[bug] Chat tells the agent a repo is "needs_attention" and drops the sentence saying why — #405's diagnosis never reaches the model

[serge-ivo]

#405 (5527cea) exists because an agent, asked about code at a workdir that was empty and not a
checkout, was handed two non-answers describing no problem — and invented the repository. The fix
wrote a real diagnosis: one sentence, deliberately phrased "to be RELAYED: an agent can say it to
the owner verbatim and it is both true and actionable."

The chat context does not carry it. The model is told needs_attention and nothing else.

Honest — far better than the old false ready — but a bare enum token is not something an agent
can say out loud, and relaying the diagnosis was the point of the ticket.

Where

workers/api/src/agent-think.ts:493-502:

const status =
 r.cloneStatus === "ready"
 ? "ready"
 : r.cloneStatus === "cloning"
 ? "cloning…"
 : r.cloneStatus === "error"
 ? `clone error${r.cloneError ? `: ${r.cloneError}` : ""}`
 : r.cloneStatus;
systemPrompt += `- ${r.name}${r.githubRepo ? ` (${r.githubRepo})` : ""} — ${status}\n`;

CloneStatus has six values (lib/coding-types.ts:20):
unknown | cloning | ready | missing_url | error | needs_attention. The chain handles three. The
cloneError field — right there on the same object (:48) — is read on exactly one branch.

So the prompt says:

- apps/chess-academy — needs_attention

when the platform already stored, in clone_error:

The configured checkout /Users/…/apps/chess-academy exists but is EMPTY — nothing was ever
cloned into it, or its contents were moved away. There is no code at that path to read.

Mechanism

Two correct things, unjoined. verifyLocalWorkdir (routes/coding-repos.ts:104-119) persists both
halves together — updateRepoClone(env, repo.id, { cloneStatus: status, cloneError }) — and
verdictFromCheck (lib/coding-workdir.ts:73-113) writes a distinct sentence for each of
missing / not_a_directory / empty / not_a_git_repo / unverified. The prompt builder is a
ternary chain that predates the new statuses, so anything it does not enumerate falls through as
the raw token. Nothing warns: adding a CloneStatus value is type-safe against a fallthrough that
prints it.

unknown falls through the same way, and it is the other state #405 created — "no machine
connected, nobody has looked at this path" — which is a genuinely important thing for an agent to
be able to say instead of guessing.

Do — cheapest first

• Render cloneError for every non-ready status, not just error. One expression:
  append `: ${r.cloneError}` whenever it is present.
• Replace the ternary chain with a phrase table typed
  satisfies Record<CloneStatus, string>, so the next new status is a compile error rather
  than a token leaking into a prompt. That is the actual defence; the line above is the fix.
• Give needs_attention and unknown prose the model can relay — e.g.
  "UNUSABLE — <cloneError>" and "not checked (no machine connected)" — rather than the enum
  name dressed up.

A separate decision, worth stating rather than drifting into

agent-think.ts:392 reads repos through listRepos (lib/coding-store.ts:104-111), a plain
SELECT. So the chat shows the last persisted verdict, refreshed only when the console's repos
route or add-repo last ran verifyLocalWorkdir. That is probably right — a relay round-trip per
chat turn is not worth it, and the repos list re-checks on every read (capped at
MAX_VERIFY_PER_LIST = 12). But it is currently an accident rather than a decision. If it stays,
consider saying when the verdict was taken, so an agent can distinguish "it is broken" from "it
was broken when someone last looked."

Alternatives considered

• Have the prompt builder run the workdir check itself. Rejected: a relay round-trip on every
  chat turn, on the latency path, for a fact that changes rarely and is already refreshed by the
  surface the user is looking at.
• Put the sentence in memory so the agent "knows" it. Rejected outright — this is live platform
  state, and memory holding a stale copy of it is precisely the phantom-repository failure that
  repo-chat removed its mem:repository entry to escape.

Acceptance

• A unit test on the prompt builder: a repo with cloneStatus: "needs_attention" and a
  cloneError produces a line containing that sentence.
• Adding a value to CloneStatus without giving it a phrase fails typecheck.
• Asked about such a repo, the agent's reply names the path and the condition (visible in
  agent_trace) instead of the word needs_attention.

Regression risk

• Prompt length. Each sentence is ~120 characters, one per broken repo, bounded by the number
  of attached repos. Small, but if an instance has many broken repos it is now many sentences —
  consider capping at the first N and summarising the rest.
