@gethmy/harness 1.2.1 → 1.4.0

package/src/confine-to-repo.ts

@@ -1,5 +1,5 @@
 /**
- * Confine a read-only spawn to one directory tree.
+ * Confine a spawn to one directory tree.
  *
  * ## Why a handler and not a permission string
  *
@@ -7,9 +7,10 @@
  * The Agent SDK documents `allowedTools` as a list of tool NAMES ("To restrict
  * which tools are available, use the `tools` option instead"), so a rule-shaped
  * entry there most likely matches no tool at all. That failure is silent and
- * expensive: the tool is denied, the preflight returns no verdict, `sizeRun`
- * answers `null`, and the daemon degrades to the policy fallback forever with
- * nothing in the logs to say the sizing step stopped working.
+ * expensive: the tool is denied and the preflight returns no verdict, so the
+ * daemon degrades to the policy fallback forever. `sizeRun` now at least names
+ * that as `failed: "malformed"` in the log and on the timeline (#954) — before
+ * it did so, nothing said the sizing step had stopped working.
  *
  * `canUseTool` is documented to run before each tool execution and receives the
  * tool's INPUT, so the path can be checked directly. It is an ordinary function,
@@ -18,6 +19,8 @@
  *
  * ## What it is for
  *
+ * Two spawns, both reasoning over text someone else wrote.
+ *
  * The pickup sizing preflight reads the operator's PRIMARY checkout, not a
  * disposable worktree — the card's worktree does not exist when the model has to
  * be chosen. Its prompt is built from card text anyone in the workspace can
@@ -26,10 +29,34 @@
  * daemon's user can read stays reachable. This inverts that into an allowlist —
  * inside the tree, or denied.
  *
- * Prompt-level containment (JSON-encoded card data) makes injection harder; this
- * is what bounds it when that fails.
+ * The red-CI repair spawn (#1015) reasons over check names and job logs fetched
+ * from a CI provider, and unlike the preflight it holds `Write` and `Edit`, and
+ * what it writes is committed and pushed. That is the spawn this module's write
+ * coverage exists for. The escape it closes was found in review of #981 and is
+ * worth stating plainly, because it needs no shell: an injected directive tells
+ * the spawn to read `~/.claude/.credentials.json` and paste the contents into a
+ * source comment, which verifies green, commits, and pushes to origin — where
+ * the credential is readable by anyone with access to the repository.
+ * Exfiltration inside a grant that has no `Bash`, no `WebFetch` and no `Task`.
+ *
+ * Prompt-level containment (JSON-encoded card data, an untrusted-evidence frame)
+ * makes injection harder; this is what bounds it when that fails.
+ *
+ * ## Symlinks
+ *
+ * The tree test resolves symlinks (`realpathSync`) before comparing. A purely
+ * lexical check is not a bound on a spawn that can WRITE: `ln -s /etc <tree>/x`
+ * is inside the tree by string comparison, and every path under it reads and
+ * writes outside. The check therefore costs a `realpath` syscall per tool call,
+ * which is the correct trade against an escape that is one `Write` wide.
+ *
+ * A path that does not exist yet — the ordinary case for `Write` creating a new
+ * file — has its longest EXISTING ancestor resolved, and the remainder joined
+ * lexically onto that. A component that does not exist cannot be a symlink, so
+ * the two halves together are exact rather than approximate.
  */
-import { isAbsolute, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, parse, resolve, sep } from "node:path";
 
 /** The result shape the Agent SDK's `canUseTool` must return. */
 export type ConfineDecision =
@@ -37,31 +64,221 @@ export type ConfineDecision =
   | { behavior: "deny"; message: string };
 
 /**
- * Where each read-only tool carries the path it wants to touch.
+ * Where each tool carries the path it wants to touch.
  *
- * A tool absent from this map is denied outright rather than allowed: this
- * guards a spawn whose allow-list is meant to be exactly these three, so an
- * unrecognised tool means either the allow-list drifted or the model reached
- * for something it should not have. Failing closed is the honest answer to
- * "I do not know what this tool would do".
+ * A tool absent from the ACTIVE map is denied outright rather than allowed: this
+ * guards a spawn whose allow-list is meant to be exactly the named set, so an
+ * unrecognised tool means either the allow-list drifted or the model reached for
+ * something it should not have. Failing closed is the honest answer to "I do not
+ * know what this tool would do".
  */
