balladeer 1.0.13 → 1.0.14

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

@@ -24,6 +24,7 @@ import { PUBLISHED_SPECIFIER } from "./release.js";
 import { installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
 import { updateNotice } from "./currency.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "./remove-earlier.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,6 +472,23 @@ 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`);
+    // 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" : "") +
@@ -522,11 +540,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;

package/dist/commands/guidance.js

@@ -5,15 +5,7 @@ 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.
- */
+/** 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 +62,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,17 +84,18 @@ 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;
         }
         const loaded = await loadGuidance({

package/dist/guidance-hook.mjs

@@ -2027,7 +2027,7 @@ var require_toml = __commonJS({
 });
 
 // src/wire.ts
-var CLI_VERSION = "1.0.13";
+var CLI_VERSION = "1.0.14";
 var CLIENT_HEADER = "x-balladeer-client";
 var CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 var DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
@@ -3107,15 +3107,11 @@ 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,
-        void 0,
-        repositoryHints(options.cwd)
-      );
+      const selection = selectAgent(credentials, options.controlPlane, void 0, repositories);
       return selection.kind === "refused" ? [] : [selection.agent];
     })();
     if (agents.length !== 1 || !agents[0]) {

package/dist/wire.d.ts

@@ -5,10 +5,10 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.13";
+export declare const CLI_VERSION = "1.0.14";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.13";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.14";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.13";
+export const CLI_VERSION = "1.0.14";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,