balladeer 1.0.16 → 1.0.18

package/dist/guidance.d.ts

@@ -12,6 +12,13 @@ export type GuidanceEvent = "SessionStart" | "SubagentStart" | "UserPromptSubmit
 export declare const GUIDANCE_UNAVAILABLE = "Balladeer could not verify the current workspace guidance and capture mode. Continue the user's authorized work, but do not make unsolicited capture offers or file inferred promises. Do not reuse earlier Quiet/Thorough permission or cached instructions as current. An explicit request to record still requires current Balladeer tool checks and named-human agreement to meaning; never invent approval. Retry current guidance at the next hook boundary.";
 export declare function parseGuidance(value: unknown, agent: StoredAgent): GuidanceDocument;
 export declare function guidanceEndpoint(agent: StoredAgent): URL;
+/**
+ * A route of the server this repository's agent connection belongs to, scoped
+ * to its workspace and repository the way `/api/agent-guidance` is: same
+ * origin as the connection's MCP address, https only, and the scope in the
+ * query exactly once.
+ */
+export declare function agentEndpoint(agent: StoredAgent, pathname: string): URL;
 export declare function guidanceScopeKey(agent: StoredAgent): string;
 export type GuidanceLoad = Readonly<{
     status: "fresh" | "revalidated" | "unavailable";

package/dist/guidance.js

@@ -34,6 +34,15 @@ export function parseGuidance(value, agent) {
     return value;
 }
 export function guidanceEndpoint(agent) {
+    return agentEndpoint(agent, "/api/agent-guidance");
+}
+/**
+ * A route of the server this repository's agent connection belongs to, scoped
+ * to its workspace and repository the way `/api/agent-guidance` is: same
+ * origin as the connection's MCP address, https only, and the scope in the
+ * query exactly once.
+ */
+export function agentEndpoint(agent, pathname) {
     const url = new URL(agent.mcpUrl);
     const expected = new URL(agent.controlPlane);
     if (url.origin !== expected.origin ||
@@ -54,7 +63,7 @@ export function guidanceEndpoint(agent) {
             throw new Error("invalid_guidance_scope");
         url.searchParams.set(key, value);
     }
-    url.pathname = "/api/agent-guidance";
+    url.pathname = pathname;
     return url;
 }
 function readJson(path) {

package/dist/headless-agent.d.ts

@@ -49,6 +49,11 @@ export type HeadlessAgentOptions = Readonly<{
     prefer?: HeadlessClient;
     /** Codex's sandbox. Read-only unless the run has to execute tests. */
     sandbox?: "read-only" | "workspace-write";
+    /**
+     * The run's folder is no repository on purpose (an anchoring call works in
+     * an empty folder, so it can read nothing), which Codex must be told.
+     */
+    outsideRepository?: boolean;
     /** Claude Code permission rules refused outright, such as `Bash(git push:*)`. */
     disallowedTools?: readonly string[];
     /** Fires when the caller's budget runs out; the run is stopped, not failed. */
@@ -58,6 +63,15 @@ export type HeadlessAgentOptions = Readonly<{
     /** A login already verified by the caller, so a batch checks it once. */
     login?: LoginCheck;
     maxOutputBytes?: number;
+    /**
+     * The most output tokens the model may write in this run. Claude Code is
+     * held to it by `CLAUDE_CODE_MAX_OUTPUT_TOKENS`, so a run that would go
+     * further is stopped there. Codex has no such setting (none in its
+     * configuration reference, and none in its 0.144 binary), so for Codex the
+     * run is held by its time limit and `overOutputCap` says afterwards when it
+     * wrote more than this.
+     */
+    maxOutputTokens?: number;
     /** Where the private settings directory is made. Defaults to the system temp directory. */
     scratch?: string;
 }>;
@@ -76,8 +90,10 @@ export type HeadlessAgentResult = Readonly<{
     stderrTail: string;
     timedOut: boolean;
     aborted: boolean;
+    /** The run reported more output tokens than `maxOutputTokens` allowed, or stopped at that cap. */
+    overOutputCap?: boolean;
     /** Why `ok` is false, as a code a caller can branch on. */
-    reason?: "no_verified_login" | "spawn_failed" | "timed_out" | "aborted" | "output_bounded" | "exit_nonzero" | "no_answer" | "no_json";
+    reason?: "no_verified_login" | "spawn_failed" | "timed_out" | "aborted" | "output_bounded" | "exit_nonzero" | "no_answer" | "no_json" | "output_capped";
 }>;
 /** Set on every run this module starts, so a hook inside it knows not to judge again. */
 export declare const JUDGE_ACTIVE_VARIABLE = "BALLADEER_JUDGE_ACTIVE";
@@ -102,6 +118,8 @@ export declare function claudeArguments(input: Readonly<{
 export declare function codexArguments(input: Readonly<{
     cwd: string;
     sandbox: "read-only" | "workspace-write";
+    /** The run is in a folder that is no repository on purpose, such as an empty one. */
+    outsideRepository?: boolean;
 }>): string[];
 /**
  * Whether this laptop has the subscription login the client needs.

package/dist/headless-agent.js

@@ -40,8 +40,13 @@ export function clientBinary(client, env) {
 export function claudeArguments(input) {
     const tools = (input.tools ?? input.allowedTools).join(",");
     // Rules narrower than a tool carry spaces (`Bash(git diff:*)`), so they go
-    // in as separate values rather than as one comma list.
-    const allowed = input.tools === undefined ? [tools] : [...input.allowedTools];
+    // in as separate values rather than as one comma list. A run with no tools
+    // at all (`--tools ""`) has nothing to allow, and the flag is left out.
+    const allowed = input.allowedTools.length === 0
+        ? []
+        : input.tools === undefined
+            ? [tools]
+            : [...input.allowedTools];
     return [
         "--print",
         "--output-format",
@@ -59,8 +64,7 @@ export function claudeArguments(input) {
         "dontAsk",
         "--tools",
         tools,
-        "--allowedTools",
-        ...allowed,
+        ...(allowed.length > 0 ? ["--allowedTools", ...allowed] : []),
         ...((input.disallowedTools ?? []).length > 0
             ? ["--disallowedTools", ...(input.disallowedTools ?? [])]
             : []),
@@ -77,6 +81,8 @@ export function codexArguments(input) {
         input.sandbox,
         "-C",
         input.cwd,
+        // Codex refuses to start outside a git repository unless told this.
+        ...(input.outsideRepository === true ? ["--skip-git-repo-check"] : []),
         "--json",
         "-c",
         'approval_policy="never"',
@@ -338,6 +344,8 @@ export async function runHeadlessAgent(options) {
         const env = agentEnvironment(options.env);
         let args;
         if (client === "claude") {
+            if (options.maxOutputTokens !== undefined)
+                env.CLAUDE_CODE_MAX_OUTPUT_TOKENS = String(options.maxOutputTokens);
             const settingsPath = join(privateRoot, "settings.json");
             writeFileSync(settingsPath, JSON.stringify({ disableAllHooks: true }), { mode: 0o600 });
             args = claudeArguments({
@@ -359,7 +367,11 @@ export async function runHeadlessAgent(options) {
             if (existsSync(auth))
                 symlinkSync(auth, join(codexHome, "auth.json"));
             env.CODEX_HOME = codexHome;
-            args = codexArguments({ cwd: options.cwd, sandbox: options.sandbox ?? "read-only" });
+            args = codexArguments({
+                cwd: options.cwd,
+                sandbox: options.sandbox ?? "read-only",
+                ...(options.outsideRepository === true ? { outsideRepository: true } : {}),
+            });
         }
         const run = await runOwnedProcess({
             command: clientBinary(client, options.env),
@@ -399,6 +411,11 @@ export async function runHeadlessAgent(options) {
             return failed("timed_out");
         if (run.bounded)
             return failed("output_bounded");
+        // Reaching the cap is a stop, whatever the agent managed to say before it.
+        if (options.maxOutputTokens !== undefined &&
+            parsed?.outputTokens !== undefined &&
+            parsed.outputTokens >= options.maxOutputTokens)
+            return { ...failed("output_capped"), overOutputCap: true };
         if (run.exitCode !== 0)
             return failed("exit_nonzero");
         if (parsed === undefined || parsed.isError || parsed.text.trim() === "")

package/dist/hook-trust.d.ts

@@ -16,16 +16,48 @@ export type TrustingHost = "codex";
 /** Hosts that run a hook only after the person has approved it. */
 export declare const HOSTS_REQUIRING_TRUST: readonly TrustingHost[];
 /**
- * This command wrote or changed the host's hooks, or found them in place with
- * no record that it ever had: either way, from now the host has to have run
- * them once before anybody assumes it does.
+ * Hooks this command writes as one set, each set with its own marks. The
+ * guidance hooks and the push check are written separately, and a host keeps
+ * running an unchanged hook it already trusted, so one set running says
+ * nothing about the other: once the push check was added, the trusted
+ * guidance hooks would run at the next session start and settle a single mark
+ * while the new push check still waited for review.
  */
-export declare function noteHooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost, changed: boolean, now?: number): void;
-/** One of the host's hooks ran, which it does only once they are trusted. */
-export declare function noteHookFired(environment: NodeJS.ProcessEnv, host: TrustingHost, now?: number): void;
-/** True while the hooks last written for this host have never run in it. */
+export type HookSet = "guidance" | "push-check";
+/**
+ * The push check's entry starts Node only for a command that could push
+ * (`pushCheckCommand` in user-scope.ts), so the run that settles its mark
+ * would wait for the first push, and meanwhile the person would be told to
+ * trust hooks they already trusted. This file exists exactly while that set
+ * waits for its first run in the host, and the entry sends every command
+ * through to Node while it does.
+ */
+export declare function pushCheckAwaitingFile(environment: NodeJS.ProcessEnv, host: TrustingHost): string;
+/**
+ * This command wrote or changed one set of the host's hooks, or found it in
+ * place with no record that it ever had: either way, from now the host has to
+ * have run that set once before anybody assumes it does. `hooks` is how many
+ * hooks the set is, which the notice counts.
+ */
+export declare function noteHooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost, changed: boolean, now?: number, options?: Readonly<{
+    set?: HookSet;
+    hooks?: number;
+}>): void;
+/** This command took one set of the host's hooks out: nothing of it is left to trust. */
+export declare function noteHooksRemoved(environment: NodeJS.ProcessEnv, host: TrustingHost, set: HookSet): void;
+/** One hook of that set ran, which it does only once it is trusted. */
+export declare function noteHookFired(environment: NodeJS.ProcessEnv, host: TrustingHost, now?: number, set?: HookSet): void;
+/** True while some set of the hooks last written for this host has never run in it. */
 export declare function hooksAwaitingTrust(environment: NodeJS.ProcessEnv, host: TrustingHost): boolean;
+/** A small count the way a sentence says it. */
+export declare function countWord(count: number): string;
+/** How many of Balladeer's hooks this host was last given, over every set written. */
+export declare function hooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost): number;
 /** The host a session belongs to, from the name it gave when it said hello. */
 export declare function trustingHost(clientName: unknown): TrustingHost | undefined;
-/** What the agent is asked to pass on, once, in the host where the approval happens. */
-export declare const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";
+/**
+ * What the agent is asked to pass on, once, in the host where the approval
+ * happens. It counts the hooks this command last wrote there, so a laptop given
+ * the push check is told to trust six and one without it four.
+ */
+export declare function hooksAwaitingTrustNotice(environment: NodeJS.ProcessEnv, host?: TrustingHost): string;

package/dist/hook-trust.js

@@ -1,9 +1,14 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { configHome } from "./store.js";
 /** Hosts that run a hook only after the person has approved it. */
 export const HOSTS_REQUIRING_TRUST = ["codex"];
+const SETS = ["guidance", "push-check"];
+/** How many hooks a set is, for a mark an earlier release wrote without saying. */
+const DEFAULT_COUNT = { guidance: 4, "push-check": 2 };
 const FILE = "hook-trust.json";
+/** The guidance set keeps the key earlier releases wrote, so their marks still count. */
+const key = (host, set) => set === "guidance" ? host : `${host}:${set}`;
 function read(environment) {
     try {
         const parsed = JSON.parse(readFileSync(join(configHome(environment), FILE), "utf8"));
@@ -15,49 +20,126 @@ function read(environment) {
         return {};
     }
 }
+/**
+ * The push check's entry starts Node only for a command that could push
+ * (`pushCheckCommand` in user-scope.ts), so the run that settles its mark
+ * would wait for the first push, and meanwhile the person would be told to
+ * trust hooks they already trusted. This file exists exactly while that set
+ * waits for its first run in the host, and the entry sends every command
+ * through to Node while it does.
+ */
+export function pushCheckAwaitingFile(environment, host) {
+    return join(configHome(environment), `${host}-push-check-awaiting-first-run`);
+}
+function forget(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* Left behind, it costs Node's start on each command, never a session. */
+    }
+}
 function write(environment, marks) {
     try {
         mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
         writeFileSync(join(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
             mode: 0o600,
         });
+        for (const host of HOSTS_REQUIRING_TRUST) {
+            const file = pushCheckAwaitingFile(environment, host);
+            if (awaiting(marks[key(host, "push-check")]))
+                writeFileSync(file, "", { mode: 0o600 });
+            else
+                forget(file);
+        }
     }
     catch {
         /* A mark that cannot be written costs a notice, never a session. */
     }
 }
 /**
- * This command wrote or changed the host's hooks, or found them in place with
- * no record that it ever had: either way, from now the host has to have run
- * them once before anybody assumes it does.
+ * This command wrote or changed one set of the host's hooks, or found it in
+ * place with no record that it ever had: either way, from now the host has to
+ * have run that set once before anybody assumes it does. `hooks` is how many
+ * hooks the set is, which the notice counts.
  */
-export function noteHooksWritten(environment, host, changed, now = Date.now()) {
+export function noteHooksWritten(environment, host, changed, now = Date.now(), options = {}) {
+    const set = options.set ?? "guidance";
+    const marks = read(environment);
+    const mark = marks[key(host, set)];
+    const counted = options.hooks === undefined || mark?.hooks === options.hooks;
+    if (!changed && mark?.writtenAt !== undefined && counted)
+        return;
+    write(environment, {
+        ...marks,
+        [key(host, set)]: {
+            ...mark,
+            ...(changed || mark?.writtenAt === undefined ? { writtenAt: now } : {}),
+            ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
+        },
+    });
+}
+/** This command took one set of the host's hooks out: nothing of it is left to trust. */
+export function noteHooksRemoved(environment, host, set) {
     const marks = read(environment);
-    if (!changed && marks[host]?.writtenAt !== undefined)
+    if (marks[key(host, set)] === undefined)
         return;
-    write(environment, { ...marks, [host]: { ...marks[host], writtenAt: now } });
+    const rest = { ...marks };
+    delete rest[key(host, set)];
+    write(environment, rest);
 }
-/** One of the host's hooks ran, which it does only once they are trusted. */
-export function noteHookFired(environment, host, now = Date.now()) {
+/** One hook of that set ran, which it does only once it is trusted. */
+export function noteHookFired(environment, host, now = Date.now(), set = "guidance") {
+    // Settled or not, a file left behind would send every command to Node for good.
+    if (set === "push-check")
+        forget(pushCheckAwaitingFile(environment, host));
     const marks = read(environment);
-    const mark = marks[host];
+    const mark = marks[key(host, set)];
     // Nothing to settle, or already settled: no write on the session's path.
     if (mark?.firedAt !== undefined && mark.firedAt >= (mark.writtenAt ?? 0))
         return;
-    write(environment, { ...marks, [host]: { ...mark, firedAt: now } });
+    write(environment, { ...marks, [key(host, set)]: { ...mark, firedAt: now } });
 }
-/** True while the hooks last written for this host have never run in it. */
-export function hooksAwaitingTrust(environment, host) {
-    const mark = read(environment)[host];
+function awaiting(mark) {
     if (mark?.writtenAt === undefined)
         return false;
     return mark.firedAt === undefined || mark.firedAt < mark.writtenAt;
 }
+/** True while some set of the hooks last written for this host has never run in it. */
+export function hooksAwaitingTrust(environment, host) {
+    const marks = read(environment);
+    return SETS.some((set) => awaiting(marks[key(host, set)]));
+}
+const WORDS = ["no", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine"];
+/** A small count the way a sentence says it. */
+export function countWord(count) {
+    return WORDS[count] ?? String(count);
+}
+/** How many of Balladeer's hooks this host was last given, over every set written. */
+export function hooksWritten(environment, host) {
+    const marks = read(environment);
+    return SETS.reduce((total, set) => {
+        const mark = marks[key(host, set)];
+        return mark?.writtenAt === undefined ? total : total + (mark.hooks ?? DEFAULT_COUNT[set]);
+    }, 0);
+}
 /** The host a session belongs to, from the name it gave when it said hello. */
 export function trustingHost(clientName) {
     return typeof clientName === "string" && clientName.toLowerCase().startsWith("codex")
         ? "codex"
         : undefined;
 }
-/** What the agent is asked to pass on, once, in the host where the approval happens. */
-export const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";
+/**
+ * What the agent is asked to pass on, once, in the host where the approval
+ * happens. It counts the hooks this command last wrote there, so a laptop given
+ * the push check is told to trust six and one without it four.
+ */
+export function hooksAwaitingTrustNotice(environment, host = "codex") {
+    const pushCheck = read(environment)[key(host, "push-check")]?.writtenAt !== undefined;
+    const count = hooksWritten(environment, host) || DEFAULT_COUNT.guidance;
+    return ("Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. " +
+        `Ask them to type /hooks in Codex and trust Balladeer's ${countWord(count)} hooks; until then Codex has Balladeer's tools without its session-start guidance, its updates, ` +
+        (pushCheck
+            ? "the note that reminds you to tell them what Balladeer did, or its check after a push."
+            : "or the note that reminds you to tell them what Balladeer did."));
+}

package/dist/judge-brief.d.ts

@@ -1,7 +1,8 @@
+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/v1`.
+ * The fixed instructions a judge works from, `judge-brief/v5`.
  *
  * 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
@@ -13,12 +14,41 @@ 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
+ * (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
+ * "find where its behavior lives yourself". A promise with a map is handed
+ * exactly what v3 handed it. v4 belongs to a candidate measured and not
+ * 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";
+/**
+ * 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.
+ *
+ * It comes last among the rules and only once the judge would otherwise
+ * answer could not tell, never before it has tried to prove or refute, so it
+ * cannot spend the time a proof needs. Measured against a same-day control of
+ * v1 on 30 September (docs/agentic-testing/evidence/20260930/setup-rule.md),
+ * it proved no fewer breaks. Could not tell stays could not tell; the only new
+ * thing in the answer is `nextStep`, the one step that would let the tests run.
  */
-export declare const JUDGE_BRIEF_REVISION = "judge-brief/v1";
-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.\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_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 type JudgeBriefInput = Readonly<{
     promise: PromiseDocument;
     map?: BehaviorMap;
+    /** Read only when there is no map. */
+    anchors?: Readonly<{
+        anchors: PromiseAnchors;
+        linkedTests: readonly Readonly<{
+            file: string;
+        }>[];
+        neighborhood: readonly string[];
+    }>;
     changedFiles: readonly string[];
     base: string;
     head: string;

package/dist/judge-brief.js

@@ -1,5 +1,5 @@
 /**
- * The fixed instructions a judge works from, `judge-brief/v1`.
+ * The fixed instructions a judge works from, `judge-brief/v5`.
  *
  * 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
@@ -11,8 +11,29 @@
  *
  * 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
+ * (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
+ * "find where its behavior lives yourself". A promise with a map is handed
+ * exactly what v3 handed it. v4 belongs to a candidate measured and not
+ * 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";
+/**
+ * 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.
+ *
+ * It comes last among the rules and only once the judge would otherwise
+ * answer could not tell, never before it has tried to prove or refute, so it
+ * cannot spend the time a proof needs. Measured against a same-day control of
+ * v1 on 30 September (docs/agentic-testing/evidence/20260930/setup-rule.md),
+ * it proved no fewer breaks. Could not tell stays could not tell; the only new
+ * thing in the answer is `nextStep`, the one step that would let the tests run.
  */
-export const JUDGE_BRIEF_REVISION = "judge-brief/v1";
+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.
 
 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.
@@ -27,6 +48,7 @@ Rules:
 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}
 
 Your final message must be exactly one JSON object and nothing after it:
 
@@ -59,6 +81,21 @@ export function judgePrompt(input) {
         sections.push("Where this promise's behavior lives, from its behavior map (built earlier; check it against the code):");
         sections.push(JSON.stringify(map, null, 2));
     }
+    else if (input.anchors !== undefined) {
+        const { anchors, linkedTests, neighborhood } = input.anchors;
+        sections.push("Where this promise's behavior lives, from its anchors (picked earlier from the promise's words and a list of this repository's files; check them against the code):");
+        sections.push(JSON.stringify({
+            entryPoints: anchors.entryPoints,
+            symbols: anchors.symbols,
+            resources: anchors.resources,
+            linkedTests,
+        }, null, 2));
+        if (neighborhood.length > 0) {
+            sections.push("Files one import step from those (what they import and what imports them), where to look next if the behavior reaches further:");
+            for (const file of neighborhood)
+                sections.push(`- ${file}`);
+        }
+    }
     else {
         sections.push("There is no behavior map for this promise; find where its behavior lives yourself.");
     }