jeo-code 0.12.25 → 0.12.27

package/src/agent/snapshot-target.ts

@@ -0,0 +1,188 @@
+/**
+ * Which directory the engine's before/after workspace snapshot should measure for ONE shell call.
+ *
+ * A shared scratch cwd ($HOME, `/`, a system temp dir) is never bracketed itself: unrelated processes write there, so
+ * a digest change cannot be blamed on the call. But a model often sits in such a cwd and edits a real project
+ * through it (`cd ~/work/app && sed -i …`, or a bash `cwd`/`subdir` argument), and that edit would otherwise be
+ * invisible to the done gate. This resolves the PROJECT the call is aimed at (the outermost directory with a project
+ * marker above the target, so `cd app/pkg && echo X > ../src/a.ts` measures `app`) so the bracket can measure it.
+ *
+ * Everything here fails SAFE: an unresolvable, nonexistent, scratch, marker-less or ambiguous target means "no nested
+ * target" (the caller keeps today's scratch skip), and nothing throws.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isSharedScratchRoot } from "./workspace-snapshot";
+
+/** Leading `cd a && cd b; …` hops followed at most this far; anything beyond is simply not modelled. */
+const MAX_CD_HOPS = 8;
+
+/** How far above a target the project-marker search climbs before giving up. */
+const MAX_MARKER_LEVELS = 12;
+
+/**
+ * Files/dirs whose presence says "this is a project". A nested target is bracketed only when it (or an ancestor below
+ * the scratch root) has one: `cd ~/.cache && ls` or `cd /var/log && tail x` is ambient state, not a project, and a
+ * bracket there measures unrelated churn (or hits the entry cap) instead of the call's own writes. The OUTERMOST such
+ * ancestor is the bracketed root, because a write anywhere in the project (`../src/a.ts`) belongs to the same project.
+ */
+const PROJECT_MARKERS: readonly string[] = [
+  ".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", "setup.py", "Makefile", "pom.xml",
+  "build.gradle", "build.gradle.kts", "Gemfile", "composer.json", "deno.json", "CMakeLists.txt", ".jeo",
+];
+
+/**
+ * A leading literal `cd <path>` terminated by `&&`, `;` or a newline. The path is single-quoted, double-quoted
+ * without expansion characters, or a bare token drawn from a whitelist (so `$`, backticks, globs, braces, escapes
+ * and `||`/`|`/`&` never parse): when it does not match, the hop is not modelled rather than guessed.
+ */
+const CD_HOP =
+  /^\s*cd[ \t]+(?:'([^']*)'|"([^"$`\\]*)"|([A-Za-z0-9_./~@%+:,][A-Za-z0-9_./~@%+:,-]*))[ \t]*(?:&&|;|\r?\n)/;
+
+const realOrResolved = (target: string): string => {
+  try { return realpathSync(target); } catch { return path.resolve(target); }
+};
+
+const isDirectory = (target: string): boolean => {
+  try { return statSync(target).isDirectory(); } catch { return false; }
+};
+
+const accountHomedir = (): string => {
+  try { return os.userInfo().homedir; } catch { return os.homedir(); }
+};
+
+/** True when `child` is `parent` or lies inside it (both already resolved). */
+const within = (parent: string, child: string): boolean => {
+  const rel = path.relative(parent, child);
+  return rel === "" || !(rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel));
+};
+
+/** The roots the climb must not enter and a bracketed root must not cover: the cwd plus the declared/default roots. */
+function scratchRootList(cwd: string, scratchRoots: readonly string[] | undefined): string[] {
+  return scratchRoots
+    ? [cwd, ...scratchRoots]
+    : [cwd, os.homedir(), accountHomedir(), os.tmpdir(), "/tmp", "/var/tmp"];
+}
+
+/**
+ * True when `target` is a scratch root or CONTAINS one (`/Users` above `$HOME`, `/` above everything). Bracketing an
+ * ancestor of a scratch root walks the very tree that made the root unmeasurable (a read-only `cd .. && ls` would hit
+ * the entry cap and count as a mutation), so it is skipped exactly like the root itself.
+ */
+function coversScratchRoot(target: string, roots: readonly string[]): boolean {
+  const here = realOrResolved(target);
+  return roots.some(root => within(here, realOrResolved(root)));
+}
+
+/**
+ * The OUTERMOST ancestor-or-self of `target` holding a project marker, or null. The climb stops BEFORE any scratch
+ * root (a `package.json` in `$HOME` must not turn every directory under it into a project) and at the filesystem
+ * root, and is bounded to MAX_MARKER_LEVELS. Outermost, not nearest: the deepest directory of a project (`app/pkg`,
+ * `/opt/homebrew/var/log`) sees only part of what a command can write, and a bracket on a log directory blames the call
+ * for its ambient writers; the project root is where an edit anywhere in the tree shows up.
+ */
+function projectRoot(target: string, roots: readonly string[]): string | null {
+  let current = realOrResolved(target);
+  let root: string | null = null;
+  for (let level = 0; level < MAX_MARKER_LEVELS; level++) {
+    const parent = path.dirname(current);
+    if (parent === current || isSharedScratchRoot(current, roots)) break;
+    if (PROJECT_MARKERS.some(marker => existsSync(path.join(current, marker)))) root = current;
+    current = parent;
+  }
+  return root;
+}
+
+/** The `a.env` map bash receives, reduced to the string entries the tool actually forwards. */
+function envValue(args: Record<string, any> | undefined, key: string): string | undefined {
+  const env = args?.env;
+  const own = env && typeof env === "object" && !Array.isArray(env) ? env[key] : undefined;
+  return typeof own === "string" ? own : process.env[key];
+}
+
+/**
+ * One `cd` hop from `dir`. Null when the hop cannot be resolved with certainty: `~user`, a relative path under a
+ * set `CDPATH` (bash would search elsewhere), or a target that is not an existing directory.
+ */
+function applyHop(dir: string, raw: string, quoted: boolean, args: Record<string, any> | undefined): string | null {
+  let target = raw;
+  if (!quoted && raw.startsWith("~")) {
+    if (raw !== "~" && !raw.startsWith("~/")) return null;
+    const home = envValue(args, "HOME") || os.homedir();
+    target = path.join(home, raw.slice(1));
+  } else if (
+    !path.isAbsolute(raw) && !/^\.\.?(?:\/|$)/.test(raw) && (envValue(args, "CDPATH") ?? "") !== ""
+  ) {
+    return null;
+  }
+  const next = path.resolve(dir, target);
+  return isDirectory(next) ? next : null;
+}
+
+/**
+ * The directory the snapshot bracket should measure for this ONE call.
+ *
+ * - Default: `cwd`, unchanged. A non-scratch cwd always brackets itself (targets outside it are not followed), and
+ *   so does every tool other than `bash`.
+ * - `bash` from a shared scratch cwd: resolve the effective run dir from `args.cwd ?? args.subdir` (the same
+ *   precedence the bash tool uses), then follow a LEADING literal `cd <path> &&` / `cd <path>;` chain from there.
+ *   The last existing directory reached is the TARGET; the bracketed directory is its project root (outermost
+ *   ancestor-or-self with a marker), unless that root is a scratch root or contains one.
+ *
+ * Returns `cwd` itself (same string) when there is no nested target; any other return value is the absolute real path
+ * of the project root the caller should measure instead. A directory the command creates itself does not exist yet
+ * and so yields no target — an accepted gap, since guessing a path that may never exist would measure the wrong
+ * tree. A target with no project marker (see PROJECT_MARKERS) is not a project either, and is treated like no target.
+ */
+export function snapshotTarget(
+  cwd: string,
+  tool: string,
+  args: Record<string, any> | undefined,
+  scratchRoots?: readonly string[],
+): string {
+  try {
+    if (tool !== "bash" || !isSharedScratchRoot(cwd, scratchRoots)) return cwd;
+    const sub = typeof args?.cwd === "string" ? args.cwd : typeof args?.subdir === "string" ? args.subdir : "";
+    let dir = sub ? path.resolve(cwd, sub) : cwd;
+    // The bash tool spawns in this directory; if it is missing the call fails before touching anything.
+    if (!isDirectory(dir)) return cwd;
+    let rest = String(args?.command ?? args?.cmd ?? "");
+    for (let hop = 0; hop < MAX_CD_HOPS; hop++) {
+      const m = CD_HOP.exec(rest);
+      if (!m) break;
+      const next = applyHop(dir, m[1] ?? m[2] ?? m[3], m[3] === undefined, args);
+      if (next === null) break;
+      dir = next;
+      rest = rest.slice(m[0].length);
+    }
+    const roots = scratchRootList(cwd, scratchRoots);
+    const root = projectRoot(dir, roots);
+    // The climb never enters a scratch root, but a marker above one (`/var/.git` over `/var/tmp`) still yields a
+    // root that covers it: that is as unmeasurable as the scratch root itself.
+    if (root === null || isSharedScratchRoot(root, roots) || coversScratchRoot(root, roots)) return cwd;
+    return root;
+  } catch {
+    return cwd;
+  }
+}
+
+/**
+ * The form persisted as `workspace.target`: relative to `cwd` when the target lies inside it, else the fixed token
+ * `<outside cwd>` — an absolute path outside the workspace has no business in a transcript. Compared by real path, so
+ * a cwd reached through a symlink (macOS `/tmp`) still counts as containing its own subdirectories.
+ */
+export function describeSnapshotTarget(cwd: string, target: string): string {
+  const base = realOrResolved(cwd);
+  const real = realOrResolved(target);
+  const rel = path.relative(base, real);
+  return rel !== "" && within(base, real) ? rel : "<outside cwd>";
+}
+
+/** Human-facing name for notices: the relative path inside `cwd`, otherwise only the directory's basename. */
+export function snapshotTargetLabel(cwd: string, target: string): string {
+  const base = realOrResolved(cwd);
+  const real = realOrResolved(target);
+  const rel = path.relative(base, real);
+  return rel !== "" && within(base, real) ? rel : path.basename(real);
+}

package/src/agent/workspace-snapshot.ts

@@ -1,7 +1,8 @@
 /**
  * Host-side workspace fingerprint. The engine brackets bash/computer calls with two snapshots and
- * counts the call as a mutation only when they differ (workspaceSnapshotChanged). Failures and caps
- * are reported as `ok:false`, which always counts as a mutation (safe side).
+ * counts the call as a mutation only when they differ (workspaceSnapshotChanged). A snapshot that
+ * cannot be taken is `ok:false` and always counts as a mutation (safe side): an unreadable ROOT, the
+ * entry/time caps, and any readdir/lstat/readlink error not listed under "degraded" below.
  *
  * Entry strings folded into an order-independent digest:
  * - directory: `d:<rel>` (presence only; directory mtimes are ignored so creating an excluded
@@ -11,11 +12,31 @@
  *   - regular file with mtime >= anchor - racyWindowMs: `:h<wyhash(content)>` (racy-clean guard
  *     against coarse timestamps; the after-snapshot reuses the before-snapshot's anchor)
  *   - FIFO/socket/device: stat only, never opened
+ *
+ * Degraded entries keep the snapshot `ok:true`; `degraded` counts them. Both cases lose nothing
+ * attributable to a command, so they must not make every bash call look mutating:
+ * - a NON-root directory whose listing is denied (EACCES/EPERM): it is keyed
+ *   `u:<rel>:<mode>:<ctimeNs>:<ino>` (lstat of the directory itself) instead of `d:<rel>` (replacing
+ *   it in the digest and the path map) and its children are skipped. A same-user process CAN change
+ *   such a directory (chmod it open, write, chmod it shut), but every entry creation/removal/rename
+ *   inside it and every chmod updates the directory's own ctime, and the mode is recorded, so the
+ *   marker flips; so does becoming listable. ENOENT/ENOTDIR (vanished) is skipped as before; any
+ *   other readdir code stays a failure. Residual, verified only for the cases above: a change that
+ *   leaves mode, ctime and inode identical (e.g. a rewrite of an existing child's CONTENT inside a
+ *   `-wx` directory does not touch the directory's ctime) is not seen.
+ * - a racy regular file that is over racyMaxFileBytes, would push the hashed total over
+ *   racyMaxTotalBytes, cannot be opened/read, or changes while being read: stat-only fingerprint plus
+ *   `:x` (unhashed). Racy files are hashed after the walk in path order, first-fit against the total
+ *   budget, so the before and after snapshots of an unchanged workspace hash the same files.
+ *   Residual risk: a same-size rewrite of such a file inside one timestamp tick of the bracket anchor
+ *   goes unseen. Nanosecond mtime/ctime (APFS, ext4) make that negligible; files within the caps are
+ *   still content-hashed.
  */
 import * as fs from "node:fs/promises";
-import { constants } from "node:fs";
+import { constants, realpathSync } from "node:fs";
 import type { BigIntStats, Dirent } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 
 export interface WorkspaceSnapshotLimits {
@@ -25,7 +46,8 @@ export interface WorkspaceSnapshotLimits {
   maxMs: number;
   /** Files with mtime within this window of the snapshot start are content-hashed too. */
   racyWindowMs: number;
-  /** Per-file and per-snapshot byte caps for racy content hashing. */
+  /** Per-file and per-snapshot byte caps for racy content hashing. A file over either cap is not
+   *  hashed: it degrades to a stat-only `:x` entry (the total bounds hashing work, first-fit). */
   racyMaxFileBytes: number;
   racyMaxTotalBytes: number;
 }
@@ -42,7 +64,14 @@ export const WORKSPACE_SNAPSHOT_LIMITS: Readonly<WorkspaceSnapshotLimits> = Obje
 export const WORKSPACE_SNAPSHOT_EXCLUDED_DIRS: ReadonlySet<string> = new Set([".git", ".jeo", "node_modules"]);
 
 export type WorkspaceSnapshot =
-  | { ok: true; digest: bigint; entries: number; elapsedMs: number; startedAtMs: number }
+  | {
+      ok: true; digest: bigint; entries: number; elapsedMs: number; startedAtMs: number;
+      /** Entries recorded without full fidelity (unlistable directory, unhashed racy file). */
+      degraded?: number;
+      /** Relative path -> entry fingerprint, so a mismatch can name WHICH paths changed
+       *  (`snapshotChangedPaths`). Optional so hand-built snapshots and mocks stay valid. */
+      paths?: ReadonlyMap<string, bigint>;
+    }
   | { ok: false; reason: "error" | "cap"; detail: string };
 
 /** `racySinceMs`: anchor for the racy content-hash predicate. The engine passes the BEFORE snapshot's
@@ -75,6 +104,8 @@ async function chunked<T>(items: readonly T[], run: (item: T) => Promise<void>):
 
 interface Dir { rel: string; abs: string }
 interface Leaf extends Dir { dirent: Dirent }
+/** A racy file waiting for the post-walk hashing pass. */
+interface RacyCandidate { leaf: Leaf; stat: BigIntStats; entry: string; hashable: boolean }
 
 export async function snapshotWorkspace(
   cwd: string,
@@ -87,26 +118,31 @@ export async function snapshotWorkspace(
   const racyThresholdNs = BigInt(Math.floor(anchorMs - limits.racyWindowMs)) * 1_000_000n;
   let digest = 0n;
   let entries = 0;
-  let racyBytes = 0;
+  let degraded = 0;
 
-  const record = (entry: string): void => { digest = (digest + Bun.hash.wyhash(entry)) & DIGEST_MASK; };
+  const paths = new Map<string, bigint>();
+  const record = (entry: string, rel: string): void => {
+    const hash = BigInt(Bun.hash.wyhash(entry));
+    // A path recorded twice (the `u:` marker over its directory's `d:` entry) replaces the first, so
+    // digest stays the sum of the path map. BigInt `&` on a negative value wraps as two's complement.
+    digest = (digest - (paths.get(rel) ?? 0n) + hash) & DIGEST_MASK;
+    paths.set(rel, hash);
+  };
   const checkCaps = (): void => {
     if (entries > limits.maxEntries) stop("cap", `workspace has more than ${limits.maxEntries} entries`);
     if (performance.now() - startedAt > limits.maxMs) stop("cap", `workspace snapshot exceeded ${limits.maxMs} ms`);
   };
 
-  /** Bounded read of a regular file's content; `null` when it vanished before it could be read. */
-  const racyHash = async (leaf: Leaf, stat: BigIntStats): Promise<bigint | null> => {
+  /** Bounded content hash of a regular file. `"gone"`: vanished before it could be opened. `"unhashed"`:
+   *  any other failure (permissions, swapped inode, grew or errored while read); the caller degrades. */
+  const racyHash = async (leaf: Leaf, stat: BigIntStats): Promise<bigint | "gone" | "unhashed"> => {
     const size = Number(stat.size);
-    if (size > limits.racyMaxFileBytes) stop("error", `racy file too large: ${leaf.rel} (${size} bytes)`);
-    racyBytes += size;
-    if (racyBytes > limits.racyMaxTotalBytes) stop("error", `racy files too large: more than ${limits.racyMaxTotalBytes} bytes`);
     let handle: FileHandle;
     try { handle = await fs.open(leaf.abs, RACY_OPEN_FLAGS); }
-    catch (error) { if (vanished(error)) return null; return stop("error", `cannot open ${leaf.rel}: ${errorMessage(error)}`); }
+    catch (error) { return vanished(error) ? "gone" : "unhashed"; }
     try {
       const opened = await handle.stat({ bigint: true });
-      if (!opened.isFile() || opened.ino !== stat.ino || opened.dev !== stat.dev) stop("error", `file changed during workspace snapshot: ${leaf.rel}`);
+      if (!opened.isFile() || opened.ino !== stat.ino || opened.dev !== stat.dev) return "unhashed";
       // One spare byte detects growth after lstat without reading past the cap.
       const buffer = new Uint8Array(size + 1);
       let read = 0;
@@ -114,14 +150,39 @@ export async function snapshotWorkspace(
         const { bytesRead } = await handle.read(buffer, read, buffer.length - read, read);
         if (bytesRead === 0) break;
         read += bytesRead;
-        if (read > size) stop("error", `file changed during workspace snapshot: ${leaf.rel}`);
+        if (read > size) return "unhashed";
       }
       return Bun.hash.wyhash(buffer.subarray(0, read));
+    } catch {
+      return "unhashed";
     } finally {
       await handle.close().catch(() => {});
     }
   };
 
+  /** Racy files are collected during the walk and hashed afterwards in path order (see header). */
+  const racy: RacyCandidate[] = [];
+  const hashRacy = async (): Promise<void> => {
+    racy.sort((a, b) => (a.leaf.rel < b.leaf.rel ? -1 : 1));
+    let racyBytes = 0;
+    for (const candidate of racy) {
+      const size = Number(candidate.stat.size);
+      candidate.hashable = size <= limits.racyMaxFileBytes && racyBytes + size <= limits.racyMaxTotalBytes;
+      if (candidate.hashable) racyBytes += size;
+    }
+    await chunked(racy, async candidate => {
+      checkCaps();
+      const hash = candidate.hashable ? await racyHash(candidate.leaf, candidate.stat) : "unhashed";
+      if (hash === "gone") { entries -= 1; return; }
+      if (hash === "unhashed") {
+        degraded += 1;
+        record(`${candidate.entry}:x`, candidate.leaf.rel);
+        return;
+      }
+      record(`${candidate.entry}:h${hash}`, candidate.leaf.rel);
+    });
+  };
+
   const fingerprint = async (leaf: Leaf, queue: Dir[]): Promise<void> => {
     let stat: BigIntStats;
     try { stat = await fs.lstat(leaf.abs, { bigint: true }); }
@@ -132,7 +193,7 @@ export async function snapshotWorkspace(
     if (stat.isDirectory()) {
       // Unreported or raced dirent type: a real directory is never fingerprinted by metadata.
       if (WORKSPACE_SNAPSHOT_EXCLUDED_DIRS.has(leaf.dirent.name)) { entries -= 1; return; }
-      record(`d:${leaf.rel}`);
+      record(`d:${leaf.rel}`, leaf.rel);
       queue.push(leaf);
       return;
     }
@@ -145,19 +206,32 @@ export async function snapshotWorkspace(
         return stop("error", `cannot read link ${leaf.rel}: ${errorMessage(error)}`);
       }
     } else if (kind === "f" && leaf.dirent.isFile() && stat.mtimeNs >= racyThresholdNs) {
-      const hash = await racyHash(leaf, stat);
-      if (hash === null) { entries -= 1; return; }
-      entry += `:h${hash}`;
+      racy.push({ leaf, stat, entry, hashable: false });
+      return;
     }
-    record(entry);
+    record(entry, leaf.rel);
   };
 
   const list = async (dir: Dir, next: Dir[], leaves: Leaf[]): Promise<void> => {
     let dirents: Dirent[];
     try { dirents = await fs.readdir(dir.abs, { withFileTypes: true }); }
     catch (error) {
-      if (dir.rel !== "" && vanished(error)) return;
-      return stop("error", `cannot read directory ${dir.rel || "."}: ${errorMessage(error)}`);
+      if (dir.rel === "") return stop("error", `cannot read directory .: ${errorMessage(error)}`);
+      if (vanished(error)) return;
+      const code = (error as NodeJS.ErrnoException | undefined)?.code;
+      if (code === "EACCES" || code === "EPERM") {
+        // chmod-open/write/chmod-shut leaves the same mode but a newer ctime, so identity must be part of the marker.
+        let stat: BigIntStats;
+        try { stat = await fs.lstat(dir.abs, { bigint: true }); }
+        catch (statError) {
+          if (vanished(statError)) return;
+          return stop("error", `cannot stat ${dir.rel}: ${errorMessage(statError)}`);
+        }
+        degraded += 1;
+        record(`u:${dir.rel}:${stat.mode}:${stat.ctimeNs}:${stat.ino}`, dir.rel);
+        return;
+      }
+      return stop("error", `cannot read directory ${dir.rel}: ${errorMessage(error)}`);
     }
     for (const dirent of dirents) {
       const rel = dir.rel ? `${dir.rel}/${dirent.name}` : dirent.name;
@@ -165,7 +239,7 @@ export async function snapshotWorkspace(
       if (dirent.isDirectory()) {
         if (WORKSPACE_SNAPSHOT_EXCLUDED_DIRS.has(dirent.name)) continue;
         entries += 1;
-        record(`d:${rel}`);
+        record(`d:${rel}`, rel);
         next.push(child);
       } else {
         entries += 1;
@@ -192,7 +266,9 @@ export async function snapshotWorkspace(
       }
       level = next;
     }
-    return { ok: true, digest, entries, elapsedMs: performance.now() - startedAt, startedAtMs };
+    await hashRacy();
+    checkCaps();
+    return { ok: true, digest, entries, degraded, elapsedMs: performance.now() - startedAt, startedAtMs, paths };
   } catch (error) {
     if (error instanceof SnapshotStop) return error.result;
     return { ok: false, reason: "error", detail: errorMessage(error) };
@@ -207,3 +283,66 @@ export function workspaceSnapshotChanged(before: WorkspaceSnapshot, after: Works
   if (!before.ok || !after.ok) return true;
   return before.digest !== after.digest || before.entries !== after.entries;
 }
+
+/** Result of comparing two snapshots path by path (sorted, relative to the workspace root). */
+export interface SnapshotPathChange {
+  added: string[];
+  removed: string[];
+  modified: string[];
+}
+
+/**
+ * Paths that differ between two successful snapshots. Null when either side cannot say (a failed
+ * snapshot, or a hand-built one without a per-path map) — callers then fall back to the bare
+ * digest verdict. Directories are reported by name too; their mtimes are not fingerprinted.
+ */
+export function snapshotChangedPaths(before: WorkspaceSnapshot, after: WorkspaceSnapshot): SnapshotPathChange | null {
+  if (!before.ok || !after.ok || !before.paths || !after.paths) return null;
+  const added: string[] = [];
+  const modified: string[] = [];
+  const removed: string[] = [];
+  for (const [rel, hash] of after.paths) {
+    const prev = before.paths.get(rel);
+    if (prev === undefined) added.push(rel);
+    else if (prev !== hash) modified.push(rel);
+  }
+  for (const rel of before.paths.keys()) if (!after.paths.has(rel)) removed.push(rel);
+  return { added: added.sort(), removed: removed.sort(), modified: modified.sort() };
+}
+
+/** `modified a/b.json; added c.txt (+3 more)` — at most `limit` paths, for notices and gate messages. */
+export function formatSnapshotChange(change: SnapshotPathChange, limit = 5): string {
+  const items = [
+    ...change.modified.map(p => `modified ${p}`),
+    ...change.added.map(p => `added ${p}`),
+    ...change.removed.map(p => `removed ${p}`),
+  ];
+  if (items.length === 0) return "no path-level difference";
+  const shown = items.slice(0, limit).join("; ");
+  return items.length > limit ? `${shown} (+${items.length - limit} more)` : shown;
+}
+
+const realOrResolved = (target: string): string => {
+  try { return realpathSync(target); } catch { return path.resolve(target); }
+};
+
+function accountHomedir(): string {
+  try { return os.userInfo().homedir; } catch { return os.homedir(); }
+}
+
+function defaultScratchRoots(cwd: string): string[] {
+  // `os.homedir()` / `os.tmpdir()` follow $HOME / $TMPDIR, so the account's real home is listed too.
+  return [os.homedir(), accountHomedir(), path.parse(path.resolve(cwd)).root, os.tmpdir(), "/tmp", "/var/tmp"];
+}
+
+/**
+ * True when `cwd` IS a shared scratch root — `$HOME`, the filesystem root, or a system temp directory —
+ * rather than a directory inside one. Those roots are written by unrelated processes (daemon heartbeats,
+ * logs, other agents), are often too large or partly unreadable to snapshot, and hold no project whose
+ * verifier could ever run, so a snapshot diff there cannot be attributed to one shell call. A project
+ * directory nested under them (a `mkdtemp` dir, `~/work/app`) is NOT a scratch root and stays gated.
+ */
+export function isSharedScratchRoot(cwd: string, roots: readonly string[] = defaultScratchRoots(cwd)): boolean {
+  const here = realOrResolved(cwd);
+  return roots.some(root => realOrResolved(root) === here);
+}

package/src/ai/types.ts

@@ -81,6 +81,18 @@ export interface ToolResultRecord {
   id: string;
   output: string;
   isError: boolean;
+  /**
+   * Host-side workspace evidence for a shell/computer call. Never sent to a provider; persisted with
+   * the transcript so a completion-gate rejection can be audited afterwards. `mutation` is whether the
+   * snapshot bracket counted the call as a possible file change, `changed` names the paths that differed,
+   * and `inconclusive` is why the bracket could not measure (cap or error; counted as a change). `skipped: "scratch"`
+   * means nothing was measured: the cwd is a shared scratch root where calls are deliberately not bracketed, or (with
+   * `target`) a nested project root was already unmeasurable BEFORE the call and failed open.
+   * `target` is set only when the bracket aimed at a nested project root instead of the cwd (a bash call from a
+   * scratch cwd; the outermost marker directory above the call's target): relative to the cwd when inside it, else
+   * the fixed token `<outside cwd>`; `changed` paths are relative to that directory.
+   */
+  workspace?: { mutation: boolean; changed?: string; inconclusive?: string; skipped?: "scratch"; target?: string };
 }
 
 export interface Usage {

package/src/commands/launch.ts

@@ -3,6 +3,7 @@ import { emitKeypressEvents } from "node:readline";
 import { StringDecoder } from "node:string_decoder";
 import { PassThrough } from "node:stream";
 import { createHash } from "node:crypto";
+import { MUTATION_NUDGE_PREFIX } from "../agent/loop-guards";
 import { runAgentLoop, DEFAULT_TOOLS, SANDBOX_MEDIATED_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, KARPATHY_DISCIPLINE, OUTPUT_DISCIPLINE, VERIFICATION_DIRECTIVE, isSafetyFallbackBail, stripSafetyFallbackTag, type AgentLoopEvents } from "../agent/engine";
 import { computerSupervisor } from "../agent/computer-supervisor";
 import { executeComputerAction } from "./computer";
@@ -2001,7 +2002,7 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
           const carriedPending = turnPendingMutation || (goalState !== null && pendingMutationVerification);
           if ((carriedPending || evidence.sawMutation) && !(evidence.sawVerification && !evidence.verificationStale)) {
             return (
-              `Cannot finish: a workspace mutation from this session still lacks a successful, non-stale verification. ` +
+              `${MUTATION_NUDGE_PREFIX} ` +
               `Run a relevant test/build/typecheck/lint after the last change (e.g. 'bun test', 'bun run typecheck', 'tsc --noEmit', 'npm test', 'pytest', 'cargo test', or 'go test ./...'), then call done again.`
             );
           }