Epic: stable agent identity and mutable presentation metadata

[schickling-assistant]

Goal

Give Agent Spec one stable automation identity and independently mutable presentation metadata, without restarting agents or introducing permanent compatibility paths.

This issue is the source of truth for design decisions, implementation status, rollout order, and downstream adoption.

Accepted contract

• The existing positional agent "<identity>" remains the stable ID.
• Stable ID alone owns bus routing, supervisor edges, task IDs, selectors, durable state paths, resources, telemetry identity, authorization, and lifecycle reconciliation.
• Add optional Agent Spec presentation fields:
  • name: mutable human-facing label;
  • description: enduring responsibility boundary.
• Presentation fields are non-unique and never become automation aliases.
• Agent Spec is the sole source of truth; the sibling name file is retired rather than retained as an override or compatibility projection.
• A presentation-only change updates live metadata in place and preserves the process, PTY, PID, task generation, inbox, context, resources, and supervisor binding.
• st2 rename <stable-id> <name> edits canonical KDL source-preservingly; --clear removes the field. It never renames stable identity.
• The authoring command supports KDL only. TOML and JSON remain readable but are not rewritten by the CLI.
• An agent may maintain its own name and description through constrained st2 commands.
• A supervisor or operator may maintain the presentation metadata of agents within its authority.
• Nix-owned specs remain Nix-owned and are updated at their Nix source.

Compositional VRS model

The design is specified once as a stable Agent Identity and Presentation contract, then refined by separate realizations:

Agent Spec contract
  |
  +-- st2 realization
  |     +-- authority and source mutation
  |     +-- roster and JSON projection
  |     +-- no-restart reconciliation
  |     `-- PTY metadata projection
  |
  +-- PTY realization
  |     +-- stable session ID
  |     +-- mutable displayName
  |     +-- versioned durable agent tags
  |     `-- metadata-change events
  |
  `-- eval evidence
        +-- contract conformance
        `-- cross-layer continuity

Each realization refines the parent contract and does not redefine stable identity or presentation semantics.

PTY dependency and projection

PTY should align to the same stable-ID/display-name model:

• duplicate display names are allowed;
• an exact stable-ID reference wins;
• one display-name match resolves;
• multiple display-name matches fail closed and print candidate stable IDs;
• the rule applies consistently to every command that accepts a session reference.

st2 must project the complete Agent Presentation envelope to PTY metadata with one representation per concept:

• stable task identity remains PTY's immutable native ID;
• every managed PTY receives agent.presentation.schema=1 and agent.actor.path=<host>.<identity>;
• name maps only to the primary agent PTY's native displayName and is not duplicated into a tag;
• secondary task PTYs retain their task-specific presentation;
• description maps to the optional agent.presentation.description tag on every managed PTY;
• field removal clears the corresponding owned metadata rather than leaving stale values;
• repeated reconciliation is idempotent;
• projection changes emit inspectable metadata events and do not restart the PTY.

st2 applies the desired display name and owned tag patch through one exact-ID-only atomic PTY metadata operation. Presentation metadata is never a selector or authorization input.

Current activity boundary

Agent Spec intentionally has no summary or other current-activity field. Current activity, progress, plan steps, blockers, and next work belong to future cmp/Compass plan integration. #128 introduces no compatibility alias or temporary projection for them.

Presentation validation

• name: at most 160 Unicode scalar values.
• description: at most 1,000 Unicode scalar values.
• Explicit values must be non-empty, trimmed, single-line, and free of control characters.
• Omission represents absence; CLI --clear removes the field.
• Concise naming and prose remain authoring guidance rather than schema constraints, so they can be tuned without a schema break.

Atomic PTY metadata API

The low-level automation surface is pty metadata patch --id <stable-id>, with one JSON merge patch read from stdin:

{
  "displayName": "Runtime Audit",
  "tags": {
    "agent.presentation.schema": "1",
    "agent.actor.path": "host.runtime-audit",
    "agent.presentation.description": "Audits runtime requirements and validation evidence."
  }
}

• omitted field/key: unchanged;
• string: set;
• null: clear;
• exact stable-ID lookup only, with no display-name fallback;
• one locked read/merge/validation and one atomic metadata write;
• unrelated tags are preserved;
• no effective delta performs no write and emits no event;
• an effective delta emits one coherent metadata_change event.

Human pty rename and pty tag remain simple wrappers over the same internal mutation engine.

Compatibility boundary

• Epic: stable agent identity and mutable presentation metadata #128 is additive: positional and child identity, TOML/JSON identity, and roster JSON identity remain supported and keep their current meanings.
• Epic: stable agent identity and mutable presentation metadata #128 does not rename the public wire field to id and does not reject the existing declaration grammar.
• Any future version-gated grammar or wire vocabulary break belongs to Define Agent Spec schema versioning and compatibility semantics #127.
• The sibling name side file is removed because it is a competing source, not because the stable identity grammar changes.

Publisher and safety constraints