-const PATH_ARG_BY_TOOL: Record<string, readonly string[]> = {
+const READ_PATH_ARGS: Record<string, readonly string[]> = {
   Read: ["file_path", "path", "notebook_path"],
   Grep: ["path"],
   Glob: ["path"],
 };
 
-/** Is `target` inside `root` (or root itself)? */
+/**
+ * The write tools, and the argument each carries its target in.
+ *
+ * `MultiEdit` and `NotebookEdit` are here beside `Write`/`Edit` because a map
+ * that covered only the two obvious ones would deny them by name — which is
+ * safe — but a later edit adding either to a spawn's `tools` would then find
+ * them silently refused rather than confined. Naming all four keeps the map and
+ * the grant able to agree.
+ */
+const WRITE_PATH_ARGS: Record<string, readonly string[]> = {
+  Write: ["file_path"],
+  Edit: ["file_path"],
+  MultiEdit: ["file_path"],
+  NotebookEdit: ["notebook_path"],
+};
+
+/** The read-only surface: what the sizing preflight is confined to. */
+export const CONFINED_READ_TOOLS = Object.freeze(Object.keys(READ_PATH_ARGS));
+
+/**
+ * The read-and-write surface: what the red-CI repair spawn is confined to.
+ *
+ * `MultiEdit` is deliberately ABSENT even though the map above covers it. It is
+ * not a tool this SDK defines, and this list becomes the SDK's `tools` — a name
+ * nothing defines has no business in a grant. Keeping it in the map means that
+ * if a future SDK does define it, it arrives confined rather than as an
+ * unrecognised name the map would have to fail closed on.
+ */
+export const CONFINED_WRITE_TOOLS = Object.freeze([
+  ...Object.keys(READ_PATH_ARGS),
+  ...Object.keys(WRITE_PATH_ARGS).filter((t) => t !== "MultiEdit"),
+]);
+
+/**
+ * Arguments that are GLOB PATTERNS rather than paths, and still escape a tree.
+ *
+ * `Glob`'s `path` is optional; its `pattern` is not. node-glob honours an
+ * absolute pattern and a leading `../` regardless of `cwd`, so
+ * `Glob({pattern: "/Users/me/.claude/**"})` enumerated the credential directory
+ * while every path check passed vacuously — the loop found no path argument and
+ * fell through to allow (security review of #1015). A pattern cannot be
+ * resolved to one path, so it is not tree-checked; it is required to be
+ * relative and traversal-free, which is what confines it.
+ */
+const PATTERN_ARG_BY_TOOL: Record<string, readonly string[]> = {
+  // `Glob.path` and `Grep.path` are real paths and are tree-checked above;
+  // only the glob-shaped arguments belong here. `Grep.pattern` is a REGEX, not
+  // a path, and must not be checked as one.
+  Glob: ["pattern"],
+  Grep: ["glob"],
+};
+
+/**
+ * Is this path the tree's git metadata?
+ *
+ * ## The escape this closes, and the comment that got it wrong
+ *
+ * An earlier version of this feature argued that `.git` needed no entry,
+ * because in a LINKED worktree `.git` is a regular file rather than a
+ * directory, so "nothing traverses into it". The first half is true and the
+ * conclusion does not follow: nothing traverses THROUGH the file, but the file
+ * itself sits inside the tree and is therefore writable, and its whole content
+ * is a pointer to where git's configuration lives.
+ *
+ * Proven end to end during the security review of #1015, with no shell, no
+ * network tool and no subagent:
+ *
+ *   1. `Write` to `<tree>/.git` → `gitdir: ./g`   (an in-tree dir the spawn owns)
+ *   2. `Write` to `<tree>/g/config` → `[core] fsmonitor = ./payload.sh`
+ *   3. the diff gate's OWN `git status` runs `payload.sh` on the daemon host.
+ *
+ * `core.hooksPath=` does nothing about it — `fsmonitor` is config, not a hook —
+ * and `core.sshCommand`, `core.pager` and `alias.*` are equivalent primitives.
+ * So the bound cannot be "disarm the mechanisms we thought of"; it is that the
+ * spawn never touches git's metadata at all.
+ *
+ * Matched as a path SEGMENT so `.gitignore` and `src/.gitkeep` are unaffected,
+ * and checked against the raw candidate BEFORE symlink resolution, since a
+ * symlink named `.git` is the same attack.
+ *
+ * **Case-INSENSITIVELY**, and that is not cosmetic. The daemon's own platform
+ * is macOS, whose filesystem is case-insensitive by default, so `.GIT` and
+ * `.git` are the same file on disk. A case-sensitive comparison let a write to
+ * `.GIT` through every guard and land on the real gitdir pointer — proven
+ * end to end during review of #1015, ending in code execution as the daemon
+ * user. Windows/NTFS is the same. Refusing `.GIT` on Linux too costs nothing:
+ * nobody needs a file by that name.
+ */
+function isGitMetadata(repoRoot: string, candidate: string): boolean {
+  const rel = candidate.startsWith(repoRoot)
+    ? candidate.slice(repoRoot.length)
+    : candidate;
+  return rel.split(/[\\/]/).some((segment) => segment.toLowerCase() === ".git");
+}
+
+/**
+ * Does a glob pattern reach outside whatever directory it is rooted at?
+ *
+ * ## An allowlist of syntax, because a denylist of spellings does not close
+ *
+ * The first version of this rejected an absolute pattern and a literal `..`
+ * segment. The security review of #1015 walked straight past it: the glob
+ * language can SPELL `..` several ways, and `{..,x}/y` and `[.][.]/*` both read
+ * as ordinary segments while node-glob expands them into real traversal. A
+ * probe using brace expansion returned 43 files from `~/.claude` — the exact
+ * credential-directory enumeration the guard claimed to prevent.
+ *
+ * Enumerating the spellings is the losing game this feature has now lost three
+ * times. So the rule inverts: the pattern may use only `*`, `**`, `?`, `/` and
+ * literal characters. That set is small enough to argue about completely —
+ * none of it can name a parent directory, and `?` cannot produce `..` because
+ * glob traversal never yields `.` or `..` as directory entries. Brace
+ * expansion, character classes, `~` and extglob are refused as SYNTAX, not as
+ * payloads, which is why a new spelling of `..` cannot reopen it.
+ *
+ * A repair searching its own worktree does not need any of the refused syntax.
+ */
+function patternEscapes(pattern: string): boolean {
+  if (isAbsolute(pattern)) return true;
+  // Brace expansion, character classes, home expansion, extglob, and a literal
+  // parent segment. Anything outside `* ** ? /` and literals is refused.
+  if (/[{}[\]~()!+@]/.test(pattern)) return true;
+  return pattern.split(/[\\/]/).some((segment) => segment === "..");
+}
+
+/** How much of the tool surface a confined spawn may reach. */
+export type ConfineMode = "read" | "write";
+
+function pathArgsFor(mode: ConfineMode): Record<string, readonly string[]> {
+  return mode === "write"
+    ? { ...READ_PATH_ARGS, ...WRITE_PATH_ARGS }
+    : READ_PATH_ARGS;
+}
+
+/**
+ * Resolve `p` the way the KERNEL does: one component at a time, following each
+ * symlink before interpreting what comes after it.
+ *
+ * ## Why not `resolve()` first
+ *
+ * `path.resolve` removes `..` TEXTUALLY. The kernel removes it only after
+ * following the symlink in front of it. The two disagree exactly when a
+ * symlinked directory is followed by `..`, and the disagreement is an escape:
+ *
+ *     <tree>/node_modules/dep  ->  <elsewhere>/secrets
+ *     <tree>/node_modules/dep/../STOLEN.txt
+ *
+ * `resolve` folds that to `<tree>/node_modules/STOLEN.txt`, which is inside the
+ * tree, so a lexical-then-realpath check ALLOWS it — while the open(2) the tool
+ * then performs lands on `<elsewhere>/STOLEN.txt`. A package install routinely
+ * creates such links (`link:`/`file:` deps, a pnpm store), so the precondition
+ * is ordinary rather than exotic. Verified against this module during the
+ * security review of #1015.
+ *
+ * Walking instead means `..` is applied to a path whose symlinks are already
+ * resolved, which is what the kernel does and therefore the only thing that
+ * agrees with it.
+ *
+ * A component that does not exist is appended literally: it cannot be a
+ * symlink, and a later `..` still pops it correctly.
+ */
+function realPathOrNearest(p: string): string {
+  const abs = isAbsolute(p) ? p : resolve(p);
+  const { root } = parse(abs);
+  let real = root;
+
+  for (const part of abs.slice(root.length).split(sep)) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      real = dirname(real);
+      continue;
+    }
+    const next = real.endsWith(sep) ? real + part : real + sep + part;
+    try {
+      // `real` is already fully resolved, so this only resolves `part`.
+      real = realpathSync(next);
+    } catch {
+      real = next;
+    }
+  }
+  return real;
+}
+
+/**
+ * Is `target` inside `root` (or root itself)?
+ *
+ * Both sides are resolved through symlinks first, so a link planted inside the
+ * tree cannot widen it and a root reached by a symlinked path (macOS `/tmp` →
+ * `/private/tmp`, a worktree under a symlinked parent) does not deny everything.
+ */
 export function isInsideTree(root: string, target: string): boolean {
-  const normalizedRoot = resolve(root);
-  const normalizedTarget = resolve(target);
+  const normalizedRoot = realPathOrNearest(root);
+  const normalizedTarget = realPathOrNearest(target);
   if (normalizedTarget === normalizedRoot) return true;
   // The separator matters: without it `/repo-secrets` reads as inside `/repo`.
   return normalizedTarget.startsWith(normalizedRoot + sep);
 }
 
 /**
- * Decide one tool call. Pure, so the policy is testable without a spawn.
+ * Decide one tool call. Pure apart from the `realpath` syscall, so the policy is
+ * testable without a spawn.
  *
  * A tool with no path argument is allowed: `Grep` and `Glob` default to the
  * session's `cwd`, which IS the tree being confined to. A relative path is
@@ -72,8 +289,9 @@ export function decideConfinedTool(
   repoRoot: string,
   toolName: string,
   input: Record<string, unknown>,
+  mode: ConfineMode = "read",
 ): ConfineDecision {
-  const pathArgs = PATH_ARG_BY_TOOL[toolName];
+  const pathArgs = pathArgsFor(mode)[toolName];
   if (!pathArgs) {
     return {
       behavior: "deny",
@@ -81,14 +299,42 @@ export function decideConfinedTool(
     };
   }
 
+  const verb = toolName in WRITE_PATH_ARGS ? "write" : "read";
+
+  // Patterns first: they are the cheaper check, and an escaping pattern makes
+  // the path check below irrelevant anyway.
+  for (const key of PATTERN_ARG_BY_TOOL[toolName] ?? []) {
+    const value = input[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    if (patternEscapes(value)) {
+      return {
+        behavior: "deny",
+        message: `${toolName} patterns must stay inside the repository — no absolute path and no "..". Refused: ${value}`,
+      };
+    }
+  }
+
   for (const key of pathArgs) {
     const value = input[key];
     if (typeof value !== "string" || value.length === 0) continue;
-    const candidate = isAbsolute(value) ? value : resolve(repoRoot, value);
+    // CONCATENATED, not `resolve`d. `resolve(repoRoot, value)` folds `..`
+    // textually — the very defect `realPathOrNearest` exists to avoid — so a
+    // RELATIVE `node_modules/dep/../STOLEN.txt` was collapsed to an in-tree
+    // path and allowed while the syscall landed outside. The absolute branch
+    // was correct and the relative one was not, which is worse than both being
+    // wrong: the guard read as closed. `realPathOrNearest` handles a raw path
+    // with `..` in it, so hand it one.
+    const candidate = isAbsolute(value) ? value : `${repoRoot}${sep}${value}`;
+    if (isGitMetadata(repoRoot, candidate)) {
+      return {
+        behavior: "deny",
+        message: `${toolName} may not touch the repository's git metadata. Refused: ${value}`,
+      };
+    }
     if (!isInsideTree(repoRoot, candidate)) {
       return {
         behavior: "deny",
-        message: `${toolName} may only read inside the repository. Refused: ${value}`,
+        message: `${toolName} may only ${verb} inside the repository. Refused: ${value}`,
       };
     }
   }
@@ -101,13 +347,19 @@ export function decideConfinedTool(
  *
  * Kept separate from {@link decideConfinedTool} so the policy stays synchronous
  * and testable while the SDK gets the async shape it expects.
+ *
+ * `mode` defaults to `"read"`, so a caller that does not ask for write access
+ * does not get it. The sizing preflight relies on that default: `Write` and
+ * `Edit` are denied by name there even though this module now knows how to
+ * confine them.
  */
 export function confineToRepo(
   repoRoot: string,
+  mode: ConfineMode = "read",
 ): (
   toolName: string,
   input: Record<string, unknown>,
 ) => Promise<ConfineDecision> {
   return async (toolName, input) =>
-    decideConfinedTool(repoRoot, toolName, input);
+    decideConfinedTool(repoRoot, toolName, input, mode);
 }

