balladeer 1.0.17 → 1.0.19

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.js

@@ -7,6 +7,7 @@ import { repositoryHints } from "../repository.js";
 import { newerVersionPublished } from "../currency.js";
 import { startSelfUpdateIfDue } from "../self-update.js";
 import { noteHookFired } from "../hook-trust.js";
+import { retireCheckoutRuntime } from "../guidance-runtime.js";
 /** A repository-specific setup step for explicit status and empty-catalog responses. */
 export function untrackedLine(remote) {
     const here = remote === "unknown/unknown" ? "This folder" : `This folder (${remote})`;
@@ -158,6 +159,18 @@ export async function runGuidance(options) {
         // trust are the ones this matters to.
         if (options.hook === "codex")
             noteHookFired(options.environment, "codex");
+        // This hook covers this checkout now, so the older per-repository hook
+        // here (releases before 1.0.8) only makes the session hear the guidance
+        // twice. Switch it off from the laptop side, once, before the fetch:
+        // nothing printed, no repository file touched, nobody asked to run a thing.
+        if (!projectScoped && event === "SessionStart")
+            retireCheckoutRuntime({
+                cwd: options.cwd,
+                host: options.hook,
+                repositoryId: agents[0].repositoryId,
+                controlPlane: agents[0].controlPlane,
+                environment: options.environment,
+            });
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,
@@ -165,14 +178,16 @@ export async function runGuidance(options) {
             hook: options.hook,
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
-        // Behind? Start the install in the background, once a day at most, and
-        // carry on serving this session from the copy that is here.
-        if (event === "SessionStart")
-            startSelfUpdateIfDue(newerVersionPublished(), {
-                environment: options.environment,
-                ...(options.startUpdate ? { run: options.startUpdate } : {}),
-                ...(options.now ? { now: options.now } : {}),
-            });
+        // Behind? Start the install in the background and carry on serving this
+        // session from the copy that is here. Any hook that loaded guidance may
+        // start it, not only a session start: sessions run for days, and a laptop
+        // whose sessions never restart would otherwise never update (Robert's own,
+        // 1 October 2026). The stamp keeps it to once a day per release.
+        startSelfUpdateIfDue(newerVersionPublished(), {
+            environment: options.environment,
+            ...(options.startUpdate ? { run: options.startUpdate } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
         const sessionId = identifier(record.session_id);
         const agentId = identifier(record.agent_id);
         recordGuidanceContext({