Specify and evaluate transactional publication of canonical Agent Specs

[schickling-assistant]

The canonical Agent Spec thoroughly specifies accepted KDL and runtime
reconciliation, but it does not yet define the conformance boundary for an
external program that publishes generated canonical declarations into a live
folder catalog.

This matters for dynamic full seats whose policy lives outside st2:

external policy/compiler
  -> complete native Agent Spec bytes
  -> accepted canonical declaration
  -> st2 materializes/reconciles

Persona selection, harness profiles, permissions, and authorization remain
external. The accepted KDL is the runtime desired-state authority.

Concrete scenario

This public reproduction demonstrates two current lifecycle facts:

https://github.com/schickling-repros/2026-07-st2-dynamic-agent-spec-lifecycle

1. spec-shaped JSON under a seat's resource tree can be discovered as a phantom
   agent; and
2. after active KDL changes from g1 to g2 under the same task ID, st2 adopts the
   still-running g1 process.

Neither behavior means Agent Spec should absorb a higher-level SeatIntent
grammar. They do mean a conforming publisher/runtime needs explicit answers for:

• which files are declaration inputs;
• what operation commits a complete declaration generation;
• how stale concurrent writers conflict;
• how desired declaration/task generation differs from observed runtime
  generation;
• why publication is not readiness;
• why deletion is not retirement; and
• when a retired declaration may be removed while retaining native resources.

Proposed direction

Add an “external publisher and lifecycle conformance” section once the matching
st2 primitives land, keeping KDL canonical.

Normative points should include:

• a generated declaration becomes canonical only at its atomic commit point;
• exact accepted bytes have a stable publication generation/digest;
• dependencies become visible before the canonical declaration which references
  them;
• publishing does not imply materialized, running, or ready;
• an alive stable task ID does not by itself prove realization of the current
  launch definition;
• live updates are nondestructive unless an explicit replacement operation is
  requested;
• retirement is expressed with retired #true, never raw deletion; and
• removal is allowed only after runtime-backed retirement completion.

Add executable cells for:

1. partial/invalid candidates never becoming discoverable;
2. create-only and stale-generation publication conflicts;
3. resource files never becoming declarations;
4. desired/observed generation drift under stable-ID adoption;
5. supervisor replacement adopting the matching generation without duplicate
   launch;
6. retirement stopping every task before declaration removal; and
7. resource/history preservation after safe removal.

Non-goals

Do not add these to Agent Spec:

• SeatIntent;
• Nix ownership;
• PersonaContract or HarnessProfile;
• grants, delegatesTo, or workspace authorization; or
• publisher authentication policy.

Those concepts produce a complete Agent Spec but are not runtime grammar.

Sequencing

The corpus is intentionally pinned to a specific st2 commit. This issue should
track the contract/evidence direction; normative documentation and executable
cells should land with the st2 commit that implements the corresponding
publication and generation surfaces.

Related st2 directions

• st2#39: canonical folder
  discovery boundary
• st2#40: desired-versus-
  observed launch generation
• st2#41: exact-byte CAS
  publication
• st2#42: retirement-safe
  unpublication
• st2#29: targeted
  per-agent lifecycle operations

Posted on behalf of @schickling

field	value
agent_name	co2-pine
agent_session_id	cdd15622-c01a-4731-bbfe-ab8cce0cad54
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/ph8rlhdj25mg71v81jsfzy6dq4xpcs9m-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/lsykz8x5481xrpbgk280xh3pypk1c5jy-agent-skills-corpus/share/agent-skills/manifest.json
worktree	tmp
machine	dev3
tooling_profile	dotfiles@3649b53

[schickling-assistant]

The prototype/eval design has now been refined by adversarial crash,
concurrency, resident-watcher, and resource-binding experiments.

The new umbrella st2 issue is:

• Incubate a transactional content-addressed Agent Spec catalog st2#52

The key correction to the original per-file publication direction is that an
atomic agent.kdl replacement is not a sufficient catalog transaction:

catalog head -> immutable catalog-root commit
                  `-- seat -> immutable Seat Admission
                               |-- ref commit -> revision/tree/blobs
                               `-- resource-binding commit

Why:

• independently valid per-seat changes can combine into duplicate lowered task
  IDs or dangling supervisor references;
• a valid multi-seat rename/swap can have no valid first per-seat write;
• spec-first and binding-first publication both have deterministic mismatch
  windows; and
• exposing desired bytes through current st2's resident watched catalog causes
  actuation/adoption before an explicit realize boundary.

The sharpened model-free family being prepared for a draft PR is:

agent-spec-lifecycle-catalog-prepare
agent-spec-lifecycle-catalog-publish-cas
agent-spec-lifecycle-catalog-root-atomicity
agent-spec-lifecycle-catalog-root-resource-admission
agent-spec-lifecycle-catalog-crash-barriers

Each cell invokes st2 directly. There is no green compatibility shim. The
draft st2 PR will expose the minimal experimental object/root/admission API;
the eval PR will pin that branch/commit and make the cells green against the
real implementation before either is proposed for maintained-main landing.

Resident runtime generation, explicit replacement, and safe
retirement/tombstone remain separate follow-up cells linked to st2 #40/#42/#44
rather than being faked by the initial store slice.

Posted on behalf of @schickling

field	value
agent_name	co2-pine
agent_session_id	cdd15622-c01a-4731-bbfe-ab8cce0cad54
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/ph8rlhdj25mg71v81jsfzy6dq4xpcs9m-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/lsykz8x5481xrpbgk280xh3pypk1c5jy-agent-skills-corpus/share/agent-skills/manifest.json
worktree	tmp
machine	dev3
tooling_profile	dotfiles@3649b53

[schickling-assistant]

The direct-product incubation PR is open as #39, paired with
compoundingtech/st2#55 at exact prototype commit
16ee7eb953508801a4603edd056ab32f28986601.

The retained model-free family is:

• agent-spec-lifecycle-catalog-prepare - 5/0;
• agent-spec-lifecycle-catalog-publish-cas - 6/0;
• agent-spec-lifecycle-catalog-root-atomicity - 8/0.

These invoke st2 directly and cover exact-byte/no-visibility preparation,
staging replay/CAS/ABA/manager fences, genuine stale-root rejection, atomic
multi-seat admission, mixed-manager preservation, old/new-only observation,
and corruption fail-closed.

Typed resource admission and public crash-boundary injection remain future
discriminators in VRS rather than known-RED maintained cells. The PR stays
draft and does not update the accepted AGENT-SPEC.md pin.

Posted on behalf of @schickling

field	value
agent_name	co2-pine
agent_session_id	cdd15622-c01a-4731-bbfe-ab8cce0cad54
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/ph8rlhdj25mg71v81jsfzy6dq4xpcs9m-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/lsykz8x5481xrpbgk280xh3pypk1c5jy-agent-skills-corpus/share/agent-skills/manifest.json
worktree	evals/schickling-assistant/2026-07-29-content-addressed-catalog-evals
machine	dev3
tooling_profile	dotfiles@3649b53