balladeer 1.0.13 → 1.0.15

package/dist/checkout-form.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Taking this product's own older, per-repository form out of a checkout once
+ * the user-scope form is in place, so one hook speaks per session.
+ *
+ * Releases before 1.0.8 registered Balladeer inside each repository: a hook in
+ * the checkout's `.claude/settings.json` (statusMessage "Balladeer current
+ * guidance (loader 1)"), a `balladeer` server in its `.mcp.json` that names the
+ * repository, and for Codex the fenced `# balladeer:guidance` and
+ * `# balladeer:mcp` blocks in `.codex/config.toml`. From 1.0.8 the same hook
+ * and server live at the host's user scope and run in every checkout. A laptop
+ * that moved from one to the other without cleaning up runs both: the session
+ * hears the guidance twice, and the server sees two hook forms fire for one
+ * person (found on Luke's laptop, 23 September 2026). Every removal here
+ * proves ownership from the entry itself; nothing else in those files moves.
+ * A file git tracks is edited without a copy (git holds the previous version)
+ * and the person is told to commit it; an untracked file is copied beside
+ * itself first.
+ */
+export type CheckoutFormItem = Readonly<{
+    path: string;
+    found: string;
+    tracked: boolean;
+    remove: () => string | undefined;
+}>;
+export type CheckoutFormReport = Readonly<{
+    removed: readonly {
+        path: string;
+        found: string;
+        copy?: string;
+        tracked: boolean;
+    }[];
+    failed: readonly {
+        path: string;
+        found: string;
+        reason: string;
+    }[];
+}>;
+/** The older per-repository form in the checkout that holds `cwd`, if any. */
+export declare function findCheckoutForm(input: {
+    cwd: string;
+    controlPlane: string;
+    now?: () => Date;
+}): CheckoutFormItem[];
+export declare function removeCheckoutForm(items: readonly CheckoutFormItem[]): CheckoutFormReport;
+export declare function describeCheckoutFormRemoval(report: CheckoutFormReport): string[];

package/dist/checkout-form.js

@@ -0,0 +1,223 @@
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isOurEntry, writeJsonAtomically } from "./mcp-config.js";
+const PROJECT_OWNER = "Balladeer current guidance (loader 1)";
+const CODEX_BLOCKS = [
+    ["# balladeer:guidance:start", "# balladeer:guidance:end"],
+    ["# balladeer:mcp:start", "# balladeer:mcp:end"],
+];
+function repositoryRoot(cwd) {
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2_000,
+        }).trim();
+        return root.length > 0 ? root : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function tracked(root, path) {
+    try {
+        execFileSync("git", ["ls-files", "--error-unmatch", "--", path], {
+            cwd: root,
+            stdio: "ignore",
+            timeout: 2_000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function regularFile(path) {
+    try {
+        return lstatSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function backup(path, now) {
+    // A file name, not a sentence: the person reads the copy's path back, and the
+    // stamp only has to sort. Same form as the earlier-client backups.
+    const stamp = now().toISOString().replaceAll(/[:.]/g, "-");
+    const copy = `${path}.before-balladeer-${stamp}`;
+    copyFileSync(path, copy);
+    return copy;
+}
+const isProjectHook = (hook) => {
+    if (hook === null || typeof hook !== "object")
+        return false;
+    const { command, statusMessage } = hook;
+    if (statusMessage === PROJECT_OWNER)
+        return true;
+    return (typeof command === "string" &&
+        /balladeer/i.test(command) &&
+        /--hook (?:claude|codex)\b/.test(command) &&
+        /--repository\b/.test(command));
+};
+function claudeHooks(root, now) {
+    const path = join(root, ".claude", "settings.json");
+    if (!regularFile(path))
+        return [];
+    const settings = readJson(path);
+    const hooks = settings?.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return [];
+    const events = Object.entries(hooks).filter(([, groups]) => Array.isArray(groups) &&
+        groups.some((group) => (group?.hooks ?? []).some((h) => isProjectHook(h))));
+    if (events.length === 0)
+        return [];
+    const isTracked = tracked(root, ".claude/settings.json");
+    return [
+        {
+            path,
+            tracked: isTracked,
+            found: `per-repository hook${events.length === 1 ? "" : "s"} (${events.map(([event]) => event).join(", ")})`,
+            remove: () => {
+                const copy = isTracked ? undefined : backup(path, now);
+                const current = readJson(path) ?? {};
+                const kept = {};
+                for (const [event, groups] of Object.entries((current.hooks ?? {}))) {
+                    if (!Array.isArray(groups)) {
+                        kept[event] = groups;
+                        continue;
+                    }
+                    const left = groups.filter((group) => !(group?.hooks ?? []).some((h) => isProjectHook(h)));
+                    if (left.length > 0)
+                        kept[event] = left;
+                }
+                writeJsonAtomically(path, JSON.stringify({ ...current, hooks: kept }, null, 2) + "\n");
+                return copy;
+            },
+        },
+    ];
+}
+function claudeServer(root, controlPlane, now) {
+    const path = join(root, ".mcp.json");
+    if (!regularFile(path))
+        return [];
+    const config = readJson(path);
+    const servers = config?.mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return [];
+    const entry = servers.balladeer;
+    if (entry === undefined || !isOurEntry(entry, controlPlane))
+        return [];
+    const args = entry.args;
+    if (!Array.isArray(args) || !args.includes("--repository"))
+        return [];
+    const isTracked = tracked(root, ".mcp.json");
+    return [
+        {
+            path,
+            tracked: isTracked,
+            found: "per-repository server entry",
+            remove: () => {
+                const copy = isTracked ? undefined : backup(path, now);
+                const current = readJson(path) ?? {};
+                const remaining = { ...(current.mcpServers ?? {}) };
+                delete remaining.balladeer;
+                writeJsonAtomically(path, JSON.stringify({ ...current, mcpServers: remaining }, null, 2) + "\n");
+                return copy;
+            },
+        },
+    ];
+}
+function codexBlocks(root, now) {
+    const path = join(root, ".codex", "config.toml");
+    if (!regularFile(path))
+        return [];
+    const text = readFileSync(path, "utf8");
+    const present = CODEX_BLOCKS.filter(([start, end]) => text.includes(`${start}\n`) && text.includes(end));
+    if (present.length === 0)
+        return [];
+    const isTracked = tracked(root, ".codex/config.toml");
+    return [
+        {
+            path,
+            tracked: isTracked,
+            found: `per-repository Codex block${present.length === 1 ? "" : "s"}`,
+            remove: () => {
+                const copy = isTracked ? undefined : backup(path, now);
+                let after = readFileSync(path, "utf8");
+                for (const [start, end] of CODEX_BLOCKS) {
+                    const from = after.indexOf(`${start}\n`);
+                    const to = after.indexOf(end, from);
+                    if (from < 0 || to < 0)
+                        continue;
+                    const cut = to + end.length + (after[to + end.length] === "\n" ? 1 : 0);
+                    after = after.slice(0, from) + after.slice(cut);
+                }
+                writeJsonAtomically(path, after.replace(/\n{3,}/g, "\n\n"));
+                return copy;
+            },
+        },
+    ];
+}
+/** The older per-repository form in the checkout that holds `cwd`, if any. */
+export function findCheckoutForm(input) {
+    const root = repositoryRoot(input.cwd);
+    if (root === undefined || !existsSync(root))
+        return [];
+    const now = input.now ?? (() => new Date());
+    return [
+        ...claudeHooks(root, now),
+        ...claudeServer(root, input.controlPlane, now),
+        ...codexBlocks(root, now),
+    ];
+}
+export function removeCheckoutForm(items) {
+    const removed = [];
+    const failed = [];
+    for (const item of items) {
+        try {
+            const copy = item.remove();
+            removed.push({
+                path: item.path,
+                found: item.found,
+                tracked: item.tracked,
+                ...(copy === undefined ? {} : { copy }),
+            });
+        }
+        catch (error) {
+            failed.push({
+                path: item.path,
+                found: item.found,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { removed, failed };
+}
+export function describeCheckoutFormRemoval(report) {
+    const lines = [];
+    for (const entry of report.removed)
+        lines.push(`Removed the older ${entry.found} from ${entry.path}` +
+            (entry.copy
+                ? ` (copy at ${entry.copy}).`
+                : entry.tracked
+                    ? "; git tracks this file, so commit the change."
+                    : "."));
+    for (const entry of report.failed)
+        lines.push(`Could not remove the older ${entry.found} from ${entry.path}: ${entry.reason}`);
+    if (report.removed.length > 0)
+        lines.push("The user-scope hook now speaks alone in this checkout; it was saying the same thing twice.");
+    return lines;
+}

package/dist/cli.js

@@ -21,9 +21,12 @@ import { runWhoami } from "./commands/whoami.js";
 import { runInstall } from "./install.js";
 import { openInBrowser } from "./open-browser.js";
 import { PUBLISHED_SPECIFIER } from "./release.js";
-import { installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
+import { CODEX_HOOK_APPROVAL, installUserScope, 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";
+import { hooksAwaitingTrust } from "./hook-trust.js";
+import { describeCheckoutFormRemoval, findCheckoutForm, removeCheckoutForm, } from "./checkout-form.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
 import { CLI_INVOCATION, CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
 const USAGE = `balladeer ${CLI_VERSION}
@@ -471,11 +474,46 @@ function installEverything(options) {
     for (const w of writes ?? [])
         if (!options.json)
             options.write(`${w.status === "refused" ? "Not changed" : w.status === "written" ? "Registered" : "Already current"}: ${w.path}${w.reason ? ` (${w.reason})` : ""}\n`);
+    // Codex runs a hook only once the person has trusted it, and trusts it by
+    // the hash of its definition, so a hook this command just wrote or changed
+    // is skipped until they do. Found 29 September 2026: Codex was the most
+    // common host at Didero and not one of its sessions had run the hook.
+    const codex = (writes ?? []).find((w) => w.host === "codex" && w.status !== "refused");
+    // Said whenever it is true, which is after any install that wrote or changed
+    // the hooks and until Codex has run one of them; silent once it has.
+    if (codex !== undefined && hooksAwaitingTrust(process.env, "codex")) {
+        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`);
+    }
+    // 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
+    // a copy beside any file git does not already keep.
+    if ((writes ?? []).length > 0 && !(writes ?? []).some((w) => w.status === "refused")) {
+        const checkoutForm = findCheckoutForm({
+            cwd: process.cwd(),
+            controlPlane: options.controlPlane,
+        });
+        if (checkoutForm.length > 0) {
+            const report = removeCheckoutForm(checkoutForm);
+            if (options.json)
+                options.write(`${JSON.stringify({ step: "checkout_form", removed: report.removed, failed: report.failed })}\n`);
+            else
+                for (const line of describeCheckoutFormRemoval(report))
+                    options.write(`${line}\n`);
+        }
+    }
     if (!options.json && (writes ?? []).some((w) => w.status === "written"))
         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");
-    return (writes ?? []).some((w) => w.status === "refused") ? 4 : code;
+    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.
+    if (process.env[SELF_UPDATE_ENVIRONMENT] === "1")
+        recordSelfUpdateState(process.env, outcome === 0 ? `installed:${CLI_VERSION}` : `failed:exit-${outcome}`, Date.now());
+    return outcome;
 }
 async function dispatch(parsed, write) {
     switch (parsed.command) {
@@ -522,11 +560,21 @@ async function dispatch(parsed, write) {
             return report.failed.length === 0 ? 0 : 6;
         }
         case "install":
-            return installEverything({ json: parsed.json, write, allowPartial: false });
+            return installEverything({
+                json: parsed.json,
+                write,
+                allowPartial: false,
+                controlPlane: parsed.controlPlane,
+            });
         case "setup":
             return runSetup({
                 installCommand: () => {
-                    const result = installEverything({ json: parsed.json, write, allowPartial: true });
+                    const result = installEverything({
+                        json: parsed.json,
+                        write,
+                        allowPartial: true,
+                        controlPlane: parsed.controlPlane,
+                    });
                     return process.platform === "win32" ? 0 : result;
                 },
                 controlPlane: parsed.controlPlane,

package/dist/commands/guidance.d.ts

@@ -1,13 +1,5 @@
 import { type GuidanceEvent } from "../guidance.js";
-/**
- * What an agent, or `status`, is told about a folder Balladeer is not tracking.
- *
- * Robert, 22 September 2026: the session hook says nothing in such a folder.
- * A customer with one repository has every other folder on the laptop
- * untracked, and a line in each of those is noise in the wrong place. This
- * sentence stays for the two readers who ask: `balladeer status` in the folder,
- * and an agent that opens the empty catalog and wonders why.
- */
+/** A repository-specific setup step for explicit status and empty-catalog responses. */
 export declare function untrackedLine(remote: string): string;
 export type GuidanceOptions = Readonly<{
     controlPlane: string;
@@ -23,7 +15,7 @@ export type GuidanceOptions = Readonly<{
     fetchImpl?: typeof fetch;
     now?: () => number;
     /** Runs the background update; injected so tests never reach npm. */
-    startUpdate?: (command: string, args: readonly string[]) => void;
+    startUpdate?: (command: string, args: readonly string[], environment: NodeJS.ProcessEnv) => boolean | void;
 }>;
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export declare function runGuidance(options: GuidanceOptions): Promise<number>;

package/dist/commands/guidance.js

@@ -5,15 +5,8 @@ import { selectAgent } from "../agent.js";
 import { repositoryHints } from "../repository.js";
 import { newerVersionPublished } from "../currency.js";
 import { startSelfUpdateIfDue } from "../self-update.js";
-/**
- * What an agent, or `status`, is told about a folder Balladeer is not tracking.
- *
- * Robert, 22 September 2026: the session hook says nothing in such a folder.
- * A customer with one repository has every other folder on the laptop
- * untracked, and a line in each of those is noise in the wrong place. This
- * sentence stays for the two readers who ask: `balladeer status` in the folder,
- * and an agent that opens the empty catalog and wonders why.
- */
+import { noteHookFired } from "../hook-trust.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})`;
     return (`${here} isn't connected to Balladeer on this laptop, so nothing is tracked from here. ` +
@@ -70,8 +63,7 @@ function identifier(input) {
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export async function runGuidance(options) {
     // A project hook names its repository and must match the checkout it sits
-    // in. A user-scope hook names none: the folder's remote decides, and a folder
-    // with no connection hears that it is untracked rather than nothing at all.
+    // in. A user-scope hook names none: the folder's remotes decide.
     const projectScoped = options.repositoryId !== undefined;
     if (projectScoped &&
         !validateProjectGuidanceScope({
@@ -93,23 +85,29 @@ export async function runGuidance(options) {
         event = parsedEvent;
         const record = input;
         const credentials = readCredentials(options.environment).agents;
+        const repositories = projectScoped ? [] : repositoryHints(options.cwd);
         const agents = projectScoped
             ? credentials.filter((agent) => agent.controlPlane === options.controlPlane &&
                 agent.repositoryId === options.repositoryId)
             : (() => {
-                const selection = selectAgent(credentials, options.controlPlane, undefined, repositoryHints(options.cwd));
+                const selection = selectAgent(credentials, options.controlPlane, undefined, repositories);
                 return selection.kind === "refused" ? [] : [selection.agent];
             })();
         if (agents.length !== 1 || !agents[0]) {
             if (projectScoped)
                 throw new Error("guidance_connection_unavailable");
-            // Untracked: nothing is said. `status` in the folder says why.
+            // Unconnected folders stay silent. An explicit status request explains setup.
             return 0;
         }
+        // A hook that runs has been trusted by its host; hosts that ask for that
+        // trust are the ones this matters to.
+        if (options.hook === "codex")
+            noteHookFired(options.environment, "codex");
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,
             timeoutMs: 750,
+            hook: options.hook,
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
         // Behind? Start the install in the background, once a day at most, and

package/dist/commands/mcp.d.ts

@@ -63,3 +63,9 @@ export declare function staleClientFrame(id: unknown, update: string): string;
  */
 export declare function revokedConnectionFrame(id: unknown, controlPlane: string): string;
 export declare function runMcp(options: McpOptions): Promise<number>;
+/**
+ * The tool's answer with one more text block at its end, or nothing when the
+ * answer is not a single tool result this can add to: a batch, an error frame,
+ * or anything it cannot parse is forwarded exactly as it came.
+ */
+export declare function withNotice(text: string, notice: string): string | undefined;

package/dist/commands/mcp.js

@@ -5,6 +5,7 @@ import { noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint, repositoryHints } from "../repository.js";
 import { CLI_VERSION } from "../wire.js";
 import { untrackedLine } from "./guidance.js";
+import { HOOKS_AWAITING_TRUST_NOTICE, hooksAwaitingTrust, trustingHost } from "../hook-trust.js";
 import { StoreError, readCredentials } from "../store.js";
 // The three commands that use an agent connection select and address it through
 // one module. These are re-exported because this is where the forwarder's
@@ -198,6 +199,11 @@ export async function runMcp(options) {
     if (guidanceInstall.status !== "not_applicable")
         options.error(`Balladeer guidance loader: ${guidanceInstall.status}${guidanceInstall.reason ? ` (${guidanceInstall.reason})` : ""}. New project hooks may need host trust; no trust is assumed.\n`);
     let saidUpdate = false;
+    // Which host this session belongs to is known from its hello; whether its
+    // hooks are waiting for the person's trust is asked at the first tool call,
+    // by which time a trusted session-start hook has certainly run.
+    let host;
+    let saidTrust = false;
     const lines = createInterface({ input: options.stdin, crlfDelay: Infinity });
     for await (const line of lines) {
         if (line.trim().length === 0)
@@ -247,7 +253,54 @@ export async function runMcp(options) {
             options.error("Balladeer refused a response frame larger than 4 MiB.\n");
             return 5;
         }
+        const request = frameOf(line);
+        if (request?.method === "initialize")
+            host = trustingHost(request.params?.clientInfo?.name);
+        if (!saidTrust &&
+            host !== undefined &&
+            request?.method === "tools/call" &&
+            hooksAwaitingTrust(options.environment, host)) {
+            const noted = withNotice(text, HOOKS_AWAITING_TRUST_NOTICE);
+            if (noted !== undefined) {
+                saidTrust = true;
+                options.write(`${noted}\n`);
+                continue;
+            }
+        }
         options.write(`${text.replace(/\n+$/, "")}\n`);
     }
     return 0;
 }
+function frameOf(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The tool's answer with one more text block at its end, or nothing when the
+ * answer is not a single tool result this can add to: a batch, an error frame,
+ * or anything it cannot parse is forwarded exactly as it came.
+ */
+export function withNotice(text, notice) {
+    try {
+        const frame = JSON.parse(text);
+        if (frame === null || typeof frame !== "object" || Array.isArray(frame))
+            return undefined;
+        const content = frame.result?.content;
+        if (!Array.isArray(content))
+            return undefined;
+        return JSON.stringify({
+            ...frame,
+            result: { ...frame.result, content: [...content, { type: "text", text: notice }] },
+        });
+    }
+    catch {
+        return undefined;
+    }
+}