• Self-maintenance is an explicit, narrow metadata capability enforced by st2; prompt prose is not an authorization boundary.
• Stable identity, supervisor edges, resources, launch configuration, and publisher regime remain outside self-maintenance authority.
• Nix-owned specs remain Nix-owned. Their presentation metadata is changed in Nix, not by mutating the rendered catalog.
• Mutable catalog specs may use the constrained CLI once its ownership and concurrency contract is accepted.
• Source-preserving whole-file mutation must not overwrite concurrent supervisor changes; the implementation needs an atomic compare-and-swap or equivalent conflict check.
• Presentation text must be bounded and must not include secrets or become a second current-work authority.

Rollout order

1. VRS: accept the compositional contract and repository refinements.
2. PTY: duplicate labels, ambiguity diagnostics, and mutable tag/metadata projection support.
3. st2: Agent Spec fields, constrained source-preserving authoring, roster projection, and in-place PTY reconciliation.
4. evals: model-free no-restart, routing, ambiguity, metadata propagation, authorization, migration, and lifecycle controls.
5. Deploy compatible PTY and st2 binaries.
6. Nix emitter and Nix-owned metadata.
7. Cohort adoption of mutable catalog specs, preserving stable IDs.
8. Agent rules: define naming/description quality and narrowly scoped maintenance obligations.

There is no feature-detection fallback or dual source of truth. Existing agents remain live throughout rollout; presentation fields are authored only after compatible PTY and st2 binaries are deployed.

Runtime acceptance proof

Before catalog adoption, snapshot every active PTY as (stable task ID, PID, createdAt). After each cohort require:

• identical stable task IDs, PIDs, creation timestamps, and generation count;
• updated display metadata and complete current tag projection;
• removed source fields produce removed display metadata/tags;
• unchanged identity, supervisor edges, workspace, argv, env, render blocks, and durable state paths;
• no replacement, restart, or duplicate process event.

Controls must also prove that a genuine lifecycle change still follows normal replacement semantics and that a stable-ID change is a distinct identity.

Workstreams

