balladeer 1.0.16 → 1.0.18

package/dist/cli.js

@@ -9,6 +9,7 @@ import { runDiscover } from "./commands/discover.js";
 import { runExplain } from "./commands/explain.js";
 import { parseRole, runInvite } from "./commands/invite.js";
 import { runGuidance } from "./commands/guidance.js";
+import { ANCHOR_USAGE } from "./commands/anchor-usage.js";
 import { JUDGE_USAGE, judgeCommand } from "./commands/judge.js";
 import { MAP_USAGE, mapCommand } from "./commands/map.js";
 import { OFFERS_USAGE, offersCommand } from "./commands/offers.js";
@@ -25,7 +26,7 @@ import { runWhoami } from "./commands/whoami.js";
 import { runInstall } from "./install.js";
 import { openInBrowser } from "./open-browser.js";
 import { PUBLISHED_SPECIFIER } from "./release.js";
-import { CODEX_HOOK_APPROVAL, installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
+import { codexHookApproval, installUserScope, pushCheckSetupLine, pushCheckState, runningFromCheckout, userHome, } from "./user-scope.js";
 import { updateNotice } from "./currency.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "./remove-earlier.js";
 import { recordSelfUpdateState, SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
@@ -160,6 +161,7 @@ const USAGE = `balladeer ${CLI_VERSION}
       local file and contacts nothing.
 
 ${MAP_USAGE}
+${ANCHOR_USAGE}
 ${JUDGE_USAGE}
 ${OFFERS_USAGE}
   ${CLI_INVOCATION} risk [--base <ref>] [--head <ref>] [--json] [--maps <dir>]
@@ -275,8 +277,9 @@ export function parseArguments(argv) {
             const requested = value("--event", inline);
             if (requested !== "SessionStart" &&
                 requested !== "UserPromptSubmit" &&
-                requested !== "SubagentStart")
-                throw new StoreError("usage", "--event needs SessionStart, UserPromptSubmit or SubagentStart.");
+                requested !== "SubagentStart" &&
+                requested !== "PostToolUse")
+                throw new StoreError("usage", "--event needs SessionStart, UserPromptSubmit, SubagentStart or PostToolUse.");
             event = requested;
         }
         else if (name === "--json")
@@ -449,7 +452,7 @@ export async function main(argv) {
     // `map`, `judge` and `offers` read their own flags: `--hook`, `--repo` and
     // `--install-hook` mean something different there, and `judge --hook` runs
     // inside a coding host where a stderr nag would reach the agent.
-    if (argv[0] === "map" || argv[0] === "judge" || argv[0] === "offers") {
+    if (argv[0] === "map" || argv[0] === "judge" || argv[0] === "offers" || argv[0] === "anchor") {
         const io = {
             cwd: process.cwd(),
             environment: process.env,
@@ -458,6 +461,8 @@ export async function main(argv) {
         };
         if (argv[0] === "offers")
             return offersCommand(argv.slice(1), io);
+        if (argv[0] === "anchor")
+            return (await import("./commands/anchor.js")).anchorCommand(argv.slice(1), io);
         return argv[0] === "map" ? mapCommand(argv.slice(1), io) : judgeCommand(argv.slice(1), io);
     }
     let parsed;
@@ -497,12 +502,14 @@ function commandVersion(name) {
 function installEverything(options) {
     const published = !runningFromCheckout();
     let writes;
+    let pushCheck = "unavailable";
     const register = (installed) => {
         writes = installUserScope({
             environment: process.env,
             published,
             ...(installed === undefined ? {} : { installed }),
         });
+        pushCheck = pushCheckState(process.env, published, installed);
         return writes;
     };
     const code = runInstall({
@@ -510,12 +517,15 @@ function installEverything(options) {
         json: options.json,
         write: options.write,
         allowPartial: options.allowPartial,
-        onInstalled: (result) => ({ userScope: register(result.command) }),
+        onInstalled: (result) => {
+            const userScope = register(result.command);
+            return { userScope, pushCheck };
+        },
     });
     if (writes === undefined) {
         const fallback = register();
         if (options.json)
-            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback })}\n`);
+            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback, pushCheck })}\n`);
     }
     for (const w of writes ?? [])
         if (!options.json)
@@ -531,7 +541,7 @@ function installEverything(options) {
         if (options.json)
             options.write(`${JSON.stringify({ step: "codex_hooks", approval: codex.status === "written" ? "required" : "check", command: "/hooks" })}\n`);
         else
-            options.write(`${CODEX_HOOK_APPROVAL}\n`);
+            options.write(`${codexHookApproval(pushCheck !== "unavailable")}\n`);
     }
     // With the user-scope form in place, the older per-repository form in this
     // checkout only makes the session hear the guidance twice. Out it goes, with
@@ -554,6 +564,13 @@ function installEverything(options) {
         options.write("Balladeer now runs in every Claude Code" +
             ((writes ?? []).some((w) => w.host === "codex") ? " and Codex" : "") +
             " session on this machine. In a folder of a connected repository it works as before; anywhere else it stays quiet, and `balladeer status` there says why.\n");
+    // The push check rides on the same hooks file, so it is on wherever that
+    // file was written: said once per run, with how to turn it off. Under
+    // --json it is the `pushCheck` field of the install step, so that step stays
+    // one object.
+    const hooksFile = (writes ?? []).find((w) => w.path.endsWith("settings.json"));
+    if (!options.json && hooksFile !== undefined && hooksFile.status !== "refused")
+        options.write(`${pushCheckSetupLine(pushCheck)}\n`);
     const outcome = (writes ?? []).some((w) => w.status === "refused") ? 4 : code;
     // Started by the session hook's background update: leave how it ended where
     // the next hook fire will find it and tell the server.

package/dist/commands/anchor-usage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `balladeer anchor`'s usage, apart from the command itself so the help text
+ * costs the command's start nothing: the anchoring machinery is loaded only
+ * when something anchors.
+ */
+export declare const ANCHOR_USAGE = "  npx -y balladeer@latest anchor [<promise id> | --all] [--json] [--repo <root>]\n                   [--client auto|claude|codex]\n      Anchor this repository's agreed promises to the code that realizes them,\n      at HEAD: the files and names where each one's behavior lives, picked by\n      one small call on your own Claude Code or Codex login from a list of\n      this repository's files, and shared through Balladeer with your team.\n      Only paths and names are sent, never code. A promise with a behavior map\n      for its current meaning is anchored from the map, with no call. The push\n      check does this by itself; this does it now. With no argument or --all,\n      every promise without current anchors, or whose anchored code is gone;\n      with a promise id, that one again. At most 20 calls a day on this\n      laptop (set BALLADEER_ANCHOR_DAILY_BUDGET to change it).\n";

package/dist/commands/anchor-usage.js

@@ -0,0 +1,19 @@
+import { CLI_INVOCATION } from "../wire.js";
+/**
+ * `balladeer anchor`'s usage, apart from the command itself so the help text
+ * costs the command's start nothing: the anchoring machinery is loaded only
+ * when something anchors.
+ */
+export const ANCHOR_USAGE = `  ${CLI_INVOCATION} anchor [<promise id> | --all] [--json] [--repo <root>]
+                   [--client auto|claude|codex]
+      Anchor this repository's agreed promises to the code that realizes them,
+      at HEAD: the files and names where each one's behavior lives, picked by
+      one small call on your own Claude Code or Codex login from a list of
+      this repository's files, and shared through Balladeer with your team.
+      Only paths and names are sent, never code. A promise with a behavior map
+      for its current meaning is anchored from the map, with no call. The push
+      check does this by itself; this does it now. With no argument or --all,
+      every promise without current anchors, or whose anchored code is gone;
+      with a promise id, that one again. At most 20 calls a day on this
+      laptop (set BALLADEER_ANCHOR_DAILY_BUDGET to change it).
+`;

package/dist/commands/anchor.d.ts

@@ -0,0 +1,127 @@
+import { type AnchorBudget } from "../anchor-budget.js";
+import { anchoringLines, type AnchorRun } from "../anchoring.js";
+import { connectionAnchorsClient, type AnchoredPromise, type AnchorsClient } from "../anchors-client.js";
+import { type PromiseAnchors } from "../anchors-schema.js";
+import { type BehaviorMap, type BehaviorMapMeaning } from "../behavior-map-schema.js";
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type PromiseReader } from "../promise-meaning.js";
+import { type RepositoryGraph } from "../risk/graph-cache.js";
+import { ANCHOR_USAGE } from "./anchor-usage.js";
+import { type StoredMap } from "./map.js";
+export { anchoringLines, connectionAnchorsClient };
+/**
+ * `balladeer anchor`, and the anchoring step the push check runs before it
+ * selects what to judge.
+ *
+ * Both read the repository's agreed promises and their current anchors from
+ * Balladeer, build the repository graph at the commit from this laptop's
+ * cache, and bring every promise's anchors current within today's budget (see
+ * `../anchoring.ts`). A behavior map for a promise's current meaning still
+ * wins over its anchors when promises are selected.
+ */
+export type AnchorStage = Readonly<{
+    available: true;
+    promises: readonly AnchoredPromise[];
+    /** Maps in this checkout for their promise's current meaning, by promise id. */
+    currentMaps: ReadonlyMap<string, BehaviorMap>;
+    repository?: RepositoryGraph;
+    run?: AnchorRun;
+}> | Readonly<{
+    available: false;
+    /** Why the anchors could not be read, for a line when one is said. */
+    reason: string;
+    /**
+     * Anchors do not apply here at all: this laptop has no connection for
+     * the repository, or its server has no anchors route yet. Neither is
+     * worth a line of its own; everything works from maps, as before.
+     */
+    unsupported: boolean;
+}>;
+export type AnchorStageInput = Readonly<{
+    root: string;
+    head: string;
+    environment: NodeJS.ProcessEnv;
+    maps: readonly StoredMap[];
+    client: AnchorsClient | undefined;
+    /** Why there is no client, when there is none. */
+    clientMissing?: string;
+    reader: PromiseReader | undefined;
+    login: () => Promise<LoginCheck | undefined>;
+    now: () => Date;
+    deadline?: number;
+    signal?: AbortSignal;
+    concurrency?: number;
+    scratch?: string;
+    force?: ReadonlySet<string>;
+    only?: ReadonlySet<string>;
+    budget?: AnchorBudget;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** Replaces the graph build, for tests. */
+    graph?: (root: string, head: string) => RepositoryGraph;
+}>;
+/** Every parsed map whose meaning is the promise's current one, by promise id. */
+export declare function currentMapsFor(maps: readonly StoredMap[], promises: readonly AnchoredPromise[]): Map<string, BehaviorMap>;
+/** Read the anchors, and bring them current. Never throws for anything the server or a call does. */
+export declare function anchorStage(input: AnchorStageInput): Promise<AnchorStage>;
+/**
+ * Anchors in the shape the risk scorer reads, so a promise selected by its
+ * anchors is ordered by the same rule as a mapped one: its entry points and
+ * symbols as core, its linked tests, its resources, and the meaning's excerpt
+ * when it was read, which is what the scorer compares a change's words with.
+ */
+export declare function anchorsAsMap(anchors: PromiseAnchors, meaning?: BehaviorMapMeaning): BehaviorMap;
+/**
+ * What a judge is handed where a promise has anchors and no map: the anchors
+ * still in the code, the linked tests the graph gives at head, and the files
+ * one import step from the anchor files.
+ */
+export type JudgeAnchors = Readonly<{
+    anchors: PromiseAnchors;
+    linkedTests: readonly {
+        file: string;
+    }[];
+    neighborhood: readonly string[];
+}>;
+/** A promise's anchors as the judge receives them, read off the graph at the judged commit. */
+export declare function judgeAnchors(anchors: PromiseAnchors, repository: RepositoryGraph): JudgeAnchors;
+/**
+ * The promises a change edits an anchor file of (an entry point's or a
+ * symbol's file), from each promise's anchor files. Nothing further: no file
+ * that merely imports or is imported by an anchor file.
+ */
+export declare function anchoredByChange(anchorFilesOf: ReadonlyMap<string, readonly string[]>, changed: readonly string[]): string[];
+export type AnchorArguments = Readonly<{
+    promiseId?: string;
+    all: boolean;
+    json: boolean;
+    repo?: string;
+    client: HeadlessClient | "auto";
+    repository?: string;
+    controlPlane: string;
+}>;
+export { ANCHOR_USAGE };
+export declare function parseAnchorArguments(argv: readonly string[]): AnchorArguments;
+export type AnchorDependencies = Readonly<{
+    client?: AnchorsClient;
+    reader?: PromiseReader;
+    resolveLogin?: (requested: HeadlessClient | "auto") => Promise<LoginCheck | undefined>;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    now?: () => Date;
+    graph?: (root: string, head: string) => RepositoryGraph;
+    scratch?: string;
+}>;
+/** `balladeer anchor`, from arguments already parsed. */
+export declare function runAnchor(options: Readonly<{
+    args: AnchorArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+    deps?: AnchorDependencies;
+}>): Promise<number>;
+export declare function anchorCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;

package/dist/commands/anchor.js

@@ -0,0 +1,303 @@
+import { join, resolve } from "node:path";
+import { anchorBudget } from "../anchor-budget.js";
+import { anchoringLines, bringAnchorsCurrent, linkedTestsFor, neighborhood, } from "../anchoring.js";
+import { connectionAnchorsClient, } from "../anchors-client.js";
+import { anchorFiles } from "../anchors-schema.js";
+import { BEHAVIOR_MAP_DIRECTORY, BEHAVIOR_MAP_SCHEMA_VERSION, } from "../behavior-map-schema.js";
+import { repositoryRoot } from "../git.js";
+import { resolveClient, } from "../headless-agent.js";
+import { connectionReader } from "../promise-meaning.js";
+import { buildRepositoryGraph } from "../risk/graph-cache.js";
+import { resolveCommit } from "../scratch-worktree.js";
+import { normalizeControlPlane, StoreError } from "../store.js";
+import { DEFAULT_CONTROL_PLANE } from "../wire.js";
+import { ANCHOR_USAGE } from "./anchor-usage.js";
+import { readBehaviorMaps } from "./map.js";
+// What the push check loads from here once a push is its to judge.
+export { anchoringLines, connectionAnchorsClient };
+/** Every parsed map whose meaning is the promise's current one, by promise id. */
+export function currentMapsFor(maps, promises) {
+    const digests = new Map(promises.map((promise) => [promise.promiseId, promise.semanticDigest]));
+    const current = new Map();
+    for (const entry of maps)
+        if (entry.map !== undefined && digests.get(entry.promiseId) === entry.map.semanticDigest)
+            current.set(entry.promiseId, entry.map);
+    return current;
+}
+/** Read the anchors, and bring them current. Never throws for anything the server or a call does. */
+export async function anchorStage(input) {
+    if (input.client === undefined)
+        return {
+            available: false,
+            reason: input.clientMissing ?? "there is no Balladeer connection for this repository",
+            unsupported: true,
+        };
+    const listed = await input.client.list();
+    if (!listed.ok)
+        return { available: false, reason: listed.reason, unsupported: listed.unsupported === true };
+    const promises = listed.promises;
+    const currentMaps = currentMapsFor(input.maps, promises);
+    if (promises.length === 0)
+        return { available: true, promises, currentMaps };
+    let repository;
+    try {
+        repository = (input.graph ??
+            ((root, head) => buildRepositoryGraph({ root, rev: head, environment: input.environment })))(input.root, input.head);
+    }
+    catch (error) {
+        return {
+            available: false,
+            reason: `the repository could not be read at ${input.head.slice(0, 12)}: ${error.message}`,
+            unsupported: false,
+        };
+    }
+    const run = await bringAnchorsCurrent({
+        promises,
+        currentMaps,
+        repository,
+        client: input.client,
+        reader: input.reader,
+        login: input.login,
+        budget: input.budget ?? anchorBudget(input.environment, input.now),
+        environment: input.environment,
+        now: input.now,
+        repositoryKey: repository.root,
+        ...(input.force === undefined ? {} : { force: input.force }),
+        ...(input.only === undefined ? {} : { only: input.only }),
+        ...(input.deadline === undefined ? {} : { deadline: input.deadline }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.concurrency === undefined ? {} : { concurrency: input.concurrency }),
+        ...(input.scratch === undefined ? {} : { scratch: input.scratch }),
+        ...(input.runAgent === undefined ? {} : { runAgent: input.runAgent }),
+    });
+    repository.save();
+    return { available: true, promises, currentMaps, repository, run };
+}
+/**
+ * Anchors in the shape the risk scorer reads, so a promise selected by its
+ * anchors is ordered by the same rule as a mapped one: its entry points and
+ * symbols as core, its linked tests, its resources, and the meaning's excerpt
+ * when it was read, which is what the scorer compares a change's words with.
+ */
+export function anchorsAsMap(anchors, meaning) {
+    return {
+        schemaVersion: BEHAVIOR_MAP_SCHEMA_VERSION,
+        promiseId: anchors.promiseId,
+        semanticDigest: anchors.semanticDigest,
+        mappedAt: {
+            sha: anchors.anchoredAt.sha,
+            at: anchors.anchoredAt.at,
+            client: anchors.anchoredAt.client ?? "claude",
+            model: anchors.anchoredAt.model ?? "",
+        },
+        entryPoints: anchors.entryPoints.map((entry) => ({ ...entry, note: "" })),
+        symbols: anchors.symbols.map((symbol) => ({ ...symbol, role: "core" })),
+        resources: [...anchors.resources],
+        linkedTests: anchors.linkedTests.map((test) => ({ file: test.file, name: "", cases: [] })),
+        sinks: [],
+        confidence: 0,
+        notes: "",
+        ...(meaning === undefined ? {} : { meaning }),
+    };
+}
+/** A promise's anchors as the judge receives them, read off the graph at the judged commit. */
+export function judgeAnchors(anchors, repository) {
+    const files = anchorFiles(anchors);
+    return {
+        anchors,
+        linkedTests: linkedTestsFor(repository.graph, files),
+        neighborhood: neighborhood(repository.graph, files),
+    };
+}
+/**
+ * The promises a change edits an anchor file of (an entry point's or a
+ * symbol's file), from each promise's anchor files. Nothing further: no file
+ * that merely imports or is imported by an anchor file.
+ */
+export function anchoredByChange(anchorFilesOf, changed) {
+    const edited = new Set(changed);
+    const selected = [];
+    for (const [promiseId, files] of anchorFilesOf)
+        if (files.some((file) => edited.has(file)))
+            selected.push(promiseId);
+    return selected.sort();
+}
+export { ANCHOR_USAGE };
+export function parseAnchorArguments(argv) {
+    const args = [...argv];
+    const positional = [];
+    let all = false;
+    let json = false;
+    let repo;
+    let repository;
+    let controlPlane;
+    let client = "auto";
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (next === undefined || next === "")
+            throw new StoreError("usage", `${flag} needs a value.`);
+        return next;
+    };
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        const [name, ...rest] = arg.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--all")
+            all = true;
+        else if (name === "--json")
+            json = true;
+        else if (name === "--repo")
+            repo = value(name, inline);
+        else if (name === "--repository")
+            repository = value(name, inline);
+        else if (name === "--control-plane")
+            controlPlane = value(name, inline);
+        else if (name === "--client") {
+            const requested = value(name, inline);
+            if (requested !== "auto" && requested !== "claude" && requested !== "codex")
+                throw new StoreError("usage", "--client needs auto, claude or codex.");
+            client = requested;
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${arg} for anchor.`);
+    }
+    if (positional.length > 1)
+        throw new StoreError("usage", "anchor takes at most one promise id.");
+    const promiseId = positional[0];
+    if (promiseId !== undefined && all)
+        throw new StoreError("usage", "Name one promise or pass --all, not both.");
+    if (promiseId !== undefined && !/^prom_[a-z0-9]{8,64}$/.test(promiseId))
+        throw new StoreError("usage", `"${promiseId}" is not a promise id.`);
+    const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
+    return {
+        ...(promiseId === undefined ? {} : { promiseId }),
+        all: promiseId === undefined,
+        json,
+        ...(repo === undefined ? {} : { repo }),
+        client,
+        ...(repository === undefined ? {} : { repository }),
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+function count(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function describeOutcome(outcome, anchors) {
+    const name = `${outcome.title} (${outcome.promiseId})`;
+    const shape = anchors === undefined
+        ? ""
+        : `: ${count(anchors.entryPoints.length, "entry point", "entry points")}, ${count(anchors.symbols.length, "symbol", "symbols")}, ${count(anchors.linkedTests.length, "linked test", "linked tests")}`;
+    switch (outcome.status) {
+        case "current":
+            return `already anchored: ${name}${shape}`;
+        case "anchored":
+            return `anchored${outcome.again === true ? " again" : ""}: ${name}${shape}`;
+        case "seeded":
+            return `anchored from its behavior map: ${name}${shape}`;
+        case "stale":
+            return `not anchored again: ${name}; some of its anchored code is gone, and what is left is used${outcome.reason ? ` (${outcome.reason})` : ""}`;
+        default:
+            return `not anchored: ${name}: ${outcome.reason ?? outcome.status}`;
+    }
+}
+/** `balladeer anchor`, from arguments already parsed. */
+export async function runAnchor(options) {
+    const { args } = options;
+    const deps = options.deps ?? {};
+    const now = deps.now ?? (() => new Date());
+    const fail = (reason, message) => {
+        if (args.json) {
+            const step = { step: "error", reason, message, changed: false, exitCode: 4 };
+            options.write(`${JSON.stringify(step)}\n`);
+        }
+        else
+            options.error(`${message}\n`);
+        return 4;
+    };
+    const root = args.repo !== undefined ? resolve(options.cwd, args.repo) : await repositoryRoot(options.cwd);
+    if (root === undefined)
+        return fail("not_a_repository", "This is not a git repository, so there is nothing to anchor.");
+    const head = await resolveCommit(root, "HEAD");
+    if (head === undefined)
+        return fail("no_head", "This repository has no commit yet, so there is nothing to anchor.");
+    const connection = {
+        environment: options.environment,
+        controlPlane: args.controlPlane,
+        cwd: root,
+        ...(args.repository === undefined ? {} : { repository: args.repository }),
+    };
+    let client = deps.client;
+    if (client === undefined) {
+        const found = connectionAnchorsClient(connection);
+        if (!found.ok)
+            return fail("no_connection", `There is no Balladeer connection for this repository on this laptop, so nothing was anchored: ${found.reason}`);
+        client = found.client;
+    }
+    let reader = deps.reader;
+    if (reader === undefined) {
+        const found = connectionReader(connection);
+        if (found.ok)
+            reader = found.reader;
+    }
+    let login;
+    const stage = await anchorStage({
+        root,
+        head,
+        environment: options.environment,
+        maps: readBehaviorMaps(join(root, BEHAVIOR_MAP_DIRECTORY)),
+        client,
+        reader,
+        login: () => (login ??= (deps.resolveLogin ??
+            ((requested) => resolveClient(requested, { env: options.environment, cwd: root })))(args.client)),
+        now,
+        ...(args.promiseId === undefined
+            ? {}
+            : { force: new Set([args.promiseId]), only: new Set([args.promiseId]) }),
+        ...(deps.runAgent === undefined ? {} : { runAgent: deps.runAgent }),
+        ...(deps.graph === undefined ? {} : { graph: deps.graph }),
+        ...(deps.scratch === undefined ? {} : { scratch: deps.scratch }),
+    });
+    if (!stage.available)
+        return fail("anchors_unavailable", `Nothing was anchored: ${stage.reason}.`);
+    if (args.promiseId !== undefined && !stage.promises.some((p) => p.promiseId === args.promiseId))
+        return fail("not_agreed_here", `${args.promiseId} is not an agreed promise of this repository, so it was not anchored.`);
+    const outcomes = (stage.run?.outcomes ?? []).filter((outcome) => args.promiseId === undefined || outcome.promiseId === args.promiseId);
+    const anchors = stage.run?.anchors ?? new Map();
+    if (args.json) {
+        for (const outcome of outcomes)
+            options.write(`${JSON.stringify({
+                step: "anchor",
+                promiseId: outcome.promiseId,
+                status: outcome.status,
+                ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+                ...(outcome.recorded === undefined ? {} : { recorded: outcome.recorded }),
+                ...(anchors.has(outcome.promiseId) ? { anchors: anchors.get(outcome.promiseId) } : {}),
+            })}\n`);
+    }
+    else {
+        if (stage.promises.length === 0)
+            options.write("This repository has no agreed promise yet, so there is nothing to anchor.\n");
+        for (const outcome of outcomes)
+            options.write(`${describeOutcome(outcome, anchors.get(outcome.promiseId))}\n`);
+        if (stage.run !== undefined)
+            for (const line of anchoringLines(stage.run, { push: false }))
+                options.write(`${line}\n`);
+    }
+    const unanchored = outcomes.filter((outcome) => !["current", "anchored", "seeded"].includes(outcome.status));
+    return unanchored.length > 0 ? 1 : 0;
+}
+export async function anchorCommand(argv, io) {
+    let args;
+    try {
+        args = parseAnchorArguments(argv);
+    }
+    catch (error) {
+        io.error(`${error instanceof Error ? error.message : String(error)}\n\n${ANCHOR_USAGE}`);
+        return 4;
+    }
+    return runAnchor({ args, ...io });
+}

package/dist/commands/guidance.d.ts

@@ -5,7 +5,8 @@ export type GuidanceOptions = Readonly<{
     controlPlane: string;
     repositoryId?: string;
     hook: "codex" | "claude";
-    event?: GuidanceEvent;
+    /** PostToolUse is the relay note, not guidance: see `runRelayNote`. */
+    event?: GuidanceEvent | "PostToolUse";
     runtimeGeneration?: string;
     environment: NodeJS.ProcessEnv;
     cwd: string;

package/dist/commands/guidance.js

@@ -1,3 +1,4 @@
+import { relayHook } from "../relay.js";
 import { validateProjectGuidanceScope } from "../guidance-install.js";
 import { GUIDANCE_UNAVAILABLE, loadGuidance, recordGuidanceContext, } from "../guidance.js";
 import { readCredentials } from "../store.js";
@@ -60,8 +61,62 @@ function eventFrom(input) {
 function identifier(input) {
     return typeof input === "string" && input.length > 0 && input.length <= 256 ? input : undefined;
 }
+/**
+ * After a Balladeer tool acts, a note the agent reads before it replies: tell
+ * the person what Balladeer did, in your own words (promise
+ * prom_45ef4e3d9e5545a9a411; plans/promise-relations/plan.md, step 1). Codex
+ * relayed every detail in 10 of 10 lab sessions with it and 6 of 10 without.
+ * Local only: no connection, no network, nothing stored. A tool result can be
+ * large, so the input bound is wider than guidance's; anything unreadable,
+ * oversized or late prints nothing, never the guidance-unavailable notice.
+ */
+async function runRelayNote(options) {
+    const input = await new Promise((resolve) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.stdin.removeListener("data", data);
+            resolve(value);
+        };
+        const data = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytes += buffer.length;
+            if (bytes > 1_048_576)
+                done(undefined);
+            else
+                chunks.push(buffer);
+        };
+        const timer = setTimeout(() => done(undefined), 1_000);
+        options.stdin.on("data", data);
+        options.stdin.once("end", () => {
+            try {
+                done(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                done(undefined);
+            }
+        });
+        options.stdin.once("error", () => done(undefined));
+    });
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return 0;
+    const record = input;
+    if (record.hook_event_name !== "PostToolUse")
+        return 0;
+    const out = relayHook(record);
+    if (out)
+        options.write(`${out}\n`);
+    return 0;
+}
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export async function runGuidance(options) {
+    if (options.event === "PostToolUse")
+        return runRelayNote(options);
     // A project hook names its repository and must match the checkout it sits
     // in. A user-scope hook names none: the folder's remotes decide.
     const projectScoped = options.repositoryId !== undefined;