jeo-code 0.12.24 → 0.12.26

package/CHANGELOG.md

@@ -9,6 +9,21 @@ The README mirrors the latest 5 entries — regenerate with `bun run changelog:s
 
 ## [Unreleased]
 
+## [0.12.26] - 2026-11-06
+
+### Fixed
+- **A read-only turn is no longer sent through three full-history retries by an unrelated writer** - the done gate counts a `bash` call as a file change when the workspace digest differs before and after it. In a shared directory (`/tmp`) a daemon heartbeat rewritten every 60 s during a 120 s `find /` flipped that digest, so a turn of `pwd`/`jeo-skill doctor` ended `UNVERIFIED` after three correction rounds (226k input tokens for `sleep 70`; the same prompt in an empty directory cost 32k). Three changes: (1) when the cwd *is* a shared scratch root (`$HOME`, `/`, a system temp dir) `bash` and `computer` calls are no longer snapshot-bracketed - the diff there cannot be attributed to one call and no project verifier exists - with one notice and `workspace: { mutation: false, skipped: "scratch" }` on the result; built-in `write`/`edit` and project directories nested inside a scratch root stay gated; (2) evidence that comes only from a shell/computer bracket ("shell-only": no built-in mutator, debug, monitor or job ran) earns one correction instead of three, counted apart from todo/hook nudges, and launch's `onBeforeDone` restatement of the gate (`MUTATION_NUDGE_PREFIX`) no longer disables that cap; (3) a passing verification now also resets the definite-mutation evidence, so a later unrelated write is judged as shell-only again. Re-run with an unrelated writer in a nested project dir: one correction, 47.8k tokens.
+
+### Changed
+- **The done gate names the paths a shell call changed** - a snapshot mismatch is diffed per path (`snapshotChangedPaths`, `formatSnapshotChange`; the snapshot now keeps a relative-path to fingerprint map, digest arithmetic unchanged) and the unverified / stale-verification messages say `the host saw these paths change: modified heartbeat.json`, so the user and model can tell the command's writes from someone else's. The note no longer suggests that replying "read-only" can clear the gate - only a passing verification does - and `workspace snapshot inconclusive` notices and `done deferred` counters show the effective limit (`1/1`).
+- **Transcripts record the workspace evidence** - each bash/computer tool result persists `workspace: { mutation, changed?, inconclusive?, skipped? }` in the session (never sent to a provider), so a rejected completion can be audited from the transcript; before, 1,221 sessions could not show which call latched the mutation flag.
+- `formatRejectedCompletion` pluralizes (`after 1 correction.`).
+
+## [0.12.25] - 2026-11-06
+
+### Changed
+- **`jeo update` no longer special-cases another tool** - the `shared global unchanged: N packages (...)` line used to list `jeopi-cli` first; it now lists every other package in plain ascending order, at most three shown.
+
 ## [0.12.24] - 2026-11-06
 
 ### Added
@@ -2757,7 +2772,9 @@ _Initial release._
 ### Added
 - Initial jeo-code agent and CLI.
 
-[Unreleased]: https://github.com/akillness/jeo-code/compare/v0.12.24...HEAD
+[Unreleased]: https://github.com/akillness/jeo-code/compare/v0.12.26...HEAD
+[0.12.26]: https://github.com/akillness/jeo-code/releases/tag/v0.12.26
+[0.12.25]: https://github.com/akillness/jeo-code/releases/tag/v0.12.25
 [0.12.24]: https://github.com/akillness/jeo-code/releases/tag/v0.12.24
 [0.12.23]: https://github.com/akillness/jeo-code/releases/tag/v0.12.23
 [0.12.22]: https://github.com/akillness/jeo-code/compare/v0.12.21...v0.12.22

package/README.ja.md

@@ -462,10 +462,10 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.26]** (2026-11-06)
+- **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
 - **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
-- **[0.12.21]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -517,10 +517,10 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.26]** (2026-11-06)
+- **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
 - **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
-- **[0.12.21]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -506,10 +506,10 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.26]** (2026-11-06)
+- **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
 - **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
-- **[0.12.21]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -460,10 +460,10 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.26]** (2026-11-06)
+- **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
 - **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
-- **[0.12.21]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.12.24",
+  "version": "0.12.26",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
 

package/src/agent/AGENTS.md

@@ -30,7 +30,7 @@ The core runtime loop, tool registry, session management, and state persistence
 | `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
 | `loop-guards.ts` | Intermediate-judgment classification (gjc ultragoal-guard parity): named `GuardState` taxonomy, `GUARD_LIMITS` thresholds, and pure classifiers (`verifierCores`/`isVerificationSignal` — recognizes wrapped verifiers such as `cd x && bun test`, env/`timeout`/`uv run`/`rtk` prefixes and `2>&1`, never pipes or `;` — `repeatHint`, `classifyDoneGate` incl. `done_stale_verification`, and `formatRejectedCompletion`, which keeps the last candidate answer under an `UNVERIFIED` marker when corrections are exhausted) consumed by `engine.ts` |
