@namzu/sdk 21.0.0 → 21.1.0

package/dist/run/memory-promoter.js

@@ -0,0 +1,117 @@
+/**
+ * The default {@link PromoteMemory}: write what a run learned into a
+ * {@link MemoryStore}, or write nothing at all.
+ *
+ * `promoteMemory` is called once at settle with the compaction extractor's
+ * already-structured output — decisions, discoveries, user requirements,
+ * failures, environment facts — and **nothing shipped supplied the hook**.
+ * So the structure the compaction pass had spent tokens producing was
+ * serialized into one system message and dropped on the floor when the run
+ * ended, exactly as its own module comment says. This is the supplier, and
+ * it is mostly a filter: the hard part — extracting facts from a transcript
+ * — already happened.
+ *
+ * ## The filter, which is the only decision here
+ *
+ * **A run that learned nothing must leave nothing.** Not an empty record,
+ * not a record whose body says "no decisions" — nothing. A promoter that
+ * wrote a row per run would fill the store with the runs least worth
+ * remembering, and `search_memory` would then return them: the model reads
+ * that store on later runs, so noise here is not merely wasted disk, it is
+ * context spent on a run that did nothing.
+ *
+ * What counts as having learned something is the five KNOWLEDGE categories —
+ * decisions, discoveries, user requirements, failures, environment. Not
+ * `task`, which every run has because it is the prompt restated. Not
+ * `files`, which every run that opened anything has, and which says what was
+ * touched rather than what was learned. A run whose only trace is "it read
+ * six files" is the exact record this filter exists to refuse.
+ *
+ * ## What it does NOT do
+ *
+ * Deduplicate against what is already stored, merge with a previous run's
+ * record, or expire anything. Each is a policy with real trade-offs and a
+ * host that wants one owns it — `promoteMemory` is a callback precisely so
+ * that the runtime does not decide this. This is the obvious default, not
+ * the only possible one.
+ */
+/**
+ * The categories that make a run worth remembering.
+ *
+ * Ordered as they are rendered. `userRequirements` first because it is the
+ * most durable of the five — a constraint the user stated outlives the run
+ * that heard it, whereas a discovery about a codebase expires when the
+ * codebase moves.
+ */
+const KNOWLEDGE = [
+    ['userRequirements', 'What the user requires'],
+    ['decisions', 'Decisions'],
+    ['discoveries', 'Discoveries'],
+    ['failures', 'What did not work'],
+    ['environment', 'Environment'],
+];
+/** Tag every record this promoter writes, so a host can find or prune them. */
+export const RUN_MEMORY_TAG = 'run-memory';
+/** Everything the candidate knows, as `[heading, items]`, empties dropped. */
+function knowledge(candidate, cap) {
+    const out = [];
+    for (const [key, heading] of KNOWLEDGE) {
+        const items = candidate[key];
+        if (items.length > 0)
+            out.push([heading, items.slice(0, cap)]);
+    }
+    return out;
+}
+/** A one-line summary naming what kind of knowledge the record holds. */
+function summarize(sections) {
+    return sections.map(([heading, items]) => `${heading.toLowerCase()} (${items.length})`).join(', ');
+}
+function render(candidate, sections) {
+    const body = sections.map(([heading, items]) => `## ${heading}\n\n${items.map((i) => `- ${i}`).join('\n')}`);
+    // The eviction counts, when there are any. Carried rather than hidden for
+    // the reason the candidate carries them: somebody reading this record
+    // should know they are reading a truncated account of the run, not a
+    // complete one.
+    const evicted = Object.entries(candidate.evicted).filter(([, n]) => n > 0);
+    if (evicted.length > 0) {
+        body.push(`## Dropped during the run\n\n${evicted
+            .map(([category, n]) => `- ${category}: ${n} entr${n === 1 ? 'y' : 'ies'} evicted`)
+            .join('\n')}`);
+    }
+    if (candidate.files.length > 0) {
+        body.push(`## Files touched\n\n${candidate.files.map((f) => `- ${f}`).join('\n')}`);
+    }
+    return `# ${candidate.task}\n\n${body.join('\n\n')}\n`;
+}
+/**
+ * Build a promoter that writes one record per run that learned something.
+ *
+ * Never throws out to the runtime — but it does not swallow either: the
+ * runtime already catches and logs a promoter's failure at settle, and
+ * catching here as well would hide a broken store from the one place that
+ * reports it.
+ */
+export function createMemoryPromoter(options) {
+    const cap = options.maxPerCategory ?? 20;
+    const tags = [RUN_MEMORY_TAG, ...(options.tags ?? [])];
+    return async (candidate) => {
+        const sections = knowledge(candidate, cap);
+        // Nothing learned, nothing written. Not an empty record: a store full
+        // of rows describing runs that discovered nothing is a store whose
+        // search results are mostly noise, and the model reads that store.
+        if (sections.length === 0)
+            return;
+        await options.store.create({
+            title: candidate.task.trim() || `Run ${candidate.runId}`,
+            summary: summarize(sections),
+            content: render(candidate, sections),
+            tags,
+            format: 'markdown',
+            // The run id, so a record can be traced back to the run that formed
+            // it. Evidence rather than decoration: without it a surprising
+            // memory cannot be checked against what actually happened.
+            metadata: { runId: candidate.runId, source: RUN_MEMORY_TAG },
+        });
+    };
+}
+//# sourceMappingURL=memory-promoter.js.map

package/dist/run/memory-promoter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-promoter.js","sourceRoot":"","sources":["../../src/run/memory-promoter.ts"],"names":[],"mappings":"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"}

package/dist/run/workspace-fingerprint.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A hash of everything a run could have changed in its working tree.
+ *
+ * It exists to answer one question, asked between two attempts at the same
+ * verification: **did anything happen since it last failed?** A verify-then-fix
+ * loop that re-runs the build after a turn which edited nothing spends a full
+ * command execution to learn what a comparison already knew, and does it once
+ * per remaining attempt — so a model that has stopped making progress burns
+ * the entire budget confirming the same failure.
+ *
+ * ## What is hashed, and why each part
+ *
+ * Three sources, because no one of them is complete:
+ *
+ *  1. **`git status --porcelain`** — which paths differ from the index at all.
+ *     Cheap, and it catches additions, deletions and mode changes. On its own
+ *     it is not enough: editing a tracked file that was ALREADY modified
+ *     leaves the status output byte-identical.
+ *  2. **`git diff --binary HEAD`** — the content of every tracked change.
+ *     `--binary` so an edit to a file git treats as binary is a real diff
+ *     rather than the constant line `Binary files … differ`, which would make
+ *     every edit to such a file invisible.
+ *  3. **Untracked file contents**, which no `git diff` covers. A new file is
+ *     named by `status` but its CONTENT is not, so successive edits to a
+ *     brand-new file would otherwise look like no change at all.
+ *
+ * ### Symlinks are recorded as their target, not read through
+ *
+ * Reading a link follows it, so a link repointed from one file to another
+ * with identical contents hashes the same — while the thing the workspace
+ * actually resolves has changed. The link's target path is the fact that
+ * moved, so that is what goes in.
+ *
+ * ## Failing open, on the cheap side
+ *
+ * Every uncertainty returns `null`, meaning *no fingerprint*, and a caller
+ * that cannot fingerprint re-runs its command. That is the correct direction:
+ * the cost of a wrong `null` is one command execution, and the cost of a
+ * wrong MATCH is a verification silently skipped — the loop would report
+ * "nothing changed" about a workspace that did change, and the model would be
+ * told to edit something it had already edited.
+ *
+ * So: a non-zero exit from any git invocation, a repository with no commits,
+ * a timeout, or output past the size cap all produce `null` rather than a
+ * partial hash. A truncated diff that hashed successfully would be the worst
+ * outcome available here, because two different workspaces truncated at the
+ * same point collide.
+ */
+import type { CommandOptions, CommandResult } from '../types/execution/index.js';
+/** How a fingerprint runs git. Injected so a test needs no repository. */
+export type FingerprintExec = (command: string, args: string[], options?: CommandOptions) => Promise<CommandResult>;
+/**
+ * The three filesystem reads an untracked entry needs.
+ *
+ * Injectable for one specific reason, written down because a seam that
+ * exists only for tests is usually a smell: **creating a symlink requires a
+ * privilege that is not granted by default on Windows**, so the symlink rule
+ * below — the one that says a repointed link changes the fingerprint even
+ * when the bytes behind it do not — cannot be exercised on a developer
+ * machine without it. A rule that can only be checked on some machines is a
+ * rule nobody checks.
+ *
+ * The default is `node:fs/promises` and every other test uses it against a
+ * real repository, so this is not a fixture standing in for production; it is
+ * one branch of one function reached without a privilege.
+ */
+export interface FingerprintFs {
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+        isFile(): boolean;
+    }>;
+    readlink(path: string): Promise<string>;
+    readFile(path: string): Promise<Buffer>;
+}
+/**
+ * Cap on the bytes any single git invocation may produce.
+ *
+ * Past it the fingerprint is abandoned rather than hashed. A diff big enough
+ * to hit this is a diff nobody is going to iterate on anyway, and hashing a
+ * clipped one would let two different trees agree.
+ */
+export declare const FINGERPRINT_MAX_BYTES: number;
+/** Default deadline per git invocation. */
+export declare const FINGERPRINT_TIMEOUT_MS = 20000;
+export interface WorkspaceFingerprintOptions {
+    /** Repository root, or any directory inside it. */
+    readonly cwd: string;
+    /** How to run git. */
+    readonly exec: FingerprintExec;
+    /** Per-invocation deadline. See {@link FINGERPRINT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** See {@link FINGERPRINT_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /** Filesystem reads. See {@link FingerprintFs}. */
+    readonly fs?: FingerprintFs;
+}
+/**
+ * A hash of the working tree's uncommitted state, or `null` when it cannot be
+ * established.
+ *
+ * **`null` is never "unchanged".** It means "I cannot tell", and the caller
+ * must treat it as a reason to do the work rather than to skip it.
+ */
+export declare function fingerprintWorkspace(options: WorkspaceFingerprintOptions): Promise<string | null>;
+//# sourceMappingURL=workspace-fingerprint.d.ts.map

package/dist/run/workspace-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-fingerprint.d.ts","sourceRoot":"","sources":["../../src/run/workspace-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAEhF,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,cAAc,KACpB,OAAO,CAAC,aAAa,CAAC,CAAA;AAE3B;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,cAAc,IAAI,OAAO,CAAC;QAAC,MAAM,IAAI,OAAO,CAAA;KAAE,CAAC,CAAA;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACvC;AAID;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAkB,CAAA;AAEpD,2CAA2C;AAC3C,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C,MAAM,WAAW,2BAA2B;IAC3C,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,CAAC,EAAE,aAAa,CAAA;CAC3B;AAwBD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmDxB"}

package/dist/run/workspace-fingerprint.js

@@ -0,0 +1,147 @@
+/**
+ * A hash of everything a run could have changed in its working tree.
+ *
+ * It exists to answer one question, asked between two attempts at the same
+ * verification: **did anything happen since it last failed?** A verify-then-fix
+ * loop that re-runs the build after a turn which edited nothing spends a full
+ * command execution to learn what a comparison already knew, and does it once
+ * per remaining attempt — so a model that has stopped making progress burns
+ * the entire budget confirming the same failure.
+ *
+ * ## What is hashed, and why each part
+ *
+ * Three sources, because no one of them is complete:
+ *
+ *  1. **`git status --porcelain`** — which paths differ from the index at all.
+ *     Cheap, and it catches additions, deletions and mode changes. On its own
+ *     it is not enough: editing a tracked file that was ALREADY modified
+ *     leaves the status output byte-identical.
+ *  2. **`git diff --binary HEAD`** — the content of every tracked change.
+ *     `--binary` so an edit to a file git treats as binary is a real diff
+ *     rather than the constant line `Binary files … differ`, which would make
+ *     every edit to such a file invisible.
+ *  3. **Untracked file contents**, which no `git diff` covers. A new file is
+ *     named by `status` but its CONTENT is not, so successive edits to a
+ *     brand-new file would otherwise look like no change at all.
+ *
+ * ### Symlinks are recorded as their target, not read through
+ *
+ * Reading a link follows it, so a link repointed from one file to another
+ * with identical contents hashes the same — while the thing the workspace
+ * actually resolves has changed. The link's target path is the fact that
+ * moved, so that is what goes in.
+ *
+ * ## Failing open, on the cheap side
+ *
+ * Every uncertainty returns `null`, meaning *no fingerprint*, and a caller
+ * that cannot fingerprint re-runs its command. That is the correct direction:
+ * the cost of a wrong `null` is one command execution, and the cost of a
+ * wrong MATCH is a verification silently skipped — the loop would report
+ * "nothing changed" about a workspace that did change, and the model would be
+ * told to edit something it had already edited.
+ *
+ * So: a non-zero exit from any git invocation, a repository with no commits,
+ * a timeout, or output past the size cap all produce `null` rather than a
+ * partial hash. A truncated diff that hashed successfully would be the worst
+ * outcome available here, because two different workspaces truncated at the
+ * same point collide.
+ */
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readlink } from 'node:fs/promises';
+import { join } from 'node:path';
+const NODE_FS = { lstat, readlink, readFile };
+/**
+ * Cap on the bytes any single git invocation may produce.
+ *
+ * Past it the fingerprint is abandoned rather than hashed. A diff big enough
+ * to hit this is a diff nobody is going to iterate on anyway, and hashing a
+ * clipped one would let two different trees agree.
+ */
+export const FINGERPRINT_MAX_BYTES = 4 * 1024 * 1024;
+/** Default deadline per git invocation. */
+export const FINGERPRINT_TIMEOUT_MS = 20_000;
+/** One untracked path's contribution, or `null` when it could not be read. */
+async function untrackedEntry(cwd, rel, fs) {
+    const abs = join(cwd, rel);
+    try {
+        const stats = await fs.lstat(abs);
+        if (stats.isSymbolicLink()) {
+            // The TARGET, not what is behind it. Following the link would hash a
+            // repointed link to the same value whenever the new target happens
+            // to hold the same bytes, and a repoint is a change to the workspace
+            // by any reading that matters.
+            return `L ${rel}\0${await fs.readlink(abs)}`;
+        }
+        if (!stats.isFile())
+            return `? ${rel}`;
+        const body = await fs.readFile(abs);
+        return `F ${rel}\0${createHash('sha256').update(body).digest('hex')}`;
+    }
+    catch {
+        // Vanished between the listing and the read, or unreadable. Neither is
+        // a fingerprint this function may guess at.
+        return null;
+    }
+}
+/**
+ * A hash of the working tree's uncommitted state, or `null` when it cannot be
+ * established.
+ *
+ * **`null` is never "unchanged".** It means "I cannot tell", and the caller
+ * must treat it as a reason to do the work rather than to skip it.
+ */
+export async function fingerprintWorkspace(options) {
+    const { cwd, exec } = options;
+    const timeoutMs = options.timeoutMs ?? FINGERPRINT_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? FINGERPRINT_MAX_BYTES;
+    const fs = options.fs ?? NODE_FS;
+    const git = async (args) => {
+        let result;
+        try {
+            result = await exec('git', args, { cwd, timeoutMs });
+        }
+        catch {
+            return null;
+        }
+        // A timeout surfaces here as a non-zero exit, and so does "not a
+        // repository" and "no commits yet". All three mean the same thing to
+        // this function: it has no basis for a comparison.
+        if (result.exitCode !== 0)
+            return null;
+        if (Buffer.byteLength(result.stdout, 'utf8') > maxBytes)
+            return null;
+        return result.stdout;
+    };
+    const status = await git(['status', '--porcelain']);
+    if (status === null)
+        return null;
+    const diff = await git(['diff', '--binary', 'HEAD']);
+    if (diff === null)
+        return null;
+    const untracked = await git(['ls-files', '--others', '--exclude-standard', '-z']);
+    if (untracked === null)
+        return null;
+    const parts = [`status ${status}`, `diff ${diff}`];
+    // Split on NUL, which is what `-z` is for: a path may contain a newline,
+    // and splitting on one would turn a single strange filename into two
+    // ordinary-looking ones.
+    //
+    // Sorted, because `ls-files` order is not part of any contract and a
+    // fingerprint that moved when the listing order did would report a change
+    // nobody made.
+    for (const rel of untracked.split('\0').filter(Boolean).sort()) {
+        const entry = await untrackedEntry(cwd, rel, fs);
+        if (entry === null)
+            return null;
+        parts.push(entry);
+    }
+    // Length-prefixed rather than delimiter-joined. A diff can contain any
+    // byte, so any separator is a separator the content can forge — and two
+    // different trees that agreed after forgery would be reported as
+    // unchanged, which is the one wrong answer this file is arranged to avoid.
+    const hash = createHash('sha256');
+    for (const part of parts)
+        hash.update(`${Buffer.byteLength(part, 'utf8')}:${part}`);
+    return hash.digest('hex');
+}
+//# sourceMappingURL=workspace-fingerprint.js.map

package/dist/run/workspace-fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-fingerprint.js","sourceRoot":"","sources":["../../src/run/workspace-fingerprint.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "21.0.0",
+  "version": "21.1.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/public-runtime.ts

@@ -141,6 +141,37 @@ export type {
 	DrainRunsParams,
 	DrainRunsResult,
 } from './run/index.js'
+// A `ReviewAnswer` that runs shell commands, so "don't finish until the
+// build passes" needs no TypeScript. `reviewAnswer` was the seam for this
+// and nothing shipped supplied one. Skips re-running a command whose
+// failure the workspace has not changed since — the difference between a
+// bounded loop and one that spends its whole budget confirming a failure it
+// already reported.
+export {
+	DEFAULT_GATE_MAX_RETRIES,
+	DEFAULT_GATE_OUTPUT_CHARS,
+	DEFAULT_GATE_TIMEOUT_MS,
+	FINGERPRINT_MAX_BYTES,
+	FINGERPRINT_TIMEOUT_MS,
+	clipOutput,
+	createCommandGate,
+	fingerprintWorkspace,
+} from './run/index.js'
+export type {
+	CommandGateOptions,
+	FingerprintExec,
+	GateExec,
+	WorkspaceFingerprintOptions,
+} from './run/index.js'
+// The default `promoteMemory`: write what a run learned into a MemoryStore,
+// or write NOTHING. The hook was invoked at settle with the compaction
+// extractor's already-structured output and no shipped app supplied it, so
+// that structure was serialized into one system message and dropped when
+// the run ended. A run that learned nothing leaves no record at all — the
+// model reads this store, so noise here is context spent on a run that did
+// nothing.
+export { RUN_MEMORY_TAG, createMemoryPromoter } from './run/index.js'
+export type { MemoryPromoterOptions } from './run/index.js'
 
 // ─── personas, skills, advisory ──────────────────────────────────────────
 

package/src/run/command-gate.ts

@@ -0,0 +1,234 @@
+/**
+ * A {@link ReviewAnswer} that runs shell commands and hands the failure back.
+ *
+ * `reviewAnswer` was the seam for exactly this — judge the answer at the point
+ * the model stops calling tools, and return it with feedback instead of
+ * settling — and nothing shipped supplied one, so an operator who wanted
+ * "don't finish until the build passes" had to write TypeScript. This is the
+ * supplier. With it, `--gate 'pnpm test'` is the whole unattended story: the
+ * model works, stops, the tests run, and a failure comes back as the next user
+ * turn rather than as a green run somebody discovers in CI.
+ *
+ * The kernel already bounds it. The reviewer is consulted only when the model
+ * stopped calling tools, never on the forced-final turn, and a rejection
+ * budget stops the run with `answer_rejected` — a stop reason that names the
+ * reviewer rather than blaming a token budget. None of that is re-implemented
+ * here.
+ *
+ * ## The part that is not just "run a command"
+ *
+ * **Before re-running a command that already failed, the workspace is
+ * fingerprinted, and an identical fingerprint means the command is NOT run.**
+ *
+ * This is the difference between a bounded loop and one that spends its whole
+ * budget. A model that has run out of ideas answers again without editing
+ * anything; re-running the suite then costs a full execution — often the most
+ * expensive thing in the loop — to produce a failure already known character
+ * for character. Worse, the feedback is identical, so the model is handed the
+ * same prompt that just failed to help it. Saying instead "the workspace has
+ * not changed since that failure; edit something before trying to finish"
+ * is both cheaper and a different instruction.
+ *
+ * The attempt still advances. Skipping the command is a saving, not a pardon:
+ * an answer that changed nothing has been rejected, and the run's budget must
+ * see that or a stuck model loops forever for free.
+ *
+ * And it fails open on the cheap side. No fingerprint — a git invocation that
+ * errored, a timeout, output past the cap, a tree with no commits — means the
+ * command runs. See {@link fingerprintWorkspace}: the cost of re-running
+ * unnecessarily is one execution; the cost of wrongly skipping is a
+ * verification that silently did not happen.
+ */
+
+import { LocalExecutionContext } from '../execution/local.js'
+import type { CommandOptions, CommandResult } from '../types/execution/index.js'
+import type { AnswerReview, ReviewAnswer } from '../types/run/answer-review.js'
+import { fingerprintWorkspace } from './workspace-fingerprint.js'
+
+/** How the gate runs a command. Injected so a test needs no shell. */
+export type GateExec = (
+	command: string,
+	args: string[],
+	options?: CommandOptions,
+) => Promise<CommandResult>
+
+/** Default per-command deadline. A test suite is allowed to be slow. */
+export const DEFAULT_GATE_TIMEOUT_MS = 600_000
+
+/** How many attempts the gate will EXECUTE its commands for, by default. */
+export const DEFAULT_GATE_MAX_RETRIES = 3
+
+/**
+ * Model-visible characters of a failing command's output.
+ *
+ * Head and tail, not head alone: a compiler names the file at the top and a
+ * test runner names the failure at the bottom, and a gate that only ever kept
+ * one end would be useless for one of them.
+ */
+export const DEFAULT_GATE_OUTPUT_CHARS = 4_000
+
+export interface CommandGateOptions {
+	/**
+	 * Shell command lines, run in order, stopping at the first failure.
+	 *
+	 * In order and short-circuiting because that is what a person means by
+	 * "typecheck then test": a type error makes the test output noise about
+	 * the same cause, and handing the model both invites it to fix the
+	 * symptom.
+	 */
+	readonly commands: readonly string[]
+	/** Directory the commands run in, and the tree that is fingerprinted. */
+	readonly cwd: string
+	/**
+	 * How many attempts will actually EXECUTE the commands.
+	 *
+	 * Past it the gate rejects without running anything, naming the
+	 * exhaustion. It does not accept: an answer that never passed the gate
+	 * has not passed the gate, and a reviewer that gave up by accepting would
+	 * hand back a green run over a red build — the exact outcome the gate
+	 * exists to prevent. What ENDS the run is the kernel's rejection budget,
+	 * so set that to the same number (the CLI does).
+	 */
+	readonly maxRetries?: number
+	/** Per-command deadline. See {@link DEFAULT_GATE_TIMEOUT_MS}. */
+	readonly timeoutMs?: number
+	/** Override the executor. Defaults to a local shell in `cwd`. */
+	readonly exec?: GateExec
+	/** See {@link DEFAULT_GATE_OUTPUT_CHARS}. */
+	readonly maxOutputChars?: number
+	/**
+	 * Override the change detector. Defaults to
+	 * {@link fingerprintWorkspace} over `cwd`.
+	 *
+	 * Returning `null` means "cannot tell", and the gate then runs its
+	 * commands. A detector that returned a constant would silence the gate
+	 * after its first failure, so this seam exists for tests and for a host
+	 * whose workspace is not a git tree — not as a way to turn the check off.
+	 */
+	readonly fingerprint?: () => Promise<string | null>
+}
+
+/** Head and tail of a command's output, with the middle marked as dropped. */
+export function clipOutput(text: string, max: number): string {
+	const trimmed = text.trimEnd()
+	if (trimmed.length <= max) return trimmed
+	const half = Math.floor(max / 2)
+	const dropped = trimmed.length - half * 2
+	return `${trimmed.slice(0, half)}\n… ${dropped} characters omitted …\n${trimmed.slice(-half)}`
+}
+
+interface LastFailure {
+	readonly command: string
+	/** The tree as it stood when this failed. `null` = could not be taken. */
+	readonly fingerprint: string | null
+}
+
+function failureFeedback(
+	command: string,
+	attempt: number,
+	result: CommandResult,
+	maxOutputChars: number,
+): string {
+	const output = clipOutput(`${result.stdout}\n${result.stderr}`, maxOutputChars)
+	return [
+		`The answer was not accepted: \`${command}\` failed (attempt ${attempt}, exit ${result.exitCode}).`,
+		'',
+		'Output:',
+		'```',
+		output || '(no output)',
+		'```',
+		'',
+		'Fix the cause and then finish. Do not restate the failure back to me; change the code so the command passes.',
+	].join('\n')
+}
+
+function unchangedFeedback(command: string, attempt: number): string {
+	return [
+		`The answer was not accepted, and \`${command}\` was NOT re-run (attempt ${attempt}).`,
+		'',
+		'The workspace is byte-for-byte identical to what it was when that command last failed — no file was created, edited or deleted since. Running it again would produce the failure you have already been shown.',
+		'',
+		'Edit something before trying to finish again. If you believe the change you described was made, verify it by reading the file: it is not on disk.',
+	].join('\n')
+}
+
+function exhaustedFeedback(command: string, maxRetries: number): string {
+	return [
+		`The answer was not accepted: \`${command}\` has failed and this gate has spent its ${maxRetries} attempts.`,
+		'',
+		'No further command will be run.',
+	].join('\n')
+}
+
+/**
+ * Build a reviewer that accepts an answer only when every command passes.
+ *
+ * Stateful across calls within one run, deliberately: the whole point is that
+ * attempt N+1 can be compared with attempt N. Build one gate per run.
+ */
+export function createCommandGate(options: CommandGateOptions): ReviewAnswer {
+	const { commands, cwd } = options
+	const timeoutMs = options.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS
+	const maxRetries = options.maxRetries ?? DEFAULT_GATE_MAX_RETRIES
+	const maxOutputChars = options.maxOutputChars ?? DEFAULT_GATE_OUTPUT_CHARS
+
+	// Built once and reused: constructing a context per attempt would re-stat
+	// the directory for no gain, and the context holds nothing per-run.
+	const context = new LocalExecutionContext({ id: 'namzu-command-gate', cwd })
+	const exec: GateExec =
+		options.exec ?? ((command, args, opts) => context.executeCommand(command, args, opts))
+	const fingerprint =
+		options.fingerprint ?? (() => fingerprintWorkspace({ cwd, exec, timeoutMs: 20_000 }))
+
+	let attempt = 0
+	let last: LastFailure | undefined
+	let executions = 0
+
+	return async (): Promise<AnswerReview> => {
+		attempt += 1
+
+		// A gate that already failed, over a tree nothing has touched since.
+		// The command is skipped, and the attempt still counts.
+		//
+		// The comparison is a bare `===` rather than `now !== null && now ===
+		// …`. The guard above already establishes that the recorded
+		// fingerprint is non-null, so a `null` from this call cannot match it,
+		// and the extra clause was a branch nothing could reach — a mutation
+		// that deleted it killed no test, which is what a dead condition looks
+		// like from the outside.
+		if (last && last.fingerprint !== null) {
+			const now = await fingerprint()
+			if (now === last.fingerprint) {
+				return { accept: false, feedback: unchangedFeedback(last.command, attempt) }
+			}
+		}
+
+		if (last && executions >= maxRetries) {
+			return { accept: false, feedback: exhaustedFeedback(last.command, maxRetries) }
+		}
+
+		executions += 1
+		for (const command of commands) {
+			// `shell: true` because the operator handed over a command LINE —
+			// `pnpm test -- --run`, with its flags and its quoting — and taking
+			// that as an executable name plus literal arguments would fail on
+			// every gate anyone would actually write. Explicit, per the note on
+			// `LocalExecutionContext.executeCommand`: shell interpretation is
+			// opt-in, and this is the opt-in.
+			const result = await exec(command, [], { cwd, timeoutMs, shell: true })
+			if (result.exitCode === 0) continue
+
+			// Taken AFTER the failure, not before the run: the comparison next
+			// time is against the tree this verdict was formed over. A snapshot
+			// from before the command would miss anything the command itself
+			// wrote — a formatter, a snapshot updater, a lockfile.
+			last = { command, fingerprint: await fingerprint() }
+			return { accept: false, feedback: failureFeedback(command, attempt, result, maxOutputChars) }
+		}
+
+		// Cleared, so a later rejection by a DIFFERENT command is not compared
+		// against a tree this one failed over.
+		last = undefined
+		return { accept: true }
+	}
+}