Spec 146 phase 11 partial: criteria 3 and 9b unmet, and no operator pairing entry point

[pseudoseed]

Phase 11 of spec 146 merged partial in #224. Two of its acceptance criteria are unmet, and a third gap makes the client unusable by an operator at all. This issue owns them, in the shape #179 used for phase 9's partial merge, so that deferred work does not evaporate into a plan that never mentioned it.

None is a shortcut taken under time pressure: each has a named mechanism that does not exist yet, and the criteria were held open rather than redefined to match what was built.

---

Criterion 3 — live status on every row

Correct live status on every row: working, turning, blocked on a named gate, or settled.

Met: blocked on a named gate, with #128's structured question, choices and consequences rendered inline. That half comes from porch and works against the real Tower.

Unmet: working, turning and settled. Those three come from t3code's session state, and tower-server.ts passes no t3codeSnapshot to initAgentRoutes, so the registry always takes its not-provided branch. No row from a real Tower can derive to any of the three. The client states the cause once per machine rather than inventing a status.

The mechanism that is missing. AgentRouteContext.t3codeSnapshot is synchronous — (workspacePath) => T3codeThreadSnapshot — and a t3code connection is not. A production provider therefore needs:

1. A cached background subscription per workspace, so the synchronous seam can answer from the last known set of live threads rather than blocking on a socket.
2. Per-workspace t3code connection config (URL, token) that Tower does not currently hold anywhere.
3. A staleness policy for the cache, because a cached snapshot that cannot say when it was true reintroduces the defect the client's own disconnected state exists to avoid.

Held open by a test. spec-146-phase-11-production-wiring.test.ts reads the real initAgentRoutes call and asserts it passes no provider. Wiring one fails that test, which is the right place to record the change — the test's message says so.

---

Criterion 9b — a human approves a real gate from the client

A human approves a real gate from the client through Phase 6's capability path, with session id, machine and timestamp in status.yaml.

Met, end to end, on a project whose phase checks do not run: pairing → session → capability → nonce → porch, with session id, machine, stated authority and timestamp landing in a real status.yaml. Demonstrated against two live servers in apps/client/e2e/two-machines.spec.ts.

Unmet for a real project. Approving runs porch's phase checks, which for an AIR implement phase are the repository's build and test suite — minutes of work on an open HTTP request. The route therefore refuses before starting, answers PHASE_CHECKS_REQUIRED, and names the checks it will not run. An operator looking at a pr gate in the client has to leave it and use the CLI.

Why a timeout is not the mechanism. A client that gives up does not stop porch. A timeout would abandon a call that goes on to approve the gate anyway — reporting one outcome while another happened, which is the defect class this whole phase is about.

The mechanism that is missing: durable asynchronous approval.

1. Submit returns immediately with an id; porch runs the checks out of band.
2. The client polls or subscribes for that id's outcome.
3. The outcome is durable, so a client that closes and reopens learns what happened rather than re-approving.
4. It reports the same three delivery stages the synchronous path now does — written-not-committed, committed-not-pushed, and the read-back backstop — because a checks-running approval can fail to travel in exactly the same ways.

Both branches are already tested in two-machines.spec.ts — the approval and the refusal — so the gap is measured rather than assumed.

---

No operator can pair a machine

The most consequential of the three, and it is not a criterion — it is a precondition for any of them.

PairingStore.issue() has exactly two callers: apps/client/scripts/pair-dev.mjs and tests. There is no afx command a human can run to mint a pairing token. So the pairing architecture that the entire approval path depends on — the one made honest over rounds 3 to 5 of #224 — has no production entry point.

This compounds criterion 9b rather than duplicating it. Even a perfect asynchronous approval would leave the client unusable by a person, because a person cannot obtain a token to open a session in the first place. pair-dev.mjs reaches into packages/codev/src through tsx and writes apps/client/.dev-machines.json; that is developer tooling and is documented as such.

The mechanism that is missing.

1. afx pair issue [--purpose machine-credential|client-session] [--ttl <minutes>], printing the token once to a terminal and never to a log or to argv — the constraints IssuedPairingToken's own doc already states.
2. An authority recorded from the invoking operator, since issue() now requires one. The CLI is the natural place for that string to be truthful about who minted it.
3. afx pair list / afx pair revoke, because a token store an operator cannot inspect is a store they cannot audit. PairingStore.records() and release() already exist for this.
4. A documented flow that ends with a machine paired and a session opened, without any file under packages/codev/src being imported by hand.

Until this exists, the client is reachable only by whoever can run the dev script from a checkout.

---

Ownership

Phase 12 is the natural home for both: it carries the static mount that puts apps/client in front of a real server, and the snapshot provider and async approval belong beside it.

Phase 12's approved plan section currently mentions none of the three. That needs a deliberate decision by whoever owns the plan — plans are human-approved and this issue does not amend one. Flagging rather than editing.

Not in scope here

The human-presence residual on a single-uid host is documented in codev/resources/146-approval-threat-model.md and pinned by lets anything with filesystem access complete the ceremony in agent-approval-path.test.ts. It is a stated property of the design rather than unfinished work, and it is not part of this issue.

[pseudoseed]

A practice item, not phase 11 scope — routing it here so it is not lost

Adding this because #228 is what gets inlined into phase 12's spawn, and because the architect owns where lessons finally live. Move it if there is a better home.

A fixture that shares the code's false premise cannot falsify it

Four distinct instances of one mechanism in a single night, all on #224:

What was measured	Where the thing being measured was not
6,813-passing unit run quoted as evidence	its config excludes **/*.e2e.test.ts, the file the change broke
Approval backstop readScopedGate	built codev/projects/<id>/status.yaml; real dirs are <id>-<slug>, and the e2e fixture happened to name its directories for the id
A test for that backstop	drove a successful approval, which never enters the catch block, so the backstop never executed
Phase 5's statusForWorktree (earlier, same shape)	assumed one project per worktree; fixtures were single-project, real worktrees carry ~300

The path bug is not the finding. The finding is that a fixture built from the shape the code assumes agrees with the code by construction, so every test passes and nothing is falsifiable. It is the same failure as a green suite quoted for files it cannot reach: a measurement taken where the thing being measured is not present.

What would have caught each:

• Build fixtures from real-shaped data — read a directory name off codev/projects/ rather than inventing one. thread-registry.ts already does this deliberately: "a list you type is a claim, one you read is a fact."
• Or drive the fixture through the same reader production uses, so a wrong premise fails in both places at once.
• And interrogate a passing test: ask what it actually executed, not whether it went green. Three of the four above were found that way rather than by a failure.

Suggested shape

Whatever spec picks this up, the concrete deliverables are small:

1. A shared test helper that produces a project directory named the way real ones are, used by every fixture that makes one.
2. A rule, enforceable by review: a test for a fallback path must demonstrate the fallback executing, not merely that the happy path still works.
3. The suite-coverage table pattern from apps/client/README.md, generalised — it is derived and drift-guarded by suite-coverage.test.ts, and the reason it exists is that a table which can go stale reintroduces the failure it prevents, with more authority than no table.

[pseudoseed]

Two more, filed from #224 round 7 — wider than that PR, not fixed there

1. tools/codev-agent-host reaches into packages/codev/src by deep relative path

agent-host.ts imports:

import { ApprovalCapabilityStore, ApprovalNonceStore } from '../../packages/codev/src/agent-farm/lib/approval-capability.js';
import { MachineCredentialStore } from '../../packages/codev/src/agent-farm/lib/machine-credentials.js';
import { PairingStore } from '../../packages/codev/src/agent-farm/lib/pairing.js';
import { HumanPairedSessionRegistry, handleAgentRoute, initAgentRoutes } from '../../packages/codev/src/agent-farm/servers/agent-routes.js';
import { normalizeWorkspacePath } from '../../packages/codev/src/agent-farm/utils/workspace-path.js';
import { GLOBAL_SCHEMA } from '../../packages/codev/src/agent-farm/db/schema.js';

That bypasses the package's export map and couples the host to internal file layout: moving lib/pairing.ts breaks a consumer that packages/codev has no way to know about. apps/client/e2e/two-machines.spec.ts does the same for PairingStore.

It is deliberate for now — the host exists to mount the real route table over a database snapshot, and the surface it needs (AgentRouteContext, the four stores, GLOBAL_SCHEMA) is not exported by any public entry point. CI type-checks the host so the coupling fails loudly rather than silently, which was #224 round 4's fix.

The real fix is a narrow test-support entry point on @cluesmith/codev exporting exactly what a host needs, so the layout can move.

2. StateCommitFailed / StatePushFailed are only handled on the approval HTTP path

#224 introduced both so that a write which succeeded and a delivery which failed are reported as different facts — the client says "approved, but not committed / not pushed" instead of a refusal that sends a human to approve twice.

Every other writeStateAndCommit caller still throws after a successful write. There are 15 call sites in packages/codev/src/commands/porch/index.ts alone — done, gate, rollback, init, the PR recording paths, the verify-skip path — and each reports a delivery failure as though the state change did not happen.

It matters less on the CLI, where a person sees the git error text and is standing in the worktree. It matters wherever porch is driven programmatically, which is the direction spec 146 is taking it. The types exist; the handling is one path wide.

The shape of the fix: either every programmatic caller distinguishes the two, or writeStateAndCommit grows a mode where delivery failure is returned rather than thrown, so a caller cannot forget.

[pseudoseed]

Issuance and revocation have asymmetric authority, and the asymmetry runs the wrong way

Found by trying to clean up after #224, not by reading the code — the architect attempted to revoke a credential a smoke test had minted, and could not.

Minting a machine credential needs nothing but write access to the pairing store: PairingStore.issue() plus a redemption. Every agent on the host runs as the operator, so anything on the machine can do it. That residual is documented in codev/resources/146-approval-threat-model.md and pinned by lets anything with filesystem access complete the ceremony.

Revoking one requires strictly more. DELETE /api/agent/v1/machines/<name> is declared authentication: 'human-session' in agent-auth.ts, and that mode's own comment states it includes machine-credential:

human-session INCLUDES machine-credential: elevation never replaces the machine's identity, so revoking a machine fails its approval routes closed too.

So revocation needs a live machine credential and a paired session. An operator holding neither — which is the operator who just discovered an unwanted credential — gets 401 MACHINE_CREDENTIAL_REQUIRED. Tower's shared key does not satisfy it, correctly, since #224 removed that key from the client surface entirely.

The asymmetry: anything on the box can create one; only something already trusted can destroy one. That is backwards. The cheap operation should be the one that reduces access.

Concrete case, still outstanding

A pair-dev.mjs smoke test against the live Tower minted a real credential that nobody present can revoke through the API:

machine dev-check
id 9bcfb24e-4b05-4017-ba3c-e71b81f1175e
issued 2026-08-30T02:28:09Z
expires 2026-11-28T02:28:09Z (90 days)
file ~/.agent-farm/machines/857bea15ce59….json

Neither the builder nor the architect hand-deleted the file, for the same reason: state under ~/.agent-farm is not modified by hand. It is scoped to that one machine name and expires on its own in 90 days, but it exists until then.

This is the revoke half of the pairing item above

afx pair issue / list / revoke is already on this issue as the missing operator entry point. The revoke half has to work for an operator who holds nothing — a local CLI acting on the store directly, the same way issue does — or the entry point only solves the direction that was never hard.

Worth checking the same question for the approval capability: approval-capability-revoke-machine is also human-session, so a capability issued to a session that has since expired may be similarly unreachable.