• Cross-repository contract and downstream catalog audits.
• Self-maintenance authority model selected.
• Johannes accepted the compositional VRS contract and requirement changes.
• PTY allows duplicate display names and reports ambiguous references with stable-ID candidates (pty#139).
• PTY/st2 use one exact-ID-only atomic display-and-tag patch with a coherent event and idempotent no-op behavior (pty#142); head 0deb3f0 merged as 504ac73. Build, typecheck, and 117/117 focused tests pass.
• st2 parses and validates name and description, including U+2028/U+2029 rejection and Unicode-scalar bounds (st2#136).
• st2 excludes presentation-only changes from lifecycle identity (st2#136).
• st2 reconciles live PTY display metadata and tags without restart (st2#136); head 70729a3 merged as 96a7351.
• st2 rename performs constrained, source-preserving canonical-KDL mutation (st2#136).
• st2 describe performs the same constrained, source-preserving mutation for descriptions (st2#136).
• Roster and JSON surfaces expose stable ID separately from presentation fields (st2#136).
• Evals prove unchanged runtime generation and durable state across presentation changes at head b9226b9 (evals#70); strengthened contract 9/9 and continuity 6/6 pass.
• Evals prove complete PTY description-tag/event propagation, clearing, idempotence, and large-boundary event behavior (evals#70).
• Evals prove ID-only routing and duplicate-name ambiguity behavior (evals#70).
• Evals prove self/supervisor authorization and Agent Spec concurrent authoring, with PTY daemon/external-writer contention covered by final PTY proof (evals#70).
• Publish the post-merge st2 release, repin evals, and run the full corpus against the immutable pin.
• Nix emitter supports name and description, rejects summary, preserves the Nix ownership marker, and projects the exact PTY presentation contract; the final aarch64 catalog check is green.
• A disposable projection of the then-current 54-seat catalog carries reviewed candidate names and descriptions, preserves the exact one-root/53-edge supervisor tree, and validates with 54 agents, zero errors, and zero warnings. Removing only name and description reproduces every source declaration byte-for-byte.
• Full-catalog scope experiments on that 54-seat snapshot establish workspace as the existing durable source: 54/54 declarations carry it; 53 seats resolve across 30 Git worktrees with exact repository/branch agreement; the remaining root is intentionally internal. No declaration in the snapshot carries duplicated scope fields or a worktree Resource.
• Downstream mutable Agent Specs are adopted and renamed where useful without changing IDs.
• Naming and description guidance is defined and validated by the authoring-skill check.
• Hosted-agent rules require source-owned metadata maintenance without making presentation an automation alias.

Current execution

• PTY duplicate-name prerequisite pty#139 is merged at 582519f.
• PTY atomic metadata patch pty#142 is merged: head 0deb3f0, merge commit 504ac73.
• st2 Agent Spec presentation implementation st2#136 is merged: head 70729a3, merge commit 96a7351.
• Eval evidence evals#70 remains open and ready for review at b9226b9. The post-merge st2 release, portable pin update, and full-corpus run remain pending.
• Downstream dotfiles repinned the merged st2 revision in commit 6d32603d8.
• Catalog adoption has not started for mutable declarations: the live catalog has 57 active Agent Specs, four Nix-owned specs with complete presentation metadata, and 53 mutable specs without it.
• Fractal presentation propagation is integrated and pushed on the canonical dotfiles branch at c00519db6, on top of the peer sidebar/pane milestone. The combined canonical state passes 20 focused tests, the full 462/0/1 suite, formatting, and diff checks. The independently verified candidate has the same stable patch ID and passes nix build .#fractal --no-link; that build was not repeated on the canonical peer-integration commit while the shared Nix-daemon incident was active.

Merge/activation gates:

1. Publish the post-merge st2 release and repin evals to its immutable artifact.
2. Run the full eval corpus against that pin.
3. Confirm compatible runtime deployment before mutable-catalog adoption.
4. Adopt mutable catalog cohorts while preserving every active PTY incarnation and durable state.
5. Complete the remaining Fractal VRS scope-qualification contract and verify the exact final revision after the shared Nix-daemon incident clears.

Catalog snapshot

The current verified live catalog contains 57 active Agent Specs. Four Nix-owned specs carry complete name and description metadata; the 53 mutable specs do not yet carry presentation metadata.

The adoption pass will derive proposed metadata from durable role signals and review it by cohort; transient status, commits, incidents, and holds are not copied into descriptions.

Open decisions

• Protected VRS authoring/approval boundary across dotfiles, st2, evals, and PTY.

• Acceptance or replacement of five semantic labels inferred from stable identity rather than durable prose.

• Whether the temporary convention-first dogfood stores contextual suffixes in name before the automatic projection lands, accepting one explicit cleanup migration.

Related work

• compoundingtech/pty#139 - duplicate display names and ambiguity-safe lookup (merged)

• compoundingtech/pty#142 - atomic exact-ID metadata patch and recovery/concurrency closure (merged)

• compoundingtech/st2#136 - Agent Spec presentation and no-restart reconciliation (merged; replaces Separate stable agent identity from mutable presentation #133)

• compoundingtech/evals#70 - model-free contract and continuity evidence (open, ready for review; replaces feat(catalog): declare the authoritative PTY registry #66)

• schickling/dotfiles#1357 - separate hierarchy-scoped authority and temporary-grant design follow-up, with a minimal reproduction

• No rename verb: an agent's identity is its directory name, so renaming means abandoning its inbox, archive, and context #21 - durable identity rename problem

• Decide ownership of stable agent identity at PTY creation #64 / VRS: define runner-owned stable launch identity #80 - stable launch identity

• Add first-class display-name authoring without changing agent identity #108 / Add first-class display-name authoring #112 - current sibling-name-file authoring proposal; superseded by Agent Spec as source of truth

• docs(vrs): define Agent Spec field-change reconciliation #102 - Agent Spec field-change reconciliation draft

• Define Agent Spec schema versioning and compatibility semantics #127 - schema versioning and compatibility semantics; intentionally separate

Dogfooding rollout (proposed; no live mutation yet)

Current census: 57 active Agent Specs, four Nix-owned specs with complete presentation metadata and 53 mutable declarations without it. The earlier 54-seat disposable candidate is strict-green; no mutable declaration has been adopted yet. Mutable adoption begins only after compatible runtime deployment is confirmed.

The convention-first preview keeps the existing supervisor tree and formats a scope change in the ordinary one-line name as [repo@worktree] or [@worktree]. Width experiments show the complete label on 26/54 seats at a 120-column terminal, 48/54 at 160, and 54/54 at 200; because the responsibility precedes the suffix, clipping preserves the semantic name first. This is suitable for bounded dogfooding, not the long-term source model.

The follow-up ideal adds no persisted scope field and does not overload Resources. st2 resolves exact repository/worktree facts from declared workspace, projects them into the existing runtime context, and derives a relative display name from workspace + supervisor + name. Arbitrary offline non-canonical workspaces remain explicitly unresolved; a first-class tagged scope becomes justified only if deterministic presentation for that unsupported case becomes a requirement.

• Make Fractal consume Agent Spec name/description and PTY presentation metadata while retaining stable IDs for routing, actions, persistence, and disambiguation.
• Treat compatible runtime deployment as cohort zero and prove task ID, PID, creation time, provider session/resume identity, bus paths, and lifecycle state are unchanged.
• Pilot one genuinely active mutable leaf with exact stable-ID rename/describe operations and idempotent reconciliation.
• Roll out leaf-to-root by reviewed supervisor subtree; allow duplicate names but fail ambiguous operations closed with candidate stable IDs.
• Retire completed seats before presentation adoption instead of labeling stale declarations as active.
• Keep the Nix-owned standing seat Nix-managed; live CLI mutation must refuse it.

Allowed continuity delta: native PTY display name, st2-owned presentation tags, and one metadata-change event. No restart, generation change, routing change, or durable-state move is permitted.