balladeer 1.0.19 → 1.0.21

package/dist/commands/mcp.d.ts

@@ -1,3 +1,4 @@
+import { type SelfUpdateDeps } from "../self-update.js";
 import { type StoredAgent } from "../store.js";
 export { forwarderHeaders, selectAgent, type AgentSelection } from "../agent.js";
 export type McpOptions = Readonly<{
@@ -15,6 +16,9 @@ export type McpOptions = Readonly<{
     stdin: NodeJS.ReadableStream;
     write: (text: string) => void;
     error: (text: string) => void;
+    now?: () => number;
+    /** Runs the background update; injected so tests never reach npm. */
+    startUpdate?: SelfUpdateDeps["run"];
 }>;
 export type ProbeResult = Readonly<{
     kind: "answered";

package/dist/commands/mcp.js

@@ -1,10 +1,11 @@
 import { createInterface } from "node:readline";
 import { callAgentTool, forwarderHeaders, noAgentCredentialSentence, safeJson, selectAgent, structuredString, updateLine, } from "../agent.js";
-import { noteServerVersion, updateNotice } from "../currency.js";
+import { newerVersionPublished, noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint, repositoryHints } from "../repository.js";
 import { CLI_VERSION } from "../wire.js";
 import { untrackedLine } from "./guidance.js";
 import { hooksAwaitingTrust, hooksAwaitingTrustNotice, trustingHost } from "../hook-trust.js";
+import { startSelfUpdateIfDue } from "../self-update.js";
 import { StoreError, readCredentials } from "../store.js";
 // The three commands that use an agent connection select and address it through
 // one module. These are re-exported because this is where the forwarder's
@@ -12,6 +13,8 @@ import { StoreError, readCredentials } from "../store.js";
 export { forwarderHeaders, selectAgent } from "../agent.js";
 const MAX_REQUEST_BYTES = 1024 * 1024;
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** How often one long-running forwarder looks at whether an update is due. */
+const UPDATE_CHECK_MS = 60 * 60 * 1000;
 /**
  * One real call over the connection just issued, before anything claims it
  * works.
@@ -195,6 +198,8 @@ export async function runMcp(options) {
     // user-scope hook had just switched off. It installs nothing now.
     const { agent } = selection;
     let saidUpdate = false;
+    let updateCheckedAt = Number.NEGATIVE_INFINITY;
+    const clock = options.now ?? Date.now;
     // Which host this session belongs to is known from its hello; whether its
     // hooks are waiting for the person's trust is asked at the first tool call,
     // by which time a trusted session-start hook has certainly run.
@@ -230,6 +235,24 @@ export async function runMcp(options) {
             saidUpdate = true;
             options.error(`${notice}\n`);
         }
+        // The guidance hook is not the only way in. Codex skips a hook nobody has
+        // trusted, and a Codex-only laptop (Luke's, at Didero) then never started
+        // an update at all, while this forwarder ran every session. So the
+        // forwarder starts the same background install, under the same stamp,
+        // looking at most once an hour however many frames pass.
+        if (newerVersionPublished() !== undefined && clock() - updateCheckedAt >= UPDATE_CHECK_MS) {
+            updateCheckedAt = clock();
+            try {
+                startSelfUpdateIfDue(newerVersionPublished(), {
+                    environment: options.environment,
+                    now: clock,
+                    ...(options.startUpdate ? { run: options.startUpdate } : {}),
+                });
+            }
+            catch {
+                /* An update that cannot even be considered never costs the session its tools. */
+            }
+        }
         if (response.status === 401) {
             options.write(`${revokedConnectionFrame(frameId(line), options.controlPlane)}\n`);
             options.error("Balladeer refused this agent connection. Rotate it in Balladeer.\n");

package/dist/currency.js

@@ -60,10 +60,16 @@ export function noteServerVersion(headers) {
     newestSeen = newest;
     const advice = headers.get(CLI_ADVICE_HEADER);
     const line = advice === null ? "" : bounded(advice);
+    // On this copy's own major the background update installs it (it lands
+    // from 1.0.21), so there is nothing to tell anyone to run. Another major
+    // is a choice a person makes.
+    const sameMajor = newest.split(".")[0] === CLI_VERSION.split(".")[0];
     notice =
-        line === ""
-            ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.`
-            : line;
+        line !== ""
+            ? line
+            : sameMajor
+                ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). It installs in the background; nothing needs to be run.`
+                : `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.`;
 }
 /** The one line this run prints about itself, or nothing when it is current. */
 export function updateNotice() {

package/dist/guidance-hook.mjs

@@ -2152,7 +2152,7 @@ function relayHook(input, directory) {
 }
 
 // src/wire.ts
-var CLI_VERSION = "1.0.19";
+var CLI_VERSION = "1.0.21";
 var CLIENT_HEADER = "x-balladeer-client";
 var UPDATE_STATE_HEADER = "x-balladeer-update-state";
 var HOOK_HOST_HEADER = "x-balladeer-hook";
@@ -2289,7 +2289,8 @@ function noteServerVersion(headers) {
   newestSeen = newest;
   const advice = headers.get(CLI_ADVICE_HEADER);
   const line = advice === null ? "" : bounded(advice);
-  notice = line === "" ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.` : line;
+  const sameMajor = newest.split(".")[0] === CLI_VERSION.split(".")[0];
+  notice = line !== "" ? line : sameMajor ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). It installs in the background; nothing needs to be run.` : `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.`;
 }
 function newerVersionPublished() {
   return newestSeen;
@@ -2334,6 +2335,13 @@ function due(newer, last, now) {
   const newerTarget = last.toward === void 0 || older(last.toward, newer);
   return newerTarget && since >= HOUR_MS;
 }
+function updateSpecifier(newer) {
+  if (!VERSION2.test(newer)) return void 0;
+  const [name, major] = HOOK_SPECIFIER.split("@");
+  if (newer.split(".")[0] !== major) return void 0;
+  if (!older(CLI_VERSION, newer)) return void 0;
+  return `${name}@${newer}`;
+}
 function writePrivate(path, value, environment) {
   mkdirSync3(configHome(environment), { recursive: true, mode: 448 });
   writeFileSync2(path, JSON.stringify(value) + "\n", { mode: 384 });
@@ -2375,9 +2383,11 @@ function detached(command, args, environment) {
 }
 function startSelfUpdateIfDue(newer, deps) {
   if (newer === void 0) return false;
+  const specifier = updateSpecifier(newer);
+  if (specifier === void 0) return false;
   const now = deps.now ?? Date.now;
   if (!due(newer, lastAttempt(deps.environment), now())) return false;
-  const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
+  const launch = resolveLaunch(specifier, deps.environment, deps.execPath, deps.exists);
   let started;
   try {
     started = (deps.run ?? detached)(launch.command, launch.args, launch.environment) !== false;

package/dist/headless-agent.d.ts

@@ -133,6 +133,7 @@ export declare function verifyLogin(client: HeadlessClient, options: Readonly<{
     cwd: string;
     spawn?: SpawnLike;
     killGroup?: KillGroup;
+    deadline?: number;
 }>): Promise<LoginCheck>;
 /**
  * The client to run, or none. `auto` tries the hook's own client first, then
@@ -144,6 +145,7 @@ export declare function resolveClient(requested: HeadlessClient | "auto", option
     prefer?: HeadlessClient;
     spawn?: SpawnLike;
     killGroup?: KillGroup;
+    deadline?: number;
 }>): Promise<LoginCheck | undefined>;
 /**
  * The last JSON object in a piece of text.

package/dist/headless-agent.js

@@ -99,13 +99,15 @@ export function codexArguments(input) {
  * dropped, the same way the compatibility canary treats them.
  */
 export async function verifyLogin(client, options) {
+    if (options.deadline !== undefined && Date.now() >= options.deadline)
+        return { client, verified: false };
     const env = agentEnvironment(options.env);
     const run = await runOwnedProcess({
         command: clientBinary(client, options.env),
         args: client === "claude" ? ["auth", "status", "--json"] : ["login", "status"],
         cwd: options.cwd,
         env,
-        timeoutMs: 15_000,
+        timeoutMs: Math.max(1, Math.min(15_000, (options.deadline ?? Number.POSITIVE_INFINITY) - Date.now())),
         maxOutputBytes: 64 * 1024,
         ...(options.spawn === undefined ? {} : { spawn: options.spawn }),
         ...(options.killGroup === undefined ? {} : { killGroup: options.killGroup }),
@@ -136,6 +138,8 @@ export async function resolveClient(requested, options) {
             ? ["codex", "claude"]
             : ["claude", "codex"];
     for (const client of order) {
+        if (options.deadline !== undefined && Date.now() >= options.deadline)
+            return undefined;
         const check = await verifyLogin(client, options);
         if (check.verified)
             return check;

package/dist/judge-brief.d.ts

@@ -2,10 +2,10 @@ import type { PromiseAnchors } from "./anchors-schema.js";
 import type { BehaviorMap } from "./behavior-map-schema.js";
 import type { PromiseDocument } from "./promise-meaning.js";
 /**
- * The fixed instructions a judge works from, `judge-brief/v5`.
+ * The fixed instructions a judge works from, `judge-brief/v7`.
  *
  * One promise, one change, one disposable checkout at the change's head. The
- * rules are the contract's: cases first, linked test first, broken only with a
+ * rules are the contract's: cases first, source-grounded review, broken only with a
  * command that fails with the change and passes without it, kept only after
  * each passing case was exercised, and could not tell for everything else,
  * with what stopped the judge. The runner checks the reproduction itself by
@@ -15,7 +15,13 @@ import type { PromiseDocument } from "./promise-meaning.js";
  * The text is a constant so a verdict can name the exact brief it was given.
  * Changing a word here is a new revision.
  *
- * v5 is v3's rules word for word; what it added is a section of the prompt
+ * v7 requires a substantive code review before settling a verdict: trace affected
+ * behavior, assess test blind spots, and preserve risks and uncertainty locally.
+ * Tests support the review; writing new tests is optional. v6 requires explicit
+ * commands for passing-case evidence and names every new
+ * evidence file. The runner executes frozen artifacts in fresh checkouts, then
+ * a separate local reviewer assesses their semantic fidelity. v5 used v3's
+ * rules; what it added is a section of the prompt
  * (1 October 2026, with promise anchors): a promise with anchors and no
  * behavior map is handed its anchors, the linked tests the graph gives at
  * head, and the files one import step from its anchor files, where v3 said
@@ -24,7 +30,7 @@ import type { PromiseDocument } from "./promise-meaning.js";
  * adopted on 30 September, so it is never reused. The judge with anchors in
  * place of a map has not been measured yet.
  */
-export declare const JUDGE_BRIEF_REVISION = "judge-brief/v5";
+export declare const JUDGE_BRIEF_REVISION = "judge-brief/v7";
 /**
  * What `judge-brief/v3` added to v1, and all it added (Robert, 30 September
  * 2026): a way forward when the tests need something the machine lacks.
@@ -37,7 +43,7 @@ export declare const JUDGE_BRIEF_REVISION = "judge-brief/v5";
  * thing in the answer is `nextStep`, the one step that would let the tests run.
  */
 export declare const JUDGE_BRIEF_SETUP_RULE = "9. Only when you would otherwise answer \"could_not_tell\" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays \"could_not_tell\", never \"kept\", and you add \"nextStep\" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.";
-export declare const JUDGE_BRIEF = "You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.\n\nDecide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.\n\nRules:\n\n1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.\n2. If linked tests are listed, run them first, before anything else. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output.\n3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.\n4. Report \"broken\" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with `git checkout --detach <base>`, run the command, then return with `git checkout --detach <head>`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.\n5. Report \"kept\" only after you have exercised each passing case against the changed code, by running a test or a command that shows it, and list every case you exercised.\n6. Anything else is \"could_not_tell\". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.\n7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.\n8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.\n9. Only when you would otherwise answer \"could_not_tell\" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays \"could_not_tell\", never \"kept\", and you add \"nextStep\" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"promiseId\": \"<the promise id below>\", \"verdict\": \"kept\" | \"broken\" | \"could_not_tell\", \"reproduction\": {\"command\": \"<shell command>\", \"cwd\": \".\"} or null, \"exercisedCases\": [\"passing-1\", ...], \"notes\": \"<at most a few sentences>\"}\n\nA reproduction is required for \"broken\" and optional otherwise.";
+export declare const JUDGE_BRIEF = "You are judging one change to this repository against one promise about the software's behavior. The supplied meaning may be recorded or agreed; use its supplied standing and never infer human agreement or protection. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.\n\nYour primary job is a substantive code review against this promise. Understand the affected behavior and investigate plausible failures, then decide whether this change keeps the promise, breaks it, or whether you could not tell. Tests and experiments support your review; generating tests is not the goal.\n\nReview approach:\n- Read the actual diff and the relevant implementation at head and base. Trace the affected behavior from its entry points through changed functions, unchanged callers, dependencies and observable effects. Follow a path beyond the supplied anchors when the behavior requires it; shared words or nearby files are not a reason to expand scope.\n- Explain what changed behaviorally and why it matters to this promise. Investigate realistic failure conditions, alternate branches and boundary cases grounded in this code. Consider state, retries, ordering, error handling and permissions where they affect the promised behavior; do not manufacture concerns that do not fit its scope.\n- Inspect the assertions and inputs of relevant existing tests. A passing suite does not settle your review: identify which affected paths it covers and what it misses. Prefer the repository's own entry points and existing checks. Use a focused command, experiment or new test when it resolves a concrete question. Do not mock away the behavior under review or assert implementation spelling instead of observable behavior.\n- Spend the available time on the most consequential uncertainties. Do not stop after a superficial glance or a trivially passing test, and do not pad the review with extra files or tests. Return a concise assessment, not private deliberation: the causal path you established, relevant files you actually inspected, concrete remaining risks and limits of your investigation. State no unresolved risks when you found none; distinguish a plausible concern from an observed failure.\n\nRules:\n\n1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.\n2. If linked tests are listed, inspect how they exercise this promise and run the relevant checks as part of your investigation. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output. Neither a passing linked test nor its failure substitutes for reviewing the affected code.\n3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.\n4. Report \"broken\" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with `git checkout --detach <base>`, run the command, then return with `git checkout --detach <head>`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.\n5. Report \"kept\" only after reviewing the affected behavior and exercising each passing case against the changed code, by running a test or a command that shows it. Return \"caseEvidence\" entries containing caseIds, command and cwd for every passing case. One command may cover several cases only when its inputs and assertions exercise each one. The runner will execute these commands itself in a fresh head checkout; listing case IDs or inspecting code alone cannot establish kept. If a concrete concern about this promise remains unresolved, answer \"could_not_tell\" and preserve that concern in your review.\n6. Anything else is \"could_not_tell\". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.\n7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.\n8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.\n9. Only when you would otherwise answer \"could_not_tell\" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays \"could_not_tell\", never \"kept\", and you add \"nextStep\" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.\n\nList every new file your evidence commands need in \"evidenceFiles\", as repository-relative paths. Include only new regular files, never edits to tracked files or symlinks. Use [] when the commands need no new files. The runner carries only these frozen files into fresh execution checkouts, with the laptop's existing local dependencies. Ignored files or state from your exploration do not travel unless explicitly named. Evidence commands must not change tracked code, their own evidence artifacts or the checked-out commit. A separate local reader reviews whether the commands and assertions actually exercise the promise. Neither independent execution nor that review establishes protection.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"promiseId\": \"<the promise id below>\", \"verdict\": \"kept\" | \"broken\" | \"could_not_tell\", \"reproduction\": {\"command\": \"<shell command>\", \"cwd\": \".\"} or null, \"exercisedCases\": [\"passing-1\", ...], \"caseEvidence\": [{\"caseIds\": [\"passing-1\"], \"command\": \"<shell command>\", \"cwd\": \".\"}], \"evidenceFiles\": [\"<new evidence file>\"], \"review\": {\"summary\": \"<concise behavioral assessment with the causal path and test blind spots>\", \"inspectedFiles\": [\"<repository-relative files actually inspected>\"], \"risks\": [\"<path/function, triggering condition and promised consequence of an unresolved concern>\"], \"limitations\": [\"<what you could not investigate or exercise>\"]}, \"notes\": \"<at most a few sentences>\"}\n\nA reproduction is required for \"broken\" and optional otherwise.";
 export type JudgeBriefInput = Readonly<{
     promise: PromiseDocument;
     map?: BehaviorMap;

package/dist/judge-brief.js

@@ -1,8 +1,8 @@
 /**
- * The fixed instructions a judge works from, `judge-brief/v5`.
+ * The fixed instructions a judge works from, `judge-brief/v7`.
  *
  * One promise, one change, one disposable checkout at the change's head. The
- * rules are the contract's: cases first, linked test first, broken only with a
+ * rules are the contract's: cases first, source-grounded review, broken only with a
  * command that fails with the change and passes without it, kept only after
  * each passing case was exercised, and could not tell for everything else,
  * with what stopped the judge. The runner checks the reproduction itself by
@@ -12,7 +12,13 @@
  * The text is a constant so a verdict can name the exact brief it was given.
  * Changing a word here is a new revision.
  *
- * v5 is v3's rules word for word; what it added is a section of the prompt
+ * v7 requires a substantive code review before settling a verdict: trace affected
+ * behavior, assess test blind spots, and preserve risks and uncertainty locally.
+ * Tests support the review; writing new tests is optional. v6 requires explicit
+ * commands for passing-case evidence and names every new
+ * evidence file. The runner executes frozen artifacts in fresh checkouts, then
+ * a separate local reviewer assesses their semantic fidelity. v5 used v3's
+ * rules; what it added is a section of the prompt
  * (1 October 2026, with promise anchors): a promise with anchors and no
  * behavior map is handed its anchors, the linked tests the graph gives at
  * head, and the files one import step from its anchor files, where v3 said
@@ -21,7 +27,7 @@
  * adopted on 30 September, so it is never reused. The judge with anchors in
  * place of a map has not been measured yet.
  */
-export const JUDGE_BRIEF_REVISION = "judge-brief/v5";
+export const JUDGE_BRIEF_REVISION = "judge-brief/v7";
 /**
  * What `judge-brief/v3` added to v1, and all it added (Robert, 30 September
  * 2026): a way forward when the tests need something the machine lacks.
@@ -34,25 +40,33 @@ export const JUDGE_BRIEF_REVISION = "judge-brief/v5";
  * thing in the answer is `nextStep`, the one step that would let the tests run.
  */
 export const JUDGE_BRIEF_SETUP_RULE = `9. Only when you would otherwise answer "could_not_tell" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays "could_not_tell", never "kept", and you add "nextStep" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.`;
-export const JUDGE_BRIEF = `You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.
+export const JUDGE_BRIEF = `You are judging one change to this repository against one promise about the software's behavior. The supplied meaning may be recorded or agreed; use its supplied standing and never infer human agreement or protection. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.
 
-Decide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.
+Your primary job is a substantive code review against this promise. Understand the affected behavior and investigate plausible failures, then decide whether this change keeps the promise, breaks it, or whether you could not tell. Tests and experiments support your review; generating tests is not the goal.
+
+Review approach:
+- Read the actual diff and the relevant implementation at head and base. Trace the affected behavior from its entry points through changed functions, unchanged callers, dependencies and observable effects. Follow a path beyond the supplied anchors when the behavior requires it; shared words or nearby files are not a reason to expand scope.
+- Explain what changed behaviorally and why it matters to this promise. Investigate realistic failure conditions, alternate branches and boundary cases grounded in this code. Consider state, retries, ordering, error handling and permissions where they affect the promised behavior; do not manufacture concerns that do not fit its scope.
+- Inspect the assertions and inputs of relevant existing tests. A passing suite does not settle your review: identify which affected paths it covers and what it misses. Prefer the repository's own entry points and existing checks. Use a focused command, experiment or new test when it resolves a concrete question. Do not mock away the behavior under review or assert implementation spelling instead of observable behavior.
+- Spend the available time on the most consequential uncertainties. Do not stop after a superficial glance or a trivially passing test, and do not pad the review with extra files or tests. Return a concise assessment, not private deliberation: the causal path you established, relevant files you actually inspected, concrete remaining risks and limits of your investigation. State no unresolved risks when you found none; distinguish a plausible concern from an observed failure.
 
 Rules:
 
 1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.
-2. If linked tests are listed, run them first, before anything else. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output.
+2. If linked tests are listed, inspect how they exercise this promise and run the relevant checks as part of your investigation. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output. Neither a passing linked test nor its failure substitutes for reviewing the affected code.
 3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.
 4. Report "broken" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with \`git checkout --detach <base>\`, run the command, then return with \`git checkout --detach <head>\`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.
-5. Report "kept" only after you have exercised each passing case against the changed code, by running a test or a command that shows it, and list every case you exercised.
+5. Report "kept" only after reviewing the affected behavior and exercising each passing case against the changed code, by running a test or a command that shows it. Return "caseEvidence" entries containing caseIds, command and cwd for every passing case. One command may cover several cases only when its inputs and assertions exercise each one. The runner will execute these commands itself in a fresh head checkout; listing case IDs or inspecting code alone cannot establish kept. If a concrete concern about this promise remains unresolved, answer "could_not_tell" and preserve that concern in your review.
 6. Anything else is "could_not_tell". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.
 7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.
 8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.
 ${JUDGE_BRIEF_SETUP_RULE}
 
+List every new file your evidence commands need in "evidenceFiles", as repository-relative paths. Include only new regular files, never edits to tracked files or symlinks. Use [] when the commands need no new files. The runner carries only these frozen files into fresh execution checkouts, with the laptop's existing local dependencies. Ignored files or state from your exploration do not travel unless explicitly named. Evidence commands must not change tracked code, their own evidence artifacts or the checked-out commit. A separate local reader reviews whether the commands and assertions actually exercise the promise. Neither independent execution nor that review establishes protection.
+
 Your final message must be exactly one JSON object and nothing after it:
 
-{"promiseId": "<the promise id below>", "verdict": "kept" | "broken" | "could_not_tell", "reproduction": {"command": "<shell command>", "cwd": "."} or null, "exercisedCases": ["passing-1", ...], "notes": "<at most a few sentences>"}
+{"promiseId": "<the promise id below>", "verdict": "kept" | "broken" | "could_not_tell", "reproduction": {"command": "<shell command>", "cwd": "."} or null, "exercisedCases": ["passing-1", ...], "caseEvidence": [{"caseIds": ["passing-1"], "command": "<shell command>", "cwd": "."}], "evidenceFiles": ["<new evidence file>"], "review": {"summary": "<concise behavioral assessment with the causal path and test blind spots>", "inspectedFiles": ["<repository-relative files actually inspected>"], "risks": ["<path/function, triggering condition and promised consequence of an unresolved concern>"], "limitations": ["<what you could not investigate or exercise>"]}, "notes": "<at most a few sentences>"}
 
 A reproduction is required for "broken" and optional otherwise.`;
 const CHANGED_FILES_SHOWN = 300;
@@ -69,10 +83,12 @@ export function judgePrompt(input) {
         promiseId: input.promise.promiseId,
         title: input.promise.title,
         semanticDigest: input.promise.semanticDigest,
+        standing: input.promise.standing,
+        subject: input.promise.subject,
         meaning: input.promise.meaning,
     }, null, 2));
     if (input.promise.meaning.passingExamples.length === 0)
-        sections.push("Its passing cases were not available here, so no case can be exercised; answer kept only if you can say from the code that none of the failing cases can happen.");
+        sections.push("Its passing cases were not available here, so kept cannot be established by executable case evidence; answer broken with a reproduction or could_not_tell.");
     sections.push("");
     if (input.map !== undefined) {
         // The excerpt repeats the promise printed above; the judge reads it once.

package/dist/judge-evidence.d.ts

@@ -0,0 +1,87 @@
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type LoginCheck } from "./headless-agent.js";
+import { type PromiseDocument } from "./promise-meaning.js";
+import { type CarriedFile } from "./scratch-worktree.js";
+/** Local execution provenance, not proof that an assertion expresses the promise. */
+export declare const EVIDENCE_PROTOCOL_REVISION = "judge-evidence/v1";
+export type CaseEvidence = Readonly<{
+    caseIds: readonly string[];
+    command: string;
+    cwd: string;
+}>;
+export type FrozenEvidenceFile = CarriedFile & Readonly<{
+    bytes: Buffer;
+}>;
+export type FrozenEvidenceManifest = Readonly<{
+    files: readonly FrozenEvidenceFile[];
+    digest: string;
+}>;
+export type EvidenceReceipt = Readonly<{
+    caseIds: readonly string[];
+    command: string;
+    cwd: string;
+    commit: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    durationMs: number;
+    artifactDigest: string;
+    dependencyMode: "shared-local";
+    /** Local lockfile fingerprints describe declared dependencies, not installed-byte integrity. */
+    localDependencyLocks: readonly CarriedFile[];
+    nodeVersion: string;
+    platform: NodeJS.Platform;
+    output: string;
+}>;
+export type EvidenceExecution = Readonly<{
+    receipts: readonly EvidenceReceipt[];
+    rejected: string | null;
+    stopped: boolean;
+}>;
+type LocalInput = Readonly<{
+    root: string;
+    sourceTree: string;
+    head: string;
+    manifest: FrozenEvidenceManifest;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    scratch?: string;
+}>;
+export declare function freezeEvidenceFiles(sourceTree: string, paths: readonly string[]): Promise<{
+    ok: true;
+    manifest: FrozenEvidenceManifest;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function executeKeptEvidence(input: LocalInput & Readonly<{
+    caseEvidence: readonly CaseEvidence[];
+    passingCaseIds: readonly string[];
+}>): Promise<EvidenceExecution>;
+export declare function executeFreshReproduction(input: LocalInput & Readonly<{
+    base: string;
+    command: string;
+    cwd: string;
+}>): Promise<EvidenceExecution & Readonly<{
+    failsOnHead: boolean;
+    passesOnBase: boolean;
+    digest: string;
+    files: readonly CarriedFile[];
+}>>;
+export type EvidenceReview = Readonly<{
+    accepted: boolean;
+    reason: string;
+    stopped: boolean;
+    agent?: HeadlessAgentResult;
+}>;
+/** A fresh local reader assesses semantics; execution receipts alone cannot establish fidelity. */
+export declare function reviewExecutedEvidence(input: LocalInput & Readonly<{
+    promise: PromiseDocument;
+    base: string;
+    claim: "kept" | "broken";
+    review?: import("./judge-review.js").CodeReview;
+    receipts: readonly EvidenceReceipt[];
+    login: LoginCheck;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>): Promise<EvidenceReview>;
+export {};