@namzu/sdk 21.0.0 → 22.0.0

package/dist/run/LimitChecker.js

@@ -8,8 +8,20 @@ export function checkLimitsDetailed(config, state) {
     if (config.tokenBudget > 0 && state.totalTokens >= config.tokenBudget) {
         return { type: 'hard_stop', reason: 'token_budget' };
     }
-    if (config.costLimitUsd && config.costLimitUsd > 0 && state.totalCost >= config.costLimitUsd) {
-        return { type: 'hard_stop', reason: 'cost_limit' };
+    if (config.costLimitUsd && config.costLimitUsd > 0) {
+        if (state.totalCost >= config.costLimitUsd) {
+            return { type: 'hard_stop', reason: 'cost_limit' };
+        }
+        // Checked BEFORE the comparison can pass, not after. `totalCost` is
+        // only the part of the run that had a rate, so a run whose spend is
+        // partly unknown can sit under any limit forever while spending without
+        // bound. Continuing here would be the check answering "the budget is
+        // satisfied" to the question "can the budget be evaluated?", which is
+        // the strongest available wrong answer — see
+        // docs/conventions/an-optional-dependency-may-not-degrade-a-check.md.
+        if (state.unpricedTokens > 0) {
+            return { type: 'hard_stop', reason: 'cost_unmeasurable' };
+        }
     }
     if (state.currentIteration >= config.maxIterations) {
         return { type: 'hard_stop', reason: 'max_iterations' };

package/dist/run/LimitChecker.js.map

@@ -1 +1 @@
-{"version":3,"file":"LimitChecker.js","sourceRoot":"","sources":["../../src/run/LimitChecker.ts"],"names":[],"mappings":"AAeA,MAAM,UAAU,mBAAmB,CAClC,MAA0B,EAC1B,KAAwB;IAExB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;IAClD,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAChD,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,KAAK,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;IACrD,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,IAAI,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9F,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;IACnD,CAAC;IAED,IAAI,KAAK,CAAC,gBAAgB,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;IACvD,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAA;QACzD,IAAI,UAAU,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;YACjD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QACnD,CAAC;IACF,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,YAAY,CAAA;QACvD,IAAI,SAAS,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;YAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;QACjD,CAAC;IACF,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAA;IAChD,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC,SAAS,CAAA;IAChD,IAAI,SAAS,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAC9C,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACtB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,WAAmB,EACnB,SAAiB,EACjB,YAAqB,EACrB,aAAsB,EACtB,sBAA+B;IAE/B,OAAO;QACN,WAAW;QACX,SAAS;QACT,YAAY;QACZ,aAAa,EAAE,aAAa,IAAI,GAAG;QACnC,sBAAsB,EAAE,sBAAsB,IAAI,GAAG;KACrD,CAAA;AACF,CAAC"}
+{"version":3,"file":"LimitChecker.js","sourceRoot":"","sources":["../../src/run/LimitChecker.ts"],"names":[],"mappings":"AAyBA,MAAM,UAAU,mBAAmB,CAClC,MAA0B,EAC1B,KAAwB;IAExB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;IAClD,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAChD,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,KAAK,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;IACrD,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QACpD,IAAI,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YAC5C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;QACnD,CAAC;QACD,oEAAoE;QACpE,oEAAoE;QACpE,wEAAwE;QACxE,qEAAqE;QACrE,sEAAsE;QACtE,6CAA6C;QAC7C,sEAAsE;QACtE,IAAI,KAAK,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAA;QAC1D,CAAC;IACF,CAAC;IAED,IAAI,KAAK,CAAC,gBAAgB,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;IACvD,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAA;QACzD,IAAI,UAAU,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;YACjD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QACnD,CAAC;IACF,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,YAAY,CAAA;QACvD,IAAI,SAAS,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;YAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;QACjD,CAAC;IACF,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAA;IAChD,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC,SAAS,CAAA;IAChD,IAAI,SAAS,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAC9C,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACtB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,WAAmB,EACnB,SAAiB,EACjB,YAAqB,EACrB,aAAsB,EACtB,sBAA+B;IAE/B,OAAO;QACN,WAAW;QACX,SAAS;QACT,YAAY;QACZ,aAAa,EAAE,aAAa,IAAI,GAAG;QACnC,sBAAsB,EAAE,sBAAsB,IAAI,GAAG;KACrD,CAAA;AACF,CAAC"}

package/dist/run/command-gate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 type { CommandOptions, CommandResult } from '../types/execution/index.js';
+import type { ReviewAnswer } from '../types/run/answer-review.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 declare const DEFAULT_GATE_TIMEOUT_MS = 600000;
+/** How many attempts the gate will EXECUTE its commands for, by default. */
+export declare 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 declare const DEFAULT_GATE_OUTPUT_CHARS = 4000;
+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 declare function clipOutput(text: string, max: number): string;
+/**
+ * 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 declare function createCommandGate(options: CommandGateOptions): ReviewAnswer;
+//# sourceMappingURL=command-gate.d.ts.map

package/dist/run/command-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-gate.d.ts","sourceRoot":"","sources":["../../src/run/command-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChF,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAG/E,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,cAAc,KACpB,OAAO,CAAC,aAAa,CAAC,CAAA;AAE3B,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAE9C,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAA;AAE9C,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACnD;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM5D;AA6CD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CAiE3E"}

package/dist/run/command-gate.js

@@ -0,0 +1,157 @@
+/**
+ * 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 { fingerprintWorkspace } from './workspace-fingerprint.js';
+/** 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;
+/** Head and tail of a command's output, with the middle marked as dropped. */
+export function clipOutput(text, max) {
+    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)}`;
+}
+function failureFeedback(command, attempt, result, maxOutputChars) {
+    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, attempt) {
+    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, maxRetries) {
+    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) {
+    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 = 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;
+    let executions = 0;
+    return async () => {
+        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 };
+    };
+}
+//# sourceMappingURL=command-gate.js.map

package/dist/run/command-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-gate.js","sourceRoot":"","sources":["../../src/run/command-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AASjE,wEAAwE;AACxE,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAA;AAE9C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAA;AA2C9C,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,GAAW;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAA;IAC9B,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,OAAO,CAAA;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAA;IAChC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC,CAAA;IACzC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,OAAO,0BAA0B,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAA;AAC/F,CAAC;AAQD,SAAS,eAAe,CACvB,OAAe,EACf,OAAe,EACf,MAAqB,EACrB,cAAsB;IAEtB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAA;IAC/E,OAAO;QACN,kCAAkC,OAAO,sBAAsB,OAAO,UAAU,MAAM,CAAC,QAAQ,IAAI;QACnG,EAAE;QACF,SAAS;QACT,KAAK;QACL,MAAM,IAAI,aAAa;QACvB,KAAK;QACL,EAAE;QACF,8GAA8G;KAC9G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe,EAAE,OAAe;IAC1D,OAAO;QACN,sCAAsC,OAAO,8BAA8B,OAAO,IAAI;QACtF,EAAE;QACF,+MAA+M;QAC/M,EAAE;QACF,mJAAmJ;KACnJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe,EAAE,UAAkB;IAC7D,OAAO;QACN,kCAAkC,OAAO,6CAA6C,UAAU,YAAY;QAC5G,EAAE;QACF,iCAAiC;KACjC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC5D,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,OAAO,CAAA;IACjC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,uBAAuB,CAAA;IAC9D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,wBAAwB,CAAA;IACjE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,yBAAyB,CAAA;IAE1E,0EAA0E;IAC1E,oEAAoE;IACpE,MAAM,OAAO,GAAG,IAAI,qBAAqB,CAAC,EAAE,EAAE,EAAE,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAA;IAC5E,MAAM,IAAI,GACT,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;IACvF,MAAM,WAAW,GAChB,OAAO,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;IAEtF,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,IAA6B,CAAA;IACjC,IAAI,UAAU,GAAG,CAAC,CAAA;IAElB,OAAO,KAAK,IAA2B,EAAE;QACxC,OAAO,IAAI,CAAC,CAAA;QAEZ,qEAAqE;QACrE,wDAAwD;QACxD,EAAE;QACF,sEAAsE;QACtE,4DAA4D;QAC5D,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,yBAAyB;QACzB,IAAI,IAAI,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAA;YAC/B,IAAI,GAAG,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAA;YAC7E,CAAC;QACF,CAAC;QAED,IAAI,IAAI,IAAI,UAAU,IAAI,UAAU,EAAE,CAAC;YACtC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAA;QAChF,CAAC;QAED,UAAU,IAAI,CAAC,CAAA;QACf,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,kEAAkE;YAClE,oEAAoE;YACpE,kEAAkE;YAClE,oEAAoE;YACpE,kEAAkE;YAClE,kCAAkC;YAClC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACvE,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;gBAAE,SAAQ;YAEnC,mEAAmE;YACnE,oEAAoE;YACpE,iEAAiE;YACjE,uDAAuD;YACvD,IAAI,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,EAAE,EAAE,CAAA;YACpD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,CAAA;QAC9F,CAAC;QAED,uEAAuE;QACvE,uCAAuC;QACvC,IAAI,GAAG,SAAS,CAAA;QAChB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;IACxB,CAAC,CAAA;AACF,CAAC"}

package/dist/run/index.d.ts

@@ -4,6 +4,12 @@ export { createRunReporter } from './reporter.js';
 export type { RunReporter } from './reporter.js';
 export { DEFAULT_DRAIN_PAGE_SIZE, drainRuns } from './drain.js';
 export type { DrainFailure, DrainRun, DrainRunsParams, DrainRunsResult } from './drain.js';
+export { DEFAULT_GATE_MAX_RETRIES, DEFAULT_GATE_OUTPUT_CHARS, DEFAULT_GATE_TIMEOUT_MS, clipOutput, createCommandGate, } from './command-gate.js';
+export type { CommandGateOptions, GateExec } from './command-gate.js';
+export { FINGERPRINT_MAX_BYTES, FINGERPRINT_TIMEOUT_MS, fingerprintWorkspace, } from './workspace-fingerprint.js';
+export type { FingerprintExec, WorkspaceFingerprintOptions } from './workspace-fingerprint.js';
 export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js';
 export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js';
+export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js';
+export type { MemoryPromoterOptions } from './memory-promoter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/run/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE1F,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACN,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,GACjB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,EACN,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACpB,MAAM,4BAA4B,CAAA;AACnC,YAAY,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AAE9F,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAE5E,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/run/index.js

@@ -2,5 +2,8 @@ export { RunPersistence } from '../manager/run/persistence.js';
 export { RunDiskStore } from '../store/run/disk.js';
 export { createRunReporter } from './reporter.js';
 export { DEFAULT_DRAIN_PAGE_SIZE, drainRuns } from './drain.js';
+export { DEFAULT_GATE_MAX_RETRIES, DEFAULT_GATE_OUTPUT_CHARS, DEFAULT_GATE_TIMEOUT_MS, clipOutput, createCommandGate, } from './command-gate.js';
+export { FINGERPRINT_MAX_BYTES, FINGERPRINT_TIMEOUT_MS, fingerprintWorkspace, } from './workspace-fingerprint.js';
 export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js';
+export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js';
 //# sourceMappingURL=index.js.map

package/dist/run/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGjD,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAG/D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGjD,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/D,OAAO,EACN,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACN,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACpB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAGzE,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/run/memory-promoter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import type { MemoryStore } from '../types/memory/index.js';
+import type { PromoteMemory } from '../types/run/memory-promotion.js';
+/** Tag every record this promoter writes, so a host can find or prune them. */
+export declare const RUN_MEMORY_TAG = "run-memory";
+export interface MemoryPromoterOptions {
+    /** Where records go. The same store `save_memory` writes through. */
+    readonly store: MemoryStore;
+    /**
+     * Extra tags on every record, beyond {@link RUN_MEMORY_TAG}.
+     *
+     * A host running several agents against one store uses this to tell whose
+     * memory is whose; without it a later search cannot.
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Cap on entries rendered per category. Defaults to 20.
+     *
+     * The extractor already caps its lists, and this is the second cap for
+     * the same reason the first exists: a record nobody will read is a record
+     * that costs context every time it is retrieved.
+     */
+    readonly maxPerCategory?: number;
+}
+/**
+ * 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 declare function createMemoryPromoter(options: MemoryPromoterOptions): PromoteMemory;
+//# sourceMappingURL=memory-promoter.d.ts.map

package/dist/run/memory-promoter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-promoter.d.ts","sourceRoot":"","sources":["../../src/run/memory-promoter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,kCAAkC,CAAA;AAkBzF,+EAA+E;AAC/E,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C,MAAM,WAAW,qBAAqB;IACrC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC;AA6CD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAuBlF"}

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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"}