fix: convoy up double-logs; init exits 0 on failed root-agent bootstrap; checkDevTask never launches its tiers

[schickling-assistant]

Three of the four Stream D convoy defects, one commit each, branched off main.

⚠️ Adjacent finding, read first: #89 already contains code fixes for two of these defects

#89 is described as "agent spec + convoy's VRS", but it also carries behavioural fixes in src/doctor/suite.ts and src/up.ts for Stream D defects 1 and 4. That is very likely not widely known. It changes what belongs where, so it's the first thing to decide on:

• Defect 4 (batch pre-trust seeding) — Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 fixes it completely. Dropped here; nothing more to do.
• Defect 1 (the readiness suite never calls up) — Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 fixes it partially: 4 of the 5 affected checks. checkDevTask was missed, and because runReadinessSuite returns 0 only if every check passes, defect 1's headline symptom — a newcomer's bare convoy doctor fails by construction — survives Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 merging. This PR closes that fifth check, and only that one.

Either leave it split this way (the two PRs are conflict-free in both directions — see Verification), or pull the fifth insertion into #89 so all of suite.ts moves together and drop that commit from here. Both work; your call.

---

Fixed here

1. convoy up printed every supervisor log line twice — fix(up)

emit() wrote the human line to stderr and, in the non---json branch, wrote the same human line to stdout. For a plain convoy up both streams land on the same terminal, so every reconcile line appeared twice.

Reproduced live. convoy up <net> --once on a throwaway network, before the fix:

hosting /tmp/…/net (reconcile every 30s, cap 3 fails / 60s)
hosting /tmp/…/net (reconcile every 30s, cap 3 fails / 60s)
[convoy-up] catalog NOT declared to fabric sync — …
[convoy-up] catalog NOT declared to fabric sync — …
[convoy-up] once: reconciled … launched/spawned 0, adopted 0, …
[convoy-up] once: reconciled … launched/spawned 0, adopted 0, …
[convoy-up] stopping host; leaving 0 session(s) running — …
[convoy-up] stopping host; leaving 0 session(s) running — …

Each line once after the fix; --json stdout is still a clean JSONL stream.

Reasoning for the stream choice: stdout carrying a copy of the human text was never useful. A caller that wants to parse the stream passes --json (stdout = JSONL); a caller that wants to read it already has it on stderr. That is also what the existing comment declared the contract to be ("the human line always goes to stderr; stdout carries the JSONL stream when --json") — the non-json stdout write contradicted it. So non-json now leaves stdout empty; --json behaviour is byte-identical. No in-repo consumer parses up's non-json stdout (the doctor suite checks .ok; backgroundUp uses stdio: "ignore").

Routing is extracted to a pure exported emitWrites(obj, human, json) so the contract is unit-testable in convoy's existing style (cf. workerCrashed). The acceptance test asserts the human line appears exactly once across both streams.

The wiring is covered too, not just the decision (see Coverage of the wiring below). emitWrites only decides what goes where; the bug lived in the code that acted on it, and that code was unreachable from a test — re-inlining the buggy writes in up() left the suite byte-identical and tsc clean. The closure is now an exported makeEmit(json, out, err) with injectable sinks, so a test drives the real emitter and counts what each stream received.

2. convoy init exited 0 after failing to create the root agent — fix(init)

cmdInit ran the CoS bootstrap, printed CoS bootstrap did not complete on a nonzero cmdCos rc, and then fell through to an unconditional return 0. A scripted convoy init && convoy up therefore saw green and proceeded against a network with an empty catalog — the root agent it just asked for never came up.

init now propagates cmdCos's rc, and on failure replaces the cheerful ✓ Network … is ready / next: run convoy doctor tail with an honest one: the structure exists, it has no agents, here is how to retry. Declining the CoS prompt — and every non-interactive run, where the branch never executes at all — still exits 0; the structure is the deliverable there. That negative control is tested.

Reproduced by test, not live — stated plainly because it matters: the CoS bootstrap is TTY-gated (interactive && await askYesNo(...)), so there is no non-interactive repro. The decision is extracted to a pure initExitCode(cosCode) and asserted red-then-green: with the old unconditional return 0 restored in place, the two new acceptance tests fail. The wiring of that function into cmdInit — that it captures cmdCos's rc, consults initExitCode, and returns the result rather than falling through to return 0 — is now held by a source guard, so reverting cmdInit to the shipped bug reds the suite. (Earlier revisions of this PR left that hop inspection-only.)

3. checkDevTask declared three tiers and never launched them — fix(doctor)

The fifth declare-then-assert check. Its add-loop declares cos + supervisor + worker, then pollUntil waits for all three to reach available — against sessions convoy add never spawned ("NOTHING launched — the catalog is desired state. Run convoy up to reconcile"). One up --once pass launches all three.

Reproduced by inspection, not live: running it end-to-end needs real agent auth and minutes of real spawning, and the missing up is unambiguous in the source (no runConvoy call site in checkDevTask invokes up). I did verify the underlying premise empirically — convoy add writes a catalog entry and leaves host.sessions() empty (see below).

Because this is a class of bug nobody was watching for, it also adds a source-level guard: the checks can't run in a unit test, but "a check that declares agents reconciles them, before it asserts liveness" is a structural invariant.

The guard derives its list of declaring checks by scanning suite.ts, and matches against comment-stripped source. Both properties are load-bearing, and an earlier revision of this PR had neither — see Coverage of the wiring below. It still carries an exception list naming the four checks whose reconcile lands in #89, so it is green today and the gap is visible in code rather than only in a PR description. That list is now stated as a shrink-only property rather than an exact-match snapshot, so it is safe to empty without breaking the suite.

---

Coverage of the wiring — what an adversarial review found, and what changed

Two of this PR's own fixes could be reverted with the suite fully green. Both are closed, each with a revert applied and restored as proof.

1. The emit and init tests covered the pure function, not the wiring. Reverting up()'s emit closure to the buggy form — writing the human line to stderr and stdout — while leaving emitWrites intact left the suite byte-identical (294 passed / 4 failed) and passed tsc. Reverting the pure function instead produced 6 failures, which is what made the gap easy to miss: the tests looked strong because they were testing the wrong half. convoy init's tail had the identical shape.

2. The doctor guard was a defeatable substring match. Replacing the reconcile with // TODO: runConvoy(box, ["up", box.net, "--once"]) -- disabled left 8/8 guard tests passing with the bug fully reopened; a comment above pollUntil( satisfied the ordering check the same way. Its hardcoded check list could only ever guard checks someone remembered to list — checkFullOrg was already a sixth declaring check absent from it — and this PR's own instruction to delete the exception list when #89 lands broke the expect(covered).toEqual(["checkDevTask"]) snapshot it shipped with.

What changed

• src/up.ts — the emit closure is now an exported makeEmit(json, out, err) with injectable sinks: the wiring itself is executed by tests.
• src/source-guard.ts (new) — gives source guards a real tokenizer: stripComments (a guard can only be satisfied by code, never by a comment), brace-matched functionBody, and exportedAsyncFunctions. It deliberately handles the shapes that silently break a naive scanner and make every downstream guard vacuous: // inside a string, and a regex literal containing quote characters — up.ts's own /ST_AGENT\s*=\s*"([^"]+)"/. It has its own tests, including the exact defeat above.
• src/doctor/suite.test.ts — the guard now derives declaring checks from suite.ts; accepts either legitimate reconcile form (up --once, or a background convoy up, which is how checkFullOrg reconciles — so it is covered rather than falsely flagged); asserts ordering non-vacuously (absence is -1, which sailed straight past toBeLessThan); and states the exception list as a shrink-only property instead of a snapshot, so deleting it widens coverage.
• src/commands.test.ts — a matching wiring guard for cmdInit.

Evidence — each revert applied, suite run, then restored

Revert	Before	After
Re-inline the buggy emit in up()	green (byte-identical, tsc clean)	2 red
makeEmit writes the human line to both streams	n/a (unreachable)	2 red
cmdInit falls through to return 0	green	1 red
Reconcile replaced by a comment naming it	green (8/8)	1 red
A new declaring check with no reconcile	invisible	1 red, no list edit needed
Empty the exception list	+1 spurious bookkeeping failure on top of the genuine ones	8 failures, all genuine (the 4 unreconciled #89 checks x 2 assertions); no bookkeeping breakage

The pre-existing 4 failures are unchanged and unrelated.

---

Dropped — defect 4, fully fixed in #89

Verified real at main: up's up-front batch pre-trust builds dirs solely from await host.sessions(), so a first-ever bring-up of freshly-declared agents contributes zero dirs and every agent falls through to the per-agent write inside nativeLaunch, racing exactly as if the batch weren't there — precisely the case the batch exists for. Observed directly: convoy add worker --identity repro-wk --dir …, then at the point up's pretrust block runs, host.sessions().length === 0.

#89 additionally seeds from readCatalog(root)'s host-filtered, non-retired entries via e.af.workspace. I checked the one thing that fix depends on — cmdAdd does persist --dir as workspace into the catalog toml (confirmed in the generated catalog/repro-wk.toml) — so #89's fix is sound, not a no-op. Nothing to add.

Also confirming the correction in the brief: up --once does pre-trust. The batch block sits before the do/while, so it runs on a one-shot pass. The earlier "doesn't pre-trust at all" report was wrong; the seeding source is the real defect.

---

Verification

• npx tsc --noEmit clean.
• npm test: 329 passed / 4 failed. The same 4 failures are present on unmodified main and are environmental, not related to these changes: 2 in doctor/hooks.test.ts (bash shim behaviour) and 2 that fail on git commit with no git identity configured in the sandbox. Net +46 tests vs main, all passing.
• Each defect's test was confirmed red against the pre-fix code before being taken green.
• No overlap with Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 — verified by dry-run merge, not just by inspection. git merge of Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89's head into this branch auto-merges up.ts and doctor/suite.ts cleanly and leaves this PR's cmdInit hunk untouched. (Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 touches up.ts only at ~209-222 vs this PR's emit at ~180; commands.ts only in cmdAdd/cmdCos/retireInCatalog vs cmdInit at ~617; suite.ts only at ~151/301/363/430 vs checkDevTask at ~536. Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 also touches none of the three test files this PR edits.) The three commits here are likewise independent of each other and revertable individually.
• Unrelated but worth knowing: that same dry-run shows Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 currently conflicts with main in src/cli.ts, src/commands.ts (cmdAdd's flag list vs the flagAllowList refactor from feat(cli): convoy completions <bash|fish|zsh>, generated from a shared command table #85) and src/role.ts. Those are Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89-vs-main conflicts that exist independently of this PR; Implement the agent spec as convoy's declaration contract, plus convoy's VRS #89 needs a rebase either way.

Draft, and deliberately no auto-merge.