• Saying it twice. agent-think.ts:398 also calls selfDescriptionPrompt(selfModel, { repoSetting, attached })
  (lib/agent-self-description.ts:250-300), which renders attached repos for its own purpose. Check
  it before adding the sentence in a second place; the console and the chat describing one directory
  two different ways is the failure #405 explicitly designed against.

Files: workers/api/src/agent-think.ts:392,398,492-502, workers/api/src/lib/coding-types.ts:20,47-48,
workers/api/src/lib/coding-workdir.ts:43-52,73-131, workers/api/src/routes/coding-repos.ts:104-119,
workers/api/src/lib/coding-store.ts:104-111, workers/api/src/lib/agent-self-description.ts:250-300.
Related: #405 (which produced the diagnosis), #395 (the fabrication it removes the reason
for).

[serge-ivo]

Delivered — 787ece1 (+ af1dca6, the ratchet raise)

The prompt no longer prints the enum token. agent-think.ts's ten-line ternary is one call into the new pure module workers/api/src/lib/repo-status-prompt.ts, and #405's stored sentence is now what the model is handed:

- apps/chess-academy — UNUSABLE — The configured checkout `/Users/…/apps/chess-academy` exists but is
 EMPTY — nothing was ever cloned into it, or its contents were moved away. There is no code at that
 path to read.
- new-thing — not checked (no machine connected) — nobody has looked at this path, so its state is
 genuinely unknown; do not assume the code is there

Against the acceptance criteria

• Unit test on the prompt builder — repo-status-prompt.test.ts, 19 tests, including the needs_attention + cloneError case producing a line containing that sentence.
• Adding a CloneStatus value without a phrase fails typecheck — measured, not asserted. A seventh value (probe_me) was added to CloneStatus and tsc re-run: TS1360 on the satisfies Record<CloneStatus, string> plus TS7053 on the lookup. Reverted afterwards.
• cloneError renders for every non-ready status, not only error.
• The third criterion — the agent's live reply naming the path, visible in agent_trace — is not verified in production, and cannot be yet: it needs a repo actually in needs_attention, which needs the runner upgrade [bug] A local repo is marked "ready" without anyone checking it exists — an empty checkout reports success, and the agent invents the code it cannot see #405 is still open on. There is no such repo in production today.

Decisions taken rather than drifted into

The "say it twice" risk was checked and is not real. grep cloneStatus returns zero hits in agent-self-description.ts and agent-style-prompt.ts. selfDescriptionPrompt renders an attached repo only for model.singleRepo, and only as name/owner/repo/workdir — a statement of ownership. The new block is a statement of health. They compose rather than contradict, so the diagnosis stays in one place. Recorded in a comment at the call site so it is not re-litigated.

Prompt length is bounded twice. Full diagnosis for the first 6 broken repos; the remainder still gets a line and a state, and a tail sentence counts and names them so the agent cannot imply they are fine. Broken repos sort to the front, so the budget can never be spent on healthy rows. Each detail truncates at 240 chars, because verdictFromCheck embeds a runner-supplied error string of unbounded length.

Freshness: stated in prose, deliberately not timestamped. The block says the status is the LAST RECORDED verdict, not a live check. No time is rendered: updated_at is bumped by updateRepo for renames and merge-policy edits as well as by updateRepoClone, so "checked 3 minutes ago" would be a precise-looking claim the platform cannot support — the exact failure #405 exists to remove. A real clone_checked_at column would fix it properly and is a follow-up, not this ticket. A test asserts no fabricated "N minutes ago" appears. The relay-round-trip-per-turn alternative stays rejected, per the ticket.

Unrecognised statuses. clone_status is a TEXT column, so a value this build does not know can still arrive. The table makes the code path exhaustive; a runtime fallback keeps the data path honest ("state unrecognised by this build") rather than reprinting the raw token — the original bug in miniature.

Verified

pnpm typecheck clean · pnpm vitest run 6301 passed · biome clean · design tokens clean · CI green · Deploy API Worker success.

Noted, not fixed (worth its own ticket)

agent-think.ts:490 — relayConnected(...) is not individually caught, so if it throws, the enclosing try swallows it and the entire Attached Repositories block, including this diagnosis, silently vanishes from the prompt. Pre-existing and separable; deliberately not expanded into here.