-| `workspace-snapshot.ts` | Host-side workspace fingerprint (`snapshotWorkspace`, `defaultWorkspaceSnapshotter`, `workspaceSnapshotChanged`): bounded lstat walk excluding `.git`/`.jeo`/`node_modules`, racy content hash for files modified near the bracket anchor; the engine brackets non-verifier `bash` and state-affecting `computer` calls with it so only a real workspace change counts as a mutation (snapshot error or cap counts as a mutation) |
+| `workspace-snapshot.ts` | Host-side workspace fingerprint (`snapshotWorkspace`, `defaultWorkspaceSnapshotter`, `workspaceSnapshotChanged`): bounded lstat walk excluding `.git`/`.jeo`/`node_modules`, racy content hash for files modified near the bracket anchor; the engine brackets non-verifier `bash` and state-affecting `computer` calls with it so only a real workspace change counts as a mutation (snapshot error or cap counts as a mutation); an ok snapshot keeps a relative-path fingerprint map (`snapshotChangedPaths`/`formatSnapshotChange` name what changed) and `isSharedScratchRoot` marks `$HOME`, `/` and system temp dirs where `bash`/`computer` calls are not bracketed |
 | `memory.ts` | OKF concept-bundle memory: session distill, query-aware budget injection with a **hybrid reranker ported from memsearch** — `priorityOrder` fuses two ranked channels via `reciprocalRankFusion` (RRF, k=60): lexical IDF relevance (`buildCorpusStats`/`scoreConcept`, the sparse/BM25 channel so rare discriminating terms steer retrieval) ⊕ graph proximity (`graphProximityOrder`, the local dense/semantic-neighbour channel — a hub linked from multiple query hits surfaces even with no keyword of its own); all embedding-free, deterministic, atop the failure-first tier + pinned-invariant reserved budget. Plus mid-loop `recordFailedAttempt` capture, shared `upsertConceptFile` writer, legacy MEMORY.md migration (`migrateLegacyMemory`) + `JEO_MEMORY_LEGACY` rollback toggle |
 | `memory-okf.ts` | OKF v0.1 format layer: frontmatter parse/serialize, concept IDs, conformance validation |
 | `memory-graph.ts` | Concept cross-link graph: build/expand (1-hop search), broken-link-tolerant lint, optional graphify detection |

package/src/agent/engine.ts

@@ -32,8 +32,11 @@ import { StepBudget, dynamicStepBudgetConfig, resolveStepBudgetConfig, hashSigna
 
 import { historyTokens, trimToolResultsInPlace, stripReasoningArtifactsInPlace } from "./compaction";
 import { jeoEnv } from "../util/env";
-import { GUARD_LIMITS, isVerificationSignal, verificationProducedEvidence, repeatHint, classifyDoneGate, formatRejectedCompletion } from "./loop-guards";
-import { defaultWorkspaceSnapshotter, workspaceSnapshotChanged, type WorkspaceSnapshot, type WorkspaceSnapshotter } from "./workspace-snapshot";
+import { GUARD_LIMITS, MUTATION_NUDGE_PREFIX, isVerificationSignal, verificationProducedEvidence, repeatHint, classifyDoneGate, formatRejectedCompletion } from "./loop-guards";
+import {
+  defaultWorkspaceSnapshotter, formatSnapshotChange, isSharedScratchRoot, snapshotChangedPaths, workspaceSnapshotChanged,
+  type WorkspaceSnapshot, type WorkspaceSnapshotter,
+} from "./workspace-snapshot";
 import { stripLeakedReasoningTags } from "../ai/think-tags";
 
 const MID_TASK_PROSE_RE =
@@ -411,6 +414,9 @@ export interface AgentLoopOptions {
   /** Host-side workspace fingerprint used to decide whether a bash/computer call mutated the
    *  workspace. Defaults to defaultWorkspaceSnapshotter; tests inject fakes. */
   workspaceSnapshot?: WorkspaceSnapshotter;
+  /** Directories treated as shared scratch roots (default: `$HOME`, `/`, system temp dirs). Where the cwd IS one of
+   *  these, bash/computer calls are not snapshot-bracketed. Tests inject a hermetic root instead of touching `$TMPDIR`. */
+  scratchRoots?: readonly string[];
   signal?: AbortSignal;
   events?: AgentLoopEvents;
   /** Step-budget overrides (gjc-style retry flow). `{ maxExtensions: 0 }` restores the
@@ -575,9 +581,22 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   };
   // bash/computer calls whose mutation status is decided by a workspace diff. Recognized
   // verifiers are never mutations, and observe-only computer actions are read-only.
-  const snapshotGated = (tool: string, args: Record<string, any> | undefined): boolean =>
+  // A shared scratch root ($HOME, /, the system temp dir) is written by unrelated processes (daemon heartbeats,
+  // logs, other agents) and holds no project verifier, so a snapshot diff there cannot be attributed to one shell
+  // call: bash and computer calls are not bracketed (a built-in write/edit still counts as a definite mutation).
+  // A project directory nested inside a scratch root stays gated.
+  const scratchCwd = isSharedScratchRoot(cwd, opts.scratchRoots);
+  let scratchNoted = false;
+  const snapshotCandidate = (tool: string, args: Record<string, any> | undefined): boolean =>
     (tool === "bash" && !isVerificationSignal(String(args?.command ?? args?.cmd ?? ""))) ||
     (tool === "computer" && computerActionMayAffectState(args));
+  const snapshotGated = (tool: string, args: Record<string, any> | undefined): boolean =>
+    !scratchCwd && snapshotCandidate(tool, args);
+  // Mutation evidence that came ONLY from a shell/computer snapshot bracket, kept apart from definite mutators
+  // (write/edit/eval/…): an unrelated writer in the cwd is indistinguishable from the command's own writes, so a
+  // shell-only block gets one correction (naming the paths) instead of the full budget.
+  let definiteMutation = false;
+  const shellChanges: string[] = [];
   const sandbox = currentSandboxExecution();
   const parentTools: Record<string, true> = { task: true, subagent: true, irc: true, todo: true, sandbox_request: true };
   const maxSteps = opts.maxSteps ?? 15;
@@ -703,6 +722,9 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   let verificationCycles = 0;
   let completionGraceUsed = false;
   let doneCorrections = 0;
+  // Corrections spent on a shell-only block, counted apart so an earlier todo/hook nudge cannot use up the one
+  // correction that names the changed paths.
+  let shellOnlyCorrections = 0;
   // Most recent non-empty completion candidate, kept so an exhausted gate still shows it.
   let lastCompletionCandidate = "";
   // F1 (round 4): the run-command of the most recent post-turn hook FAILURE whose
@@ -1219,11 +1241,23 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       };
       const candidate = stripLeakedReasoningTags(String(toolCalls[0].arguments?.reason ?? ""));
       if (candidate.trim()) lastCompletionCandidate = candidate;
-      const doneGate = classifyDoneGate({ ...evidence, pendingHookFailure, unmeasured: unmeasuredSnapshot ?? undefined });
+      const doneGate = classifyDoneGate({
+        ...evidence,
+        pendingHookFailure,
+        unmeasured: unmeasuredSnapshot ?? undefined,
+        shellChanged: !definiteMutation && shellChanges.length ? shellChanges.slice(-3).join(" | ") : undefined,
+      });
       const nudge = await ev.onBeforeDone?.((toolCalls[0].arguments?.reason as string) ?? "", evidence);
-      const rejection = [doneGate.block ? doneGate.message : "", nudge].filter(Boolean).join("\n\n");
+      // launch's onBeforeDone restates the mutation gate in its own words when the gate blocks; the engine's message
+      // names the paths, so the restatement is dropped and does not count as an independent reason to keep going.
+      const independentNudge = nudge && !(doneGate.block && nudge.startsWith(MUTATION_NUDGE_PREFIX)) ? nudge : "";
+      const rejection = [doneGate.block ? doneGate.message : "", independentNudge].filter(Boolean).join("\n\n");
       if (rejection) {
-        if (doneCorrections >= GUARD_LIMITS.MAX_DONE_CORRECTIONS) {
+        // Shell-only evidence (no built-in mutator succeeded) cannot tell the command's writes from an unrelated
+        // process's, so it earns one correction naming the paths; every other block keeps the full budget.
+        const shellOnlyBlock = doneGate.block && doneGate.state !== "done_hook_failing" && !definiteMutation && !independentNudge;
+        const correctionLimit = shellOnlyBlock ? GUARD_LIMITS.MAX_SHELL_ONLY_DONE_CORRECTIONS : GUARD_LIMITS.MAX_DONE_CORRECTIONS;
+        if (shellOnlyBlock ? shellOnlyCorrections >= correctionLimit : doneCorrections >= correctionLimit) {
           return finish({
             done: false,
             steps: step,
@@ -1232,9 +1266,10 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           });
         }
         doneCorrections++;
+        if (shellOnlyBlock) shellOnlyCorrections++;
         pushAssistantTurn(history, responseText, reasonBuf, artifactBuf);
         history.push({ role: "user", content: rejection });
-        ev.onNotice?.(`done deferred — completion correction ${doneCorrections}/${GUARD_LIMITS.MAX_DONE_CORRECTIONS}`);
+        ev.onNotice?.(`done deferred — completion correction ${shellOnlyBlock ? shellOnlyCorrections : doneCorrections}/${correctionLimit}`);
         step++;
         continue;
       }
@@ -1371,6 +1406,8 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       let output: string;
       let images: import("../ai/types").ImageAttachment[] | undefined;
       let mutationMayHaveOccurred: boolean | undefined;
+      let workspace: import("../ai/types").ToolResultRecord["workspace"];
+      let bracketed = false;
       if (tool === "done") {
         success = false;
         output = "Error: 'done' can only be called as the single tool invocation, not in a batch. Please send 'done' alone.";
@@ -1393,6 +1430,13 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
             success = false;
             output = preHookResult.error + (preHookResult.output ? `\n${preHookResult.output}` : "");
           } else {
+            if (scratchCwd && snapshotCandidate(tool, args)) {
+              workspace = { mutation: false, skipped: "scratch" };
+              if (!scratchNoted) {
+                scratchNoted = true;
+                ev.onNotice?.(`cwd ${cwd} is a shared scratch directory: shell and computer calls here are not checked for file changes`);
+              }
+            }
             // Taken after pre-tool hooks so hook writes are never attributed to the call.
             const before = snapshotGated(tool, args) ? await takeSnapshot() : undefined;
             try {
@@ -1423,7 +1467,16 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
               // bash/computer: the workspace diff is the sole mutation authority (overrides
               // handler flags and the catch heuristic). Both sides share one racy anchor so
               // an unchanged recently-modified file is hashed on both sides or neither.
-              mutationMayHaveOccurred = before.ok ? workspaceSnapshotChanged(before, await takeSnapshot(before.startedAtMs)) : true;
+              const after = before.ok ? await takeSnapshot(before.startedAtMs) : undefined;
+              mutationMayHaveOccurred = after ? workspaceSnapshotChanged(before, after) : true;
+              bracketed = true;
+              const failed = !before.ok ? before : after && !after.ok ? after : undefined;
+              const change = after ? snapshotChangedPaths(before, after) : null;
+              workspace = {
+                mutation: mutationMayHaveOccurred,
+                ...(mutationMayHaveOccurred && change ? { changed: formatSnapshotChange(change) } : {}),
+                ...(failed && !failed.ok ? { inconclusive: `${failed.reason}: ${failed.detail}` } : {}),
+              };
             }
             // A pre-tool hook's structured `additionalContext` rides along with the result
             // so the model sees it next to the output it concerns.
@@ -1431,7 +1484,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           }
         }
       }
-      return { success, output, images, mutationMayHaveOccurred };
+      return { success, output, images, mutationMayHaveOccurred, bracketed, workspace };
     };
 
     const WRITE_TOOLS = new Set(["write", "edit"]);
@@ -1474,7 +1527,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       }
     }
 
-    const results: { success: boolean; output: string; executed: boolean; images?: import("../ai/types").ImageAttachment[]; mutationMayHaveOccurred?: boolean }[] = Array.from(
+    const results: { success: boolean; output: string; executed: boolean; images?: import("../ai/types").ImageAttachment[]; mutationMayHaveOccurred?: boolean; bracketed?: boolean; workspace?: import("../ai/types").ToolResultRecord["workspace"] }[] = Array.from(
       { length: toolCalls.length },
       () => ({ success: false, output: "", executed: false })
     );
@@ -1563,6 +1616,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         id: idFor(idx),
         output: bodies[i],
         isError: !results[idx].success,
+        ...(results[idx].workspace ? { workspace: results[idx].workspace } : {}),
       }));
       pushAssistantTurn(history, responseText, reasonBuf, artifactBuf, toolUse);
       const resultMsg: Message = { role: "user", content: resultBlocks.join("\n\n"), toolResults };
@@ -1607,11 +1661,16 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         if (results[i].success && verificationProducedEvidence(command, String(results[i].output ?? ""))) {
           sawVerification = true;
           lastVerificationSeq = ++mutVerSeq;
-          if (!pendingHookFailure) doneCorrections = 0;
+          // A passing verification supersedes the evidence before it: what happens next is judged on its own.
+          definiteMutation = false;
+          shellChanges.length = 0;
+          unmeasuredSnapshot = null;
+          if (!pendingHookFailure) { doneCorrections = 0; shellOnlyCorrections = 0; }
         } else {
           sawVerification = false;
           if (results[i].mutationMayHaveOccurred === true) {
             sawMutation = true;
+            definiteMutation = true; // a verifier is never snapshot-bracketed: this flag came from the handler itself
             lastMutationSeq = ++mutVerSeq;
           }
         }
@@ -1619,6 +1678,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       }
       if (t === "todo" && results[i].success && doneCorrections > 0 && (!sawMutation || (sawVerification && lastMutationSeq < lastVerificationSeq)) && !pendingHookFailure) {
         doneCorrections = 0;
+        shellOnlyCorrections = 0;
       }
 
       const output = String(results[i].output ?? "").trim();
@@ -1638,19 +1698,24 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         if (results[i].success || results[i].mutationMayHaveOccurred === true) {
           sawMutation = true;
           lastMutationSeq = ++mutVerSeq;
+          if (results[i].bracketed !== true) definiteMutation = true;
+          else if (results[i].workspace?.changed) shellChanges.push(results[i].workspace!.changed!);
         }
       } else if (t === "debug" && MUTATING_DEBUG_ACTIONS[String(toolCalls[i].arguments?.action ?? "")] === true) {
         sawMutation = true;
+        definiteMutation = true;
         lastMutationSeq = ++mutVerSeq;
       } else if (t === "monitor" && String(toolCalls[i].arguments?.action ?? "").trim().toLowerCase() === "start") {
         // Starting a background monitor can mutate the workspace asynchronously;
         // read-only monitor controls (list/tail/await/cancel) do not invalidate verification.
         sawMutation = true;
+        definiteMutation = true;
         lastMutationSeq = ++mutVerSeq;
       } else if (t === "job" && String(toolCalls[i].arguments?.action ?? "").trim().toLowerCase() === "start") {
         // Starting a background shell may mutate the workspace asynchronously;
         // read-only job controls (list/tail/await/cancel) do not invalidate verification.
         sawMutation = true;
+        definiteMutation = true;
         lastMutationSeq = ++mutVerSeq;
       }
     }

package/src/agent/loop-guards.ts

@@ -36,6 +36,13 @@ export type GuardState =
  * Kept in one frozen object so the limits are discoverable and testable instead of
  * sprinkled as bare literals through the loop body.
  */
+/**
+ * Prefix of the launch-level `onBeforeDone` nudge that merely restates the mutation-verification gate. The engine's
+ * own `classifyDoneGate` already blocks (and explains) that case, so the engine must not count the restatement as an
+ * independent block — otherwise the shell-only correction cap could never apply in the interactive loop.
+ */
+export const MUTATION_NUDGE_PREFIX = "Cannot finish: a workspace mutation from this session still lacks a successful, non-stale verification.";
+
 export const GUARD_LIMITS = Object.freeze({
   /** Identical step repeats tolerated before a consolidated stop (with corrections en route). */
   MAX_REPEAT: 4,
@@ -43,6 +50,10 @@ export const GUARD_LIMITS = Object.freeze({
   MAX_FAILURES: 5,
   /** Rejected completion attempts that may request a correction before stopping incomplete. */
   MAX_DONE_CORRECTIONS: 3,
+  /** Same, when the only mutation evidence is a shell/computer snapshot bracket (no built-in mutator
+   *  succeeded). An unrelated process writing in the cwd looks identical to the command's own writes, so
+   *  one correction states the paths and asks for verification; a second full-history retry only burns tokens. */
+  MAX_SHELL_ONLY_DONE_CORRECTIONS: 1,
   /** Context-mutating refusal-ladder rungs (resend → reset → guidance strip) before
    *  recovery switches to unbounded backoff resends (gjc parity: never terminal). */
   MAX_REFUSAL_RETRIES: 3,
@@ -185,7 +196,7 @@ export const UNVERIFIED_MARKER = "UNVERIFIED";
  * model's last candidate answer, never presents it as accepted, and keeps the gate reason.
  */
 export function formatRejectedCompletion(candidate: string, corrections: number, rejection: string): string {
-  const stop = `Stopped: completion rejected after ${corrections} corrections. ${rejection}`;
+  const stop = `Stopped: completion rejected after ${corrections} correction${corrections === 1 ? "" : "s"}. ${rejection}`;
   const answer = candidate.trim();
   if (!answer) return stop;
   return `${UNVERIFIED_MARKER} - the completion gate did not accept this answer; treat it as unconfirmed.\n\n${answer}\n\n${stop}`;
@@ -239,6 +250,11 @@ export interface DoneGateInput {
    * instead of claiming files were modified.
    */
   unmeasured?: string;
+  /**
+   * Paths a shell call's before/after snapshot saw change (`modified a.json; added b.txt`), when the evidence
+   * came from a shell bracket. Lets the model and user judge whether the command or an unrelated process wrote them.
+   */
+  shellChanged?: string;
 }
 
 /** Verdict from {@link classifyDoneGate}: whether to bounce `done`, and the message. */
@@ -263,10 +279,15 @@ export function classifyDoneGate(input: DoneGateInput): DoneGateVerdict {
   const stale = input.sawVerification && input.verificationStale === true;
   const block = input.sawMutation && (!input.sawVerification || stale || hookFailing);
   if (!block) return { state: "done_ok", block: false, message: "" };
-  const unmeasuredNote = input.unmeasured
-    ? ` Note: the host could not measure a shell call's effect on the workspace (${input.unmeasured}), so it is counted as a possible file change; ` +
-      "if every command you ran was read-only, say so in your reply."
+  // A reply alone never clears this gate: only a passing verification does, or the budget running out.
+  const escape = "Only a passing verification command clears this check; if none applies, the answer is returned labelled UNVERIFIED once the correction budget is spent.";
+  const changedNote = input.shellChanged
+    ? ` Note: around a shell/computer call the host saw these paths change: ${input.shellChanged}. ` +
+      `Something other than your commands may have written them (another process, or your own background job). ${escape}`
     : "";
+  const unmeasuredNote = changedNote + (input.unmeasured
+    ? ` Note: the host could not measure a shell/computer call's effect on the workspace (${input.unmeasured}), so it is counted as a possible file change. ${escape}`
+    : "");
   if (hookFailing) {
     return {
       state: "done_hook_failing",