Route spec 146 phase 9/11 findings into the governance tier (arch-critical, lessons-critical, arch)

[pseudoseed]

Facts established during spec 146 phases 9 and 11 that belong in the governance tier and are
currently recorded only in PR bodies and issues. Filed by the architect rather than folded into
#221 or #224, because routing facts by tier is MAINTAIN work and neither PR should grow a
governance edit.

For arch-critical.md (HOT — consult before deciding)

Tower is multi-workspace; process-global state in it is a cross-workspace defect.
thread-runtime.ts held a bare let engine, which is harmless in the CLI (one process, one
workspace, then exit) and a misroute in Tower, which drains held mail for every workspace in
global.db. The first thread-configured workspace pinned the socket, projectId, dispatcher and
journal for all others, and a turn dispatched to the wrong server succeeds.

The fix is now the house rule: key by canonical workspace root, and the unkeyed slot is not a
fallback in either direction. A keyed read that missed and then took the unkeyed one would
restore the bug one indirection further away. This sits alongside the existing mailbox-first fact,
because Tower being multi-workspace is the premise both depend on.

installThreadSpawnFactory is the same defect one layer up and is tracked in #227.

The CLI-awaits / Tower-does-not split is load-bearing and undefended by the type system.
ensureThreadBackendReady is CLI-only. Reaching for it from a request path reintroduces a
Tower-wide stall. The drain tick must never await an establishable resource — the synchronous
requestThreadBackend, returning a state union rather than a promise, is the pattern.

For lessons-critical.md (HOT)

The existing line — "I could not tell" must never be spelled the same way as "no" — now has
reference implementations worth naming, because the abstract rule kept being agreed with and then
violated:

• found | none | unknown (project lookup, thread-backend.ts)
• known: false only on spawn error or non-empty stderr (lsof, t3-server.mjs) — the exit code
  alone cannot separate "nothing is listening" from "I could not run the check"
• UNDETERMINED as a distinct exit (NO_DATA_TO_KEEP)
• the five-state availability enum
• UNCONFIRMED as its own client band, distinct from refused, because an unreadable 200 may mean the
  gate is approved and reporting "no" sends a human to approve twice

New lesson, earned four separate times in two days:

A green suite is evidence only about what it ran. Before quoting one, name which suites exist and
which files each covers.

Instances: a unit run that excluded *.e2e.test.ts and so could not reach the file the change
broke; a fixture that named directories the way the code assumed, so it could not falsify the
assumption; a test that passed because a successful path never entered the catch block it was
written to exercise; and a determinism test whose precondition was violated by a concurrent
porch commit (#217).

The common mechanism is a measurement taken where the thing being measured is not present.

Second new lesson: a comment asserting a guarantee stops the guarantee being checked. Four
instances in two days, each found by a reviewer going straight to the sentence:
thread-backend.ts:370 ("can only fire after…"), ownsProcess ("ownership is proven from the
command line"), validateSnapshot (claiming a distinction the code did not make), and a guard
whose stated justification did not hold. Write what makes a claim true, or write the limit —
argv heuristic, not proof of parentage is the corrected form.

For arch.md (COLD — Monorepo Structure, Integration Points)

• apps/client — the codev-client, React 19 / Vite 6 / Vitest 4 / Playwright.
• tools/codev-agent-host — mounts the route table over a copy of global.db with a scratch
  credential root; the two-server e2e harness.
• The two new agent routes: POST /api/agent/v1/human-sessions and .../gates/approve.
• Five test suites, not one: packages/codev unit, its vitest.e2e.config, its vitest.cli.config,
  apps/client unit, apps/client Playwright.

Not in scope

Do not edit codev/specs/146-*.md or the phase plans. Phase 11's unmet criteria are #228.

[pseudoseed]

Routing one finding from spec 236's post-PR review round into the governance tier.

Lesson: a guard that pins documentation text can become the thing that keeps the documentation stale.

agent-auth.test.ts asserted the remote-access runbook contained the strings Today, revoke at the host and that completePairing has no production caller. Both were true when written, and the guard existed for a good reason — to stop the runbook documenting a step nobody could follow.

Phase 11 then added POST /api/agent/v1/human-sessions as that production caller, and spec 236 added afx pair revoke. From that moment the runbook was wrong, and the test was what kept it wrong: every correct update to the prose reddened the suite, so the cheap move was always to leave it alone.

Two things generalise past this repo:

1. A check whose subject is prose has no way to notice that the world it describes has moved. The assertion is still true of the file — which is exactly why it passes.
2. The failure is invisible from inside. The guard is green and doing precisely what it was written to do; the defect is that what it was written to do stopped being desirable.

The rule that falls out: pin the property the documentation must have ("names a revocation an operator can actually perform"), never the sentence it currently uses to have it. When a claim is time-bound — "not yet", "until X lands" — assert the condition, not the wording.

Routed COLD (codev/resources/lessons-learned.md, Testing), in 9bd4caae1. The hot tier is at its cap and holds cross-cutting facts a builder needs up front; this one is needed at the moment someone writes a guard over documentation, which is narrower. Happy to be overruled on the tier.

Found by review, not by any suite — the check was working as specified the whole time.