convoy run declares, launches, and attaches (supersedes #92)

[schickling-assistant]

This supersedes the design that shipped in #92

If you read #92, read this section first — otherwise this looks like a regression.

#92 shipped convoy run as an ad-hoc session, and said so in the help text: "launch an AD-HOC session — NOT declared, NOT reconciled, NOT respawned, no durable context (declare it with add if it should survive)." This PR replaces that with the intended semantics: convoy run is exactly convoy add, plus a launch and an attach.

The verb set becomes coherent:

verb	does
add	declare (no launch)
render	materialize the overlay (no launch, no bus)
up	reconcile — launch what is declared
run	declare, launch, and attach

Why #92's reasoning does not survive

#92 argued the declared model was "not implementable honestly", on three grounds.

1. "supervisor is required for every non-root agent, so an ephemeral declaration would fabricate one and corrupt the supervision tree." — Refuted. No such field requirement exists. parseAgentFile requires only identity and role; supervisor is optional throughout. This was factually wrong.

2. "The catalog syncs union/no-delete, so a per-run entry is permanent fleet-wide garbage." — Stops being an objection under this model. The entry is not garbage: it is a declared agent that happens to have been started interactively. Permanence is the intent, not a leak. Retirement is what retired = true is for.

3. "strategy accepts only permanent." — Consistent rather than obstructive, since a run-created agent is a real declared agent. --permanent is now accepted by run (#92 rejected it with rc=2).

The deeper reason

An undeclared session has no stable identity → no durable context/ directory → it cannot externalize state or converge after a restart. That is a permanent second class of session, one that could never be promoted. Making run declare means every agent gets the same guarantees, and the ad-hoc/declared distinction disappears rather than being managed forever.

The coherence property that makes this safe

convoy up's reconcile keys liveness on the bus id <host>.<identity> (reconcile.ts agentBusId), and run launches through the very same nativeLaunch that up's reconcile uses, pinning the same identity-derived session id (writePtyToml → sessionId(spec)). So a session started by run is adopted by a concurrently-running convoy up — never double-spawned. Declaring and launching in one breath is indistinguishable, to every other verb, from add followed by up.

This was the load-bearing unknown and it was verified in the source before anything was built, not assumed.

Decisions you should push back on if you disagree

Identity: required, never generated

run now requires --identity, exactly as add does. #92 generated one (run-b3ur0v) when it was omitted.

A generated identity reintroduces precisely the hashed-name problem that makes durable context unreachable: nobody re-derives a random name on the next cold boot, so the agent can never find its own context/ again. Deriving from the role (worker-1) is worse — a counter re-derives within a parent's lifetime, so after a restart worker-2 names a different agent and reads a stranger's memory (this is #88 item 6, and #92 itself cited it as the reason its discriminator was random).

The error message explains the why, since #92 accepted the omission happily:

--identity is required. convoy run DECLARES the agent, and a declared agent needs a name you can re-derive — that is what lets its context/ survive a restart.

Attach / detach

Detaching leaves the agent running. This is free from pty's model (a session outlives its client) and it is the correct semantic here: the agent is declared, so convoy up also reconciles and respawns it. The printed notice states this rather than leaving it to be discovered — it is the exact inverse of #92's adHocNotice, which existed to disclaim these guarantees.

--no-attach covers non-interactive callers (declare + launch, return).

Already-exists: a decision table, NOT add's refuse-without---force

This is a deliberate divergence from "exactly like add", and the one place a reviewer holding me to that phrase should look:

declared	live	--force	action
no	—	—	declare + launch + attach
yes	no	no	resume from the existing declaration
yes	yes	no	attach to the running session
yes	no	yes	redeclare with these flags, then launch
yes	yes	yes	refuse → convoy reload <id>

The resume row is why. add refuses a re-declare without --force; inheriting that flatly would make re-running an identity you already declared an error — breaking the exact property this redesign exists to deliver (durable context survives a restart, so resuming is the everyday path, not a collision).

The last row refuses rather than growing a second kill-and-respawn: overwriting a live agent's declaration and relaunching would spawn a second session on the same pinned session id. convoy reload already does that job properly.

On resume/attach the existing declaration is authoritative — a stray --model must not mutate a synced, fleet-visible agent file as a side effect of attaching. Ignored flags are named out loud rather than silently dropped (staleFlagsNote), since silent ignoring is a real footgun.

Two bugs this surfaced

Liveness was keyed on the wrong host. buildDeclaration always populates host (--host ?? this machine), so keying liveness on the args-built agent file computed a this-machine bus id for an agent declared host = otherbox — whose catalog file is present locally via fabric sync. convoy run --identity <that agent> would have found nothing live and launched a duplicate alongside the real session, falsifying the coherence property above. run now reads the existing declaration before computing the bus id and keys off it, exactly as reconcile does.

The choice is a named, exported function (livenessAgentFile) rather than an inline ??, because it is the single point where the two verbs agree or diverge. Reverting it to return the args-built file turns two tests red.

One ordering bug

: buildDeclaration refused "no workspace" before knowing the agent was already declared — which would have forced callers to re-specify --dir on every resume, repeating what the catalog already knows. The check is now skipped when run is resuming an existing declaration; add keeps the hard requirement, since it only ever authors a declaration and has nothing to fall back on.

What was removed

The ad-hoc machinery is deleted, not left dormant — two models in the codebase is the thing being fixed:

• generateAdHocIdentity, adHocNotice, isAdHocIdentity, AD_HOC_PREFIX
• validateRunIdentity — note its premise inverted: it refused an identity colliding with a declared agent, and that collision is now precisely the resume case. Not dead code; wrong code. add's identityErrors covers grammar and socket-budget validation.
• --prefix and --config-dir dropped from run: the declaration carries the host prefix (--host) and the harness config dir (via env), and a per-invocation override of either would desync the session from the agent file describing it.

add and run now share buildDeclaration, so they cannot drift — enforced by a test asserting run's flag set is exactly add's plus --no-attach.

Help text updated in both cli.ts and command-table.ts; the old wording actively advertised the superseded semantics.

Tests

src/run.test.ts was rewritten rather than extended — it was entirely ad-hoc machinery. 39 tests: the decision table, the messages, command-table parity with add, and end-to-end through the real CLI against throwaway networks.

Proven red without the change: applying this test file to unmodified main gives 35 failed / 4 passed. The 4 that pass are unchanged-behavior guards (unknown flag, unknown role, identity grammar validation, table presence). Every ACCEPTANCE: test and every behavior-change test fails on baseline.

Full suite: 548 passed, with 4 pre-existing environmental failures identical to origin/main (bash-3.2 heredoc parsing in doctor/hooks, git worktree in launch/network-config). No regressions.

Reviewer notes — what I did not verify

• No live launch was exercised. Every end-to-end test runs --dry-run or --no-attach against a throwaway network. The nativeLaunch → pty attach handoff is verified by construction (I confirmed writePtyToml pins the harness session to sessionId(spec) and spawnFromPtyFile spawns under exactly that name, so the attach ref is right) but never by spawning a real harness. Production was not disturbed.
• execInteractive is new (spawn with stdio: "inherit") because exec.ts's run buffers through execFile, which would break raw mode and the detach key. Its behavior under a non-TTY stdin is untested.
• An earlier version of the host-keying test was worthless and I nearly shipped it: it asserted the printed session ref, which was derived from the existing declaration and therefore correct either way. I only caught it by reverting the fix and watching the test still pass. The replacement tests the decision directly. Worth knowing that I check tests by breaking the code, not by watching them go green.
• The megarepo worktree cut still does not happen at run time — nativeLaunch mkdirs the workspace and writes the overlay, matching what up does today (launch.ts calls megarepo worktree-cutting a follow-up). So run inherits that gap rather than fixing it; a run against a megarepo-configured network gets a plain directory where a worktree is intended, exactly as up does.