balladeer 1.0.17 → 1.0.18

package/dist/guidance-hook.mjs

@@ -2152,7 +2152,7 @@ function relayHook(input, directory) {
 }
 
 // src/wire.ts
-var CLI_VERSION = "1.0.17";
+var CLI_VERSION = "1.0.18";
 var CLIENT_HEADER = "x-balladeer-client";
 var UPDATE_STATE_HEADER = "x-balladeer-update-state";
 var HOOK_HOST_HEADER = "x-balladeer-hook";
@@ -2403,6 +2403,9 @@ function parseGuidance(value, agent) {
   return value;
 }
 function guidanceEndpoint(agent) {
+  return agentEndpoint(agent, "/api/agent-guidance");
+}
+function agentEndpoint(agent, pathname) {
   const url = new URL(agent.mcpUrl);
   const expected = new URL(agent.controlPlane);
   if (url.origin !== expected.origin || url.protocol !== "https:" || url.pathname !== "/api/mcp" || url.username || url.password || url.hash || !UUID.test(agent.workspaceId) || !UUID.test(agent.repositoryId))
@@ -2415,7 +2418,7 @@ function guidanceEndpoint(agent) {
       throw new Error("invalid_guidance_scope");
     url.searchParams.set(key2, value);
   }
-  url.pathname = "/api/agent-guidance";
+  url.pathname = pathname;
   return url;
 }
 function readJson(path) {

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/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/v3`.
+ * 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,8 +14,17 @@ 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/v3";
+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.
@@ -31,6 +41,14 @@ export declare const JUDGE_BRIEF = "You are judging one change to this repositor
 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/v3`.
+ * 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,17 @@
  *
  * 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/v3";
+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.
@@ -72,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.");
     }

package/dist/promise-meaning.d.ts

@@ -1,4 +1,5 @@
 import { type BehaviorMapMeaning } from "./behavior-map-schema.js";
+import { type StoredAgent } from "./store.js";
 /**
  * One promise's agreed meaning, the way the map builder and the judge read it.
  *
@@ -115,6 +116,22 @@ export type PromiseReader = Readonly<{
  * is told what happened and what works meanwhile.
  */
 export declare function olderServerRefusal(text: string): string | undefined;
+/**
+ * The agent connection stored on this laptop for the repository a folder is
+ * in, or the reason there is none. Read locally; nothing is asked of the server.
+ */
+export declare function connectionAgent(input: Readonly<{
+    environment: NodeJS.ProcessEnv;
+    controlPlane: string;
+    cwd: string;
+    repository?: string;
+}>): {
+    ok: true;
+    agent: StoredAgent;
+} | {
+    ok: false;
+    reason: string;
+};
 /**
  * This repository's agent connection as a reader of promises, or the reason
  * there is none. Reading is all it does: `get_promise` and `list_promises`,

package/dist/promise-meaning.js

@@ -211,22 +211,31 @@ export function olderServerRefusal(text) {
         "the server is updated; until then, hand the promise over as a file with --from-file.");
 }
 /**
- * This repository's agent connection as a reader of promises, or the reason
- * there is none. Reading is all it does: `get_promise` and `list_promises`,
- * the same two reads an agent in this repository makes.
+ * The agent connection stored on this laptop for the repository a folder is
+ * in, or the reason there is none. Read locally; nothing is asked of the server.
  */
-export function connectionReader(input) {
-    let agent;
+export function connectionAgent(input) {
     try {
         const credentials = readCredentials(input.environment);
         const selection = selectAgent(credentials.agents, input.controlPlane, input.repository, repositoryHints(input.cwd));
         if (selection.kind === "refused")
             return { ok: false, reason: selection.reason };
-        agent = selection.agent;
+        return { ok: true, agent: selection.agent };
     }
     catch (error) {
         return { ok: false, reason: error instanceof Error ? error.message : String(error) };
     }
+}
+/**
+ * This repository's agent connection as a reader of promises, or the reason
+ * there is none. Reading is all it does: `get_promise` and `list_promises`,
+ * the same two reads an agent in this repository makes.
+ */
+export function connectionReader(input) {
+    const found = connectionAgent(input);
+    if (!found.ok)
+        return found;
+    const agent = found.agent;
     const refusal = (kind) => kind === "unreachable"
         ? `Balladeer could not be reached at ${input.controlPlane}`
         : kind === "unauthorized"

package/dist/risk/git.d.ts

@@ -15,11 +15,13 @@ export declare function tryGit(root: string, args: readonly string[]): string |
 export declare function resolveCommit(root: string, ref: string): string;
 /** The merge base `git diff base...head` compares against. */
 export declare function mergeBase(root: string, base: string, head: string): string;
+/** One blob in a tree: its path, its size, and the object id its content hashes to. */
 export type TreeEntry = Readonly<{
     path: string;
     size: number;
+    sha: string;
 }>;
-/** Every blob in a commit's tree, with its size. */
+/** Every blob in a commit's tree, with its size and object id. */
 export declare function listTree(root: string, rev: string): TreeEntry[];
 /**
  * The contents of many files at one commit, in one `git cat-file --batch`.

package/dist/risk/git.js

@@ -59,7 +59,7 @@ export function mergeBase(root, base, head) {
         throw new GitReadError(["merge-base", base, head], "no merge base between the two commits");
     return sha;
 }
-/** Every blob in a commit's tree, with its size. */
+/** Every blob in a commit's tree, with its size and object id. */
 export function listTree(root, rev) {
     const out = runGit(root, ["ls-tree", "-r", "-z", "--long", rev]).toString("utf8");
     const entries = [];
@@ -69,10 +69,10 @@ export function listTree(root, rev) {
         const tab = record.indexOf("\t");
         if (tab < 0)
             continue;
-        const [, type, , size] = record.slice(0, tab).split(/\s+/);
+        const [, type, sha, size] = record.slice(0, tab).split(/\s+/);
         if (type !== "blob")
             continue;
-        entries.push({ path: record.slice(tab + 1), size: Number(size) || 0 });
+        entries.push({ path: record.slice(tab + 1), size: Number(size) || 0, sha: sha ?? "" });
     }
     return entries;
 }

package/dist/risk/graph-cache.d.ts

@@ -0,0 +1,83 @@
+import type { SymbolKind } from "./contract.js";
+import { type ImportGraph } from "./import-graph.js";
+/**
+ * The repository graph of one commit, built from a cache on this laptop.
+ *
+ * What a file imports and which names it declares depend only on its own
+ * content, so they are kept per blob, and a commit parses only the blobs this
+ * laptop has not read before. How those imports resolve depends on the whole
+ * tree, so that is worked out again on every build, from the cached
+ * specifiers; it is cheap. The cache sits in Balladeer's config home, one file
+ * per repository (all worktrees of a repository share it), and holds file
+ * paths' blob ids, import specifiers and declared names. It is never committed
+ * and never sent anywhere.
+ */
+/** Bumped whenever what is read out of a blob changes, so old entries are read again. */
+export declare const GRAPH_CACHE_VERSION = 1;
+export declare const GRAPH_CACHE_DIRECTORY = "graph-cache";
+export type ExportedName = Readonly<{
+    name: string;
+    kind: SymbolKind;
+}>;
+type BlobSymbols = {
+    /** Which reader found them: `typescript@<version>` or `regex`. */
+    reader: string;
+    /** Top-level names the file exports, in the order it declares them. */
+    exported: ExportedName[];
+    /** Every name the file declares or exports, which is what an anchor's symbol is checked against. */
+    names: string[];
+};
+export type GraphBuildStats = Readonly<{
+    /** Source files in the graph. */
+    files: number;
+    /** Blobs read and parsed in this build. */
+    parsed: number;
+    /** Blobs whose reading came from the cache. */
+    reused: number;
+    ms: number;
+}>;
+export type RepositoryGraph = Readonly<{
+    root: string;
+    /** The commit, as a full sha. */
+    sha: string;
+    graph: ImportGraph;
+    /** Every path in the commit's tree, of any kind. */
+    tree: ReadonlySet<string>;
+    /** The names a source file exports, read once per blob. Undefined for a file not in the graph. */
+    exportedNames(file: string): readonly ExportedName[] | undefined;
+    /** Every name a source file declares or exports. Undefined for a file not in the graph. */
+    declaredNames(file: string): ReadonlySet<string> | undefined;
+    /** Read the names of many files at once, so a whole index costs one git read. */
+    prepareNames(files: readonly string[]): void;
+    /** Keep what this build read for the next one. Never throws. */
+    save(): void;
+    stats(): GraphBuildStats;
+}>;
+/**
+ * Names a script file makes available beyond its declarations: `default` for
+ * `export default`, each name or alias in `export { a, b as c }`, a namespace
+ * re-export's name, and the names bound by `export const { a, b } = ...` or
+ * `export const [a, b] = ...`.
+ */
+export declare function exportClauseNames(text: string): string[];
+/**
+ * Whether a graph file belongs in the anchoring index: product source, so not
+ * a test, and (from `anchor-brief/v3`) not a story or a mock.
+ */
+export declare function isIndexSource(file: string): boolean;
+/** The names a file declares and exports, read the way the anchoring index reads them. */
+export declare function readSymbols(file: string, text: string, root: string): Omit<BlobSymbols, "reader">;
+/** The cache file of the repository a checkout belongs to, shared by all its worktrees. */
+export declare function graphCachePath(root: string, environment: NodeJS.ProcessEnv): string;
+/**
+ * The graph of `rev`, from this laptop's cache where it can be. With
+ * `cache: false` nothing is read from or written to disk, which is the plain
+ * build every time.
+ */
+export declare function buildRepositoryGraph(input: Readonly<{
+    root: string;
+    rev: string;
+    environment?: NodeJS.ProcessEnv;
+    cache?: boolean;
+}>): RepositoryGraph;
+export {};