jeo-code 0.12.26 → 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,6 +12,25 @@
  *   - 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, realpathSync } from "node:fs";
@@ -26,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;
 }
@@ -45,6 +66,8 @@ export const WORKSPACE_SNAPSHOT_EXCLUDED_DIRS: ReadonlySet<string> = new Set([".
 export type WorkspaceSnapshot =
   | {
       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>;
@@ -81,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,
@@ -93,12 +118,14 @@ 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 paths = new Map<string, bigint>();
   const record = (entry: string, rel: string): void => {
     const hash = BigInt(Bun.hash.wyhash(entry));
-    digest = (digest + hash) & DIGEST_MASK;
+    // 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 => {
@@ -106,18 +133,16 @@ export async function snapshotWorkspace(
     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;
@@ -125,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 }); }
@@ -156,9 +206,8 @@ 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, leaf.rel);
   };
@@ -167,8 +216,22 @@ export async function snapshotWorkspace(
     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;
@@ -203,7 +266,9 @@ export async function snapshotWorkspace(
       }
       level = next;
     }
-    return { ok: true, digest, entries, elapsedMs: performance.now() - startedAt, startedAtMs, paths };
+    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) };

package/src/ai/types.ts

@@ -86,9 +86,13 @@ export interface ToolResultRecord {
    * 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 the cwd is a shared scratch root, where calls are deliberately not bracketed (nothing was measured).
+   * 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" };
+  workspace?: { mutation: boolean; changed?: string; inconclusive?: string; skipped?: "scratch"; target?: string };
 }
 
 export interface Usage {