Implement the agent spec as convoy's declaration contract, plus convoy's VRS

[schickling-assistant]

Implements the agent spec as convoy's declaration contract, and adds convoy's own VRS under context/. Tracking issue: #88.

Draft on purpose — items 1–6 of #88 are here and tested; item 7 (convoy run) is not, and four known divergences are recorded rather than fixed. Details at the bottom.

Why this shape

The spec's payoff is continuity, and continuity has one prerequisite: a name that outlives the session. Everything here follows from taking that seriously.

If identity is declared and durable, then durable state can hang off it — and a session becomes disposable, because a fresh one converges on the same goal by reading what the last one wrote. That makes restart recovery a testable property instead of an aspiration. But it also puts a real cost on naming: the name is what peers address and what memory is keyed by. A cost on naming is only acceptable if a wrong choice is cheaply correctable, which is why rename is in the spine rather than in a follow-up, and why a name that convoy accepts must be one every component downstream can actually use.

What landed

Catalog in the spec format (#88 item 1). KDL, TOML, and JSON, discovered by slurping catalog/**/*.{kdl,toml,json}.

The identical-semantics claim is made structural rather than promised: all three formats decode to one canonical object, and exactly one function applies field rules. A format is supported by definition once its decoder is right. The equivalence is tested by decoding the same document three ways and asserting the results are equal — not by three parser suites that can each be individually right and collectively inconsistent.

KDL needed a node→table mapping the spec never states. The load-bearing rule: a node with one unnamed argument and children names a sub-table, so pty "agent" { … } means [pty.agent]. Without it the spec's central construct has no KDL spelling.

The spec's three examples also aren't structurally identical to each other, which I only found by trying to parse all of them: its KDL nests every field under agent "<identity>" { … } while its JSON and TOML are flat; its JSON says ptys where the others say pty; its KDL render gives dest positionally where TOML uses dest =. My first implementation followed the TOML/JSON shape and could not parse the spec's own KDL example. Convoy now accepts both spellings rather than picking a winner unilaterally — that would invalidate catalogs written against the other published example — and tests parse the published KDL verbatim, raw-string command included. Reconciling it is the lead item of the spec PR.

Identity comes from content; path segments supply defaults; a path↔content disagreement warns and content wins. Erroring would strand an agent over a directory name; silently preferring the path would make one spec mean different things in different folders.

Declare-time identity validation (item 2). The grammar is now imported from smalltalk (isAgent), not restated. The two had drifted: worker_fodfix passed convoy and was rejected by the bus, as did anything ending in -, ., or _. A second regex would just be a second chance to drift.

convoy add previously checked identity for truthiness only and never parsed, so a bad name was written into the synced catalog and propagated to every peer before anything rejected it — the failure surfaced on a different machine than the mistake, at an unrelated time. It now validates with real context: bus grammar, this network's socket budget, and the identities already declared.

Length is derived, not chosen: pty binds <PTY_ROOT>/<prefix>.<identity>.ding.sock against a 104-byte sun_path limit, so the budget is 104 − len(ptyRoot) − len(prefix) − len(".ding.sock") − 2. A network on a long path genuinely affords shorter names; the error says so rather than quoting a constant. The longest derived form is used, because a bound admitting a name the ding sidecar can't bind admits a half-working agent.

convoy rename (item 3), which moves the catalog entry and the whole bus folder.

Moving the folder wholesale is what makes in-flight mail survive — messages in inbox/ at rename time travel with it and need no special handling, precisely because it's a move and not a re-creation.

The tombstone is scoped honestly. The intent was that stale references resolve. Investigating smalltalk shows convoy cannot deliver that: smalltalk has no alias/redirect concept anywhere, and its send path validates the name then unconditionally mkdirs the inbox. So a peer holding the old name that sends after a rename doesn't fail and doesn't redirect — it manufactures a folder nobody reads. The tombstone is therefore documented as read by convoy (uniqueness, listings, rename idempotency), not by the bus, and the residual gap is DELTA-002 rather than a claimed guarantee.

Two structural details fall out of smalltalk's behavior, not taste: the tombstone is a bare dotfile with no inbox//archive//status beside it, because st agents lists a folder when any of those exist and a tombstone carrying them would resurrect the renamed-away agent in every listing; and the folder moved is the host-prefixed <host>.<identity>, since moving the bare name would move nothing and report success. Ordering is bus-first so an interrupted rename completes on re-run.

bin (item 4). Replaces the bare harness name while every derived flag survives, so a deployment that wraps its harness isn't bypassed — a convoy-managed session was running outside the boundary every other session in that deployment runs inside. Also sidesteps the closed Harness union. Charset-validated (it lands unquoted in sh -c); arguments deliberately not permitted.

Counter-discriminator guard (item 6). Refuses to seed context/ under <role>-<n>. The counter re-derives per parent lifetime, so after a restart worker-2 names a different agent and would read its predecessor's now.md as its own memory — silent, delayed, and indistinguishable from having done the work. Refused rather than warned, because a warning is read when the name is chosen and not when the wrong file is opened weeks later. fabric-2 is unaffected.

Scoped honestly, after checking: this is a strong default, not an invariant. st context write mkdir-p's context/ itself, so an agent that externalizes state makes its own regardless — verified directly. What convoy removes is the case where a renumbered successor finds a directory already waiting. Real enforcement belongs where the directory is created, which is the bus (DELTA-005).

Credentials in env, no account field. Selecting an account is selecting a config dir; a second field is a second thing to disagree. CLAUDE_CONFIG_DIR is read back out of env so the declaration and the derived manifest can't diverge. Spec env merges under derived wiring so a declared key can't repoint an agent at another bus.

Two premises I'd correct

up --once already pre-trusts (item 5). The batch is unconditional and nativeLaunch pre-trusts per-agent before spawn, so the reported one-shot hang doesn't reproduce as described. There is a real defect underneath: the batch seeded only from running sessions — exactly the agents that had already launched and didn't need it. A first-ever bring-up of N freshly-declared agents contributed zero dirs and raced the trust lost-update as if the batch weren't there. It now also seeds from the catalog, which is what names the workspaces about to be spawned.

convoy doctor's diagnosis was right, and the structural defect is fixed. It ran init → add → then polled for a live session, but add is declare-only. All five checks failed by construction on every machine. The missing up --once is inserted, making declare→reconcile→assert coherent. This depended on the item-5 finding: inserting it only helps because up --once is genuinely headless. Caveat: the suite needs live signed-in harness auth to run, so I've confirmed the structural defect is gone, not that the five checks now pass end-to-end.

VRS

context/ per the meta-spec: vision, requirements, spec, ontology, intuition, open questions, roadmap, five subsystem nodes (01-network, 02-agent-spec, 03-supervision, 04-transports, 05-doctor), seven decision records, five deltas. Consumer-agnostic — it says what convoy IS and guarantees, not how any deployment composes it.

The ontology earned its place immediately: "spec" named three different objects in existing prose — the catalog file (portable, authored), the in-memory compiled form (machine-specific), and pty's manifest (a build artifact). That conflation is most of why the layering was hard to talk about. They're now agent spec / launch spec / session manifest.

Decision records carry the tradeoff and the rejected alternative, not just the choice.

Not implemented — deliberately

• convoy run (item 7). The biggest greenfield piece, and it's not obviously additive: an ad-hoc session has no declaration, so it can't be reconciled, recovered, or adopted — it sits outside every property this VRS promises. Whether that's an acceptable escape hatch or whether it should be an ephemeral declaration is captured in open-questions.md; that fork should be settled before code.
• Supervisor never replays the manifest after provider death (Supervisor detects provider death but never replays the manifest — no recovery #82) — DELTA-001. Detection (the hard half) works; the response is missing.
• Post-rename stale sends — DELTA-002, above. Needs redirect resolution in smalltalk, which owns the send path. A convoy-side narrowing (forward resurrected tombstone folders during reconcile) is in roadmap.md.
• Reads three formats, writes one — DELTA-003. A KDL/JSON spec can be discovered and run but not retired through convoy; rename refuses explicitly, remove currently reports it as absent, which is a misleading answer about a spec it found.
• The counter-context guard is a default, not an invariant — DELTA-005, above. Needs bus-side enforcement.
• pty and render blocks are parsed but inert — DELTA-004. They round-trip so specs authored against the published format don't lose fields, but declaring a task that never runs with no error is the same silent-divergence failure mode this work exists to prevent. At minimum this wants a discovery warning.
• Convoy still writes flat catalog/<identity>.toml rather than the spec's recommended nested layout. It reads both; the nested write path touches retire/render and wasn't worth bundling.
• Cross-machine rename. The catalog syncs; the bus folder move is local to the machine running the command.
• Not addressed from Implement the agent spec as convoy's declaration contract #88's defect list: personas cloning into $HOME/src (note CONVOY_PERSONAS_DIR already exists), doubled supervisor log lines, and convoy init exiting 0 after failing to create the root agent.

Testing

npx vitest run — 73 new tests, all green. Four failures on this branch are pre-existing on main and environment-dependent (two bash-3.2 hook-parsing assertions, one git status cleanliness check, one megarepo worktree check); they fail identically on a clean main checkout here.

New suites: spec-format.test.ts (three-format equivalence + the KDL mapping), identity.test.ts (bus agreement, the socket-derived boundary, counter recognition), catalog.test.ts (tree discovery, path defaults, duplicates), rename.test.ts (durable move, in-flight mail, tombstone invisibility, re-runnability), agent-spec-file.test.ts (bin, env, pty/render parsing).

Verified end-to-end against a real network: add refuses worker_fodfix with rc=2 and names the fix; KDL and JSON specs in the nested layout are discovered with host defaulted from the path; rename --dry-run reports the move and the tombstone caveat.

Adds one runtime dependency, @bgotink/kdl — chosen for having no transitive dependencies (the alternative pulls a parser generator) in a package that otherwise has one.

Spec feedback

Implementing surfaced things worth changing upstream; happy to open a PR on agent-spec if these look right:

Opened as compoundingtech/agent-spec#1 (draft). Each item is something the implementation couldn't do, or could only do by guessing:

1. The three examples aren't structurally identical (above). Proposes the flat shape as normative; explicitly happy to go the other way, the value is in picking one.
2. The KDL mapping is unstated. [pty.<name>] has no specified KDL spelling, so implementations will differ and each still claim conformance. Adds the mapping table.
3. identity + role as the recognition rule is a footgun. A spec that omits or misspells one is silently not an agent — declared-looking, never running, no error. Changed to: either field is a claim, incomplete is a reported error.
4. env exists only at the pty level, but credential selection is agent-level and must reach every derived task; with ptys derived there's nowhere to put CLAUDE_CONFIG_DIR.
5. No bin field — the wrapped-harness case, and the only escape from the closed Harness union.
6. Identity constraints unstated — the bus grammar (with the "import, don't restate" recommendation and the worker_fodfix drift as evidence), the socket-derived length formula, and the counter-name hazard.
7. $CONVOY_NET vs CONVOY_NETWORK — flagged, not changed; as written the examples aren't copy-pasteable.

One convoy-side bug this surfaced: role = "root" — the name the spec's own field table uses — was rejected outright by convoy's role parser. Now accepted as an alias for chief-of-staff; whether the two names should coexist is left to the spec.

🤖 Generated with Claude Code