package/src/error-classifier.ts

@@ -17,7 +17,8 @@ export type ApiErrorKind =
   | "rate_limit"
   | "out_of_credits"
   | "usage_limit"
-  | "auth";
+  | "auth"
+  | "spend_limit";
 
 export interface RunErrorClass {
   kind: ApiErrorKind | null;
@@ -37,6 +38,38 @@ const USAGE_LIMIT =
 const RATE_LIMIT =
   /\b429\b|\b529\b|rate[ _-]?limit|too many requests|overloaded_error|"type"\s*:\s*"overloaded"/i;
 
+/**
+ * An ACCOUNT-level spend cap (#1012). Measured in production on 2026-09-01:
+ *
+ *   Claude Code returned an error result: You've hit your org's monthly spend
+ *   limit · raise it at claude.ai/admin-settings/usage
+ *
+ * All four patterns above miss it, and each near-miss is instructive:
+ * `OUT_OF_CREDITS` wants the word `billing` (the text says `admin-settings/usage`),
+ * and `USAGE_LIMIT` has `monthly limit` where the text says `monthly **spend**
+ * limit`. So `classifyRunError` returned `kind: null`, the worker took the
+ * generic-crash path, and the daemon re-picked the same two cards every ~2
+ * minutes for four rounds — $198.99 in a day.
+ *
+ * Only the UNAMBIGUOUS spend phrasing lives here. The remedy URL is deliberately
+ * NOT in this pattern: it is checked last, after every other class, by
+ * {@link SPEND_LIMIT_REMEDY} — see `classifyRunError`.
+ */
+const SPEND_LIMIT = /spend(?:ing)? (?:limit|cap)|monthly spend/i;
+
+/**
+ * The remedy URL, as a LAST-RESORT signal only.
+ *
+ * A message that names this console page needs an admin, so on its own it is
+ * good evidence of a spend cap. But a self-clearing usage limit may cite the
+ * same page, and misreading one of those as a spend cap would latch the daemon
+ * and demand an operator resume that nobody owed. Checking it only after
+ * `USAGE_LIMIT` and `RATE_LIMIT` have both declined keeps the explicit,
+ * self-clearing classes winning while still catching the measured string, whose
+ * whole problem is that no other pattern recognises it at all.
+ */
+const SPEND_LIMIT_REMEDY = /admin-settings\/usage/i;
+
 /** Best-effort `Retry-After: <seconds>` extraction. */
 function parseRetryAfterMs(message: string): number | undefined {
   const match = message.match(/retry[- ]?after["':\s]+(\d+)/i);
@@ -54,10 +87,19 @@ export function classifyRunError(message: string): RunErrorClass {
   // pauses wholesale rather than churning. Check before billing because some
   // 401 bodies also mention "billing".
   if (AUTH.test(message)) return { kind: "auth", retryAfterMs };
+  // Before billing: a spend cap and a credit shortfall read alike but need
+  // opposite handling — a top-up clears one, only an admin raising the cap
+  // clears the other. A spend-limit body that also says "billing" must not be
+  // classified as something the daemon can wait out.
+  if (SPEND_LIMIT.test(message)) return { kind: "spend_limit", retryAfterMs };
   if (OUT_OF_CREDITS.test(message))
     return { kind: "out_of_credits", retryAfterMs };
   if (USAGE_LIMIT.test(message)) return { kind: "usage_limit", retryAfterMs };
   if (RATE_LIMIT.test(message)) return { kind: "rate_limit", retryAfterMs };
+  // Last: the remedy URL alone. See SPEND_LIMIT_REMEDY for why it ranks below
+  // every self-clearing class instead of beside SPEND_LIMIT.
+  if (SPEND_LIMIT_REMEDY.test(message))
+    return { kind: "spend_limit", retryAfterMs };
 
   return { kind: null };
 }
@@ -73,6 +115,8 @@ export function describeApiError(kind: ApiErrorKind): string {
       return "Anthropic usage limit reached — retrying after reset";
     case "rate_limit":
       return "Anthropic rate limit hit — retrying shortly";
+    case "spend_limit":
+      return "Account spend limit reached — raise it at claude.ai/admin-settings/usage, then run `harmony-agent resume`";
   }
 }
 
@@ -80,6 +124,11 @@ export function describeApiError(kind: ApiErrorKind): string {
  * Default daemon-wide cooldown for an API error class, used when the API gave
  * no explicit `Retry-After`. Billing/usage conditions reset slowly (or need a
  * human), so they back off longer; transient rate limits clear fast.
+ *
+ * **A cooldown is the wrong shape for `spend_limit`**, and its value below says
+ * so by being a fallback rather than the mechanism. Waiting does not raise a
+ * monthly spend cap, so `Pool.noteApiError` routes that kind to the durable
+ * account halt and never reaches this function with it.
  */
 export function cooldownMsFor(kind: ApiErrorKind): number {
   switch (kind) {
@@ -91,5 +140,7 @@ export function cooldownMsFor(kind: ApiErrorKind): number {
       return 30 * 60_000; // 30 min — usually needs a human top-up
     case "auth":
       return 30 * 60_000; // fallback; pool pauses wholesale on auth anyway
+    case "spend_limit":
+      return 30 * 60_000; // fallback; the pool latches durably on this one
   }
 }

package/src/gate-collectors.ts

@@ -10,6 +10,8 @@
  *   - custom        → #690's allowlisted command metric (a number to gate on)
  *   - oracle_passed → the held test authored by the stage's `author` role, run
  *                     against the implementer's worktree (Playbooks P2, Task 12)
+ *   - oracle_red    → the SAME held test, graded red: it must run and fail
+ *                     against the current tree (#921)
  *
  * The flow per gate, run daemon-side after a stage's work completes:
  *   collector.collect(ctx) → GateEvidence
@@ -46,7 +48,7 @@ import {
 } from "./command-metric.js";
 import { log } from "./log.js";
 import type { OracleDeps } from "./oracle.js";
-import { OracleCollector } from "./oracle-collector.js";
+import { OracleCollector, OracleRedCollector } from "./oracle-collector.js";
 import type { ReviewResult } from "./review-types.js";
 import { runBuild, runLint } from "./verification.js";
 
@@ -349,8 +351,9 @@ export interface GateCollectorDeps {
    */
   command?: CommandMetricDeps;
   /**
-   * The oracle_passed gate: the held test fetched from Harmony, placed in the
-   * worktree, run, removed. Supply it whenever a worktree exists.
+   * The held-test gates — `oracle_passed` AND `oracle_red` (#921): the held test
+   * fetched from Harmony, placed in the worktree, run, removed. Supply it
+   * whenever a worktree exists; one dep object serves both polarities.
    */
   oracle?: OracleDeps;
 }
@@ -385,6 +388,11 @@ export function buildGateCollectorRegistry(
   }
   if (deps.oracle) {
     registry.oracle_passed = new OracleCollector(deps.oracle);
+    // Same deps, opposite polarity (#921) — one held test, graded red here and
+    // green above. Registered together because they are never independently
+    // available: whatever lets the motor fetch and run a held test lets it do
+    // so for either polarity.
+    registry.oracle_red = new OracleRedCollector(deps.oracle);
   }
   return registry;
 }