balladeer 1.0.7 → 1.0.8

package/dist/cli.d.ts

@@ -19,6 +19,7 @@ type Parsed = Readonly<{
      */
     claudeDesktop: boolean | undefined;
     repo: string | undefined;
+    repoScope: boolean;
     file: string | undefined;
     repository: string | undefined;
     /**

package/dist/cli.js

@@ -18,15 +18,24 @@ import { runStatus } from "./commands/status.js";
 import { runTouchMap } from "./commands/touch-map.js";
 import { runWhoami } from "./commands/whoami.js";
 import { runInstall } from "./install.js";
+import { installUserScope, runningFromCheckout } from "./user-scope.js";
+import { setQuiet } from "./quiet.js";
 import { updateNotice } from "./currency.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
 import { CLI_INVOCATION, CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
 const USAGE = `balladeer ${CLI_VERSION}
 
   ${CLI_INVOCATION} install [--json]
-      Install this exact release as the durable balladeer command, without pairing
-      or changing any workspace, repository, or CI configuration. Use the latest
-      npx bootstrap to upgrade an older global command.
+      Install this exact release as the durable balladeer command, and register
+      Balladeer once for every Claude Code and Codex session on this machine:
+      it decides per folder, from the git remote, which connection applies.
+      Pairs nothing and changes no workspace, repository, or CI configuration.
+
+  ${CLI_INVOCATION} quiet [--repo]
+  ${CLI_INVOCATION} track [--repo]
+      In a folder Balladeer does not track, each session hears that once. quiet
+      stops it for this folder (or --repo, for every checkout of this
+      repository); track undoes it.
 
   ${CLI_INVOCATION} setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
                   [--create-workspace <name>] [--choose-workspace] [--refresh] [--force]
@@ -188,6 +197,7 @@ export function parseArguments(argv) {
     let runner;
     let controlPlane;
     let repo;
+    let repoScope = false;
     let file;
     let owner;
     let createWorkspace;
@@ -267,6 +277,8 @@ export function parseArguments(argv) {
             claudeDesktop = false;
         else if (name === "--control-plane")
             controlPlane = value("--control-plane", inline);
+        else if (name === "--repo" && (command === "quiet" || command === "track"))
+            repoScope = true;
         else if (name === "--repo")
             repo = value("--repo", inline);
         else if (name === "--file")
@@ -368,6 +380,7 @@ export function parseArguments(argv) {
         existingOnly,
         claudeDesktop,
         repo,
+        repoScope,
         file,
         repository: repositories[0],
         repositories,
@@ -409,8 +422,46 @@ async function dispatch(parsed, write) {
     switch (parsed.command) {
         case "explain":
             return runExplain(write, parsed.controlPlane);
-        case "install":
-            return runInstall({ environment: process.env, json: parsed.json, write });
+        case "install": {
+            // Once per laptop: the same server and hook, registered where every
+            // session on this machine reads them, deciding per folder at run time.
+            // Registered first and independently: the entries run through npx and
+            // need no durable command, so a blocked PATH must not keep a laptop
+            // from getting them.
+            const writes = installUserScope({
+                environment: process.env,
+                published: !runningFromCheckout(),
+            });
+            for (const w of writes)
+                if (!parsed.json)
+                    write(`${w.status === "refused" ? "Not changed" : w.status === "written" ? "Registered" : "Already current"}: ${w.path}${w.reason ? ` (${w.reason})` : ""}\n`);
+            if (!parsed.json && writes.some((w) => w.status === "written"))
+                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 says once that the folder isn't tracked. Approve the new hook when your coding host asks.\n");
+            const code = runInstall({
+                environment: process.env,
+                json: parsed.json,
+                write,
+                extra: { userScope: writes },
+            });
+            return writes.some((w) => w.status === "refused") ? 4 : code;
+        }
+        case "quiet":
+        case "track": {
+            const scope = parsed.repoScope ? "repo" : "folder";
+            try {
+                const { key, changed } = setQuiet(process.cwd(), scope, parsed.command === "quiet", process.env);
+                write(parsed.command === "quiet"
+                    ? `${changed ? "Balladeer will stay quiet" : "Balladeer was already quiet"} in ${scope === "repo" ? `every checkout of ${key}` : key}. Run \`balladeer track${scope === "repo" ? " --repo" : ""}\` here to undo.\n`
+                    : `${changed ? "Balladeer will speak again" : "Balladeer was not quiet"} in ${scope === "repo" ? `checkouts of ${key}` : key}.\n`);
+                return 0;
+            }
+            catch (error) {
+                write(`${error instanceof Error ? error.message : String(error)}\n`);
+                return 4;
+            }
+        }
         case "setup":
             return runSetup({
                 installCommand: () => {

package/dist/commands/guidance.d.ts

@@ -1,4 +1,6 @@
 import { type GuidanceEvent } from "../guidance.js";
+/** What a session hears, once, in a folder Balladeer is not tracking. */
+export declare function untrackedLine(remote: string): string;
 export type GuidanceOptions = Readonly<{
     controlPlane: string;
     repositoryId?: string;

package/dist/commands/guidance.js

@@ -1,6 +1,17 @@
 import { validateProjectGuidanceScope } from "../guidance-install.js";
 import { GUIDANCE_UNAVAILABLE, loadGuidance, recordGuidanceContext, } from "../guidance.js";
 import { readCredentials } from "../store.js";
+import { selectAgent } from "../agent.js";
+import { repositoryHint } from "../repository.js";
+import { isQuiet } from "../quiet.js";
+import { PUBLISHED_SPECIFIER } from "../release.js";
+/** What a session hears, once, in a folder Balladeer is not tracking. */
+export function untrackedLine(remote) {
+    const here = remote === "unknown/unknown" ? "This folder" : `This folder (${remote})`;
+    return (`${here} isn't tracked by Balladeer, so promises can't be tracked from here. ` +
+        `To track it, run \`npx -y ${PUBLISHED_SPECIFIER} setup\` in this folder. ` +
+        `To stop this message here, run \`npx -y ${PUBLISHED_SPECIFIER} quiet\` (or \`quiet --repo\` for the whole repository).`);
+}
 function readInput(stream) {
     return new Promise((resolve, reject) => {
         let bytes = 0;
@@ -51,8 +62,11 @@ function identifier(input) {
 }
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export async function runGuidance(options) {
-    // A globally invoked hook cannot use --repository to reach another project's connection.
-    if (!options.repositoryId ||
+    // 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.
+    const projectScoped = options.repositoryId !== undefined;
+    if (projectScoped &&
         !validateProjectGuidanceScope({
             cwd: options.cwd,
             hook: options.hook,
@@ -71,9 +85,22 @@ export async function runGuidance(options) {
             throw new Error("invalid_hook_event");
         event = parsedEvent;
         const record = input;
-        const agents = readCredentials(options.environment).agents.filter((agent) => agent.controlPlane === options.controlPlane && agent.repositoryId === options.repositoryId);
-        if (agents.length !== 1 || !agents[0])
-            throw new Error("guidance_connection_unavailable");
+        const credentials = readCredentials(options.environment).agents;
+        const agents = projectScoped
+            ? credentials.filter((agent) => agent.controlPlane === options.controlPlane &&
+                agent.repositoryId === options.repositoryId)
+            : (() => {
+                const selection = selectAgent(credentials, options.controlPlane, undefined, repositoryHint(options.cwd));
+                return selection.kind === "refused" ? [] : [selection.agent];
+            })();
+        if (agents.length !== 1 || !agents[0]) {
+            if (projectScoped)
+                throw new Error("guidance_connection_unavailable");
+            // Untracked. Said once, at session start, and never when silenced.
+            if (event === "SessionStart" && !isQuiet(options.cwd, options.environment))
+                emit(untrackedLine(repositoryHint(options.cwd)));
+            return 0;
+        }
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,

package/dist/commands/mcp.js

@@ -3,6 +3,8 @@ import { installGuidanceLoader } from "../guidance-install.js";
 import { callAgentTool, forwarderHeaders, noAgentCredentialSentence, safeJson, selectAgent, structuredString, updateLine, } from "../agent.js";
 import { noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint } from "../repository.js";
+import { CLI_VERSION } from "../wire.js";
+import { untrackedLine } from "./guidance.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
@@ -127,6 +129,39 @@ function frameId(line) {
     }
     return null;
 }
+/** The smallest server a host accepts: initialize, an empty tools list, ping. */
+async function serveUntracked(options, instructions) {
+    const lines = createInterface({ input: options.stdin, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (request.id === undefined)
+            continue; // a notification
+        const result = request.method === "initialize"
+            ? {
+                protocolVersion: request.params?.protocolVersion ?? "2025-06-18",
+                capabilities: { tools: {} },
+                serverInfo: { name: "balladeer", version: CLI_VERSION },
+                instructions,
+            }
+            : request.method === "tools/list"
+                ? { tools: [] }
+                : request.method === "ping"
+                    ? {}
+                    : undefined;
+        options.write(JSON.stringify(result === undefined
+            ? { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "Method not found" } }
+            : { jsonrpc: "2.0", id: request.id, result }) + "\n");
+    }
+    return 0;
+}
 export async function runMcp(options) {
     let credentials;
     try {
@@ -144,7 +179,14 @@ export async function runMcp(options) {
         options.error(selection.missingFor === undefined
             ? `${selection.reason} Run setup in this repository, or issue the connection at ${options.controlPlane}/setup.\n`
             : `${noAgentCredentialSentence(selection.missingFor)}\n`);
-        return 4;
+        // A project entry named its repository and got it wrong: that is an error
+        // the host should show. A user-scope entry named none and simply landed in
+        // a folder nobody tracks: that is ordinary, and a server that dies here
+        // shows up red in every untracked folder on the laptop. Answer the host
+        // with an empty catalog and the one sentence the hook also says.
+        if (options.repositoryId !== undefined)
+            return 4;
+        return serveUntracked(options, untrackedLine(repositoryHint(options.cwd)));
     }
     const { agent } = selection;
     const guidanceInstall = installGuidanceLoader({

package/dist/guidance-hook.mjs

@@ -2027,7 +2027,7 @@ var require_toml = __commonJS({
 });
 
 // src/wire.ts
-var CLI_VERSION = "1.0.7";
+var CLI_VERSION = "1.0.8";
 var CLIENT_HEADER = "x-balladeer-client";
 var CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 var DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
@@ -2411,6 +2411,11 @@ import {
   writeSync as writeSync2
 } from "node:fs";
 import { basename, dirname as dirname2, isAbsolute, join as join3 } from "node:path";
+
+// src/release.ts
+var PUBLISHED_SPECIFIER = "balladeer@latest";
+
+// src/mcp-config.ts
 var MCP_CONFIG_FILE = ".mcp.json";
 function sameOrigin(left, right) {
   try {
@@ -2865,7 +2870,129 @@ function validateProjectGuidanceScope(options) {
   }
 }
 
+// src/agent.ts
+var REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+function selectAgent(agents, controlPlane, repositoryId, currentRepository) {
+  const here = agents.filter((agent) => agent.controlPlane === controlPlane);
+  if (repositoryId !== void 0) {
+    const named = here.find(
+      (agent) => agent.repositoryId === repositoryId || agent.repository?.toLowerCase() === repositoryId.toLowerCase()
+    );
+    if (named === void 0) {
+      return {
+        kind: "refused",
+        reason: `No Balladeer connection for repository ${repositoryId} is stored for ${controlPlane}.`,
+        missingFor: repositoryId
+      };
+    }
+    return withSafeEndpoint(named);
+  }
+  if (!REPOSITORY_NAME.test(currentRepository) || currentRepository === "unknown/unknown") {
+    return {
+      kind: "refused",
+      reason: "This directory has no GitHub origin remote I could read, so I cannot tell which repository's Balladeer connection to use. Pass --repository <id>."
+    };
+  }
+  const matches = here.filter(
+    (agent) => agent.repository?.toLowerCase() === currentRepository.toLowerCase()
+  );
+  const chosen = matches[matches.length - 1];
+  if (chosen === void 0) {
+    return {
+      kind: "refused",
+      reason: `No Balladeer connection for ${currentRepository} is stored for ${controlPlane}.`,
+      missingFor: currentRepository
+    };
+  }
+  return withSafeEndpoint(chosen);
+}
+function withSafeEndpoint(agent) {
+  try {
+    if (new URL(agent.mcpUrl).origin !== new URL(agent.controlPlane).origin) {
+      return {
+        kind: "refused",
+        reason: "That connection's MCP endpoint is not on the control plane it belongs to, so I sent its credential nowhere."
+      };
+    }
+  } catch {
+    return {
+      kind: "refused",
+      reason: "That connection's MCP endpoint is not a URL, so I did not use it."
+    };
+  }
+  return { kind: "agent", agent };
+}
+
+// src/repository.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+var REPOSITORY_HINT_PATTERN = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+function repositoryHint(cwd = process.cwd()) {
+  let remote;
+  try {
+    remote = execFileSync2("git", ["-C", cwd, "remote", "get-url", "origin"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "unknown/unknown";
+  }
+  const match = /github\.com[:/]+([A-Za-z0-9._-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(
+    remote
+  );
+  if (!match) return "unknown/unknown";
+  const hint = `${match[1]}/${match[2]}`;
+  return REPOSITORY_HINT_PATTERN.test(hint) ? hint : "unknown/unknown";
+}
+
+// src/quiet.ts
+import { execFileSync as execFileSync3 } from "node:child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync6, realpathSync } from "node:fs";
+import { join as join6 } from "node:path";
+var EMPTY2 = { schemaVersion: 1, folders: [], remotes: [] };
+function quietPath(environment = process.env) {
+  return join6(configHome(environment), "quiet.json");
+}
+function readQuiet(environment = process.env) {
+  const path = quietPath(environment);
+  if (!existsSync3(path)) return EMPTY2;
+  try {
+    const parsed = JSON.parse(readFileSync6(path, "utf8"));
+    if (parsed.schemaVersion !== 1) return EMPTY2;
+    return {
+      schemaVersion: 1,
+      folders: Array.isArray(parsed.folders) ? parsed.folders.filter(isString) : [],
+      remotes: Array.isArray(parsed.remotes) ? parsed.remotes.filter(isString) : []
+    };
+  } catch {
+    return EMPTY2;
+  }
+}
+var isString = (value) => typeof value === "string";
+function folderKey(cwd) {
+  try {
+    return realpathSync(
+      execFileSync3("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 1e3
+      }).trim()
+    );
+  } catch {
+    return realpathSync(cwd);
+  }
+}
+function isQuiet(cwd, environment = process.env) {
+  const list = readQuiet(environment);
+  const folder = folderKey(cwd);
+  const remote = repositoryHint(cwd);
+  return list.folders.includes(folder) || remote !== "unknown/unknown" && list.remotes.some((r) => r.toLowerCase() === remote.toLowerCase());
+}
+
 // src/commands/guidance.ts
+function untrackedLine(remote) {
+  const here = remote === "unknown/unknown" ? "This folder" : `This folder (${remote})`;
+  return `${here} isn't tracked by Balladeer, so promises can't be tracked from here. To track it, run \`npx -y ${PUBLISHED_SPECIFIER} setup\` in this folder. To stop this message here, run \`npx -y ${PUBLISHED_SPECIFIER} quiet\` (or \`quiet --repo\` for the whole repository).`;
+}
 function readInput(stream) {
   return new Promise((resolve2, reject) => {
     let bytes = 0;
@@ -2908,7 +3035,8 @@ function identifier(input) {
   return typeof input === "string" && input.length > 0 && input.length <= 256 ? input : void 0;
 }
 async function runGuidance(options) {
-  if (!options.repositoryId || !validateProjectGuidanceScope({
+  const projectScoped = options.repositoryId !== void 0;
+  if (projectScoped && !validateProjectGuidanceScope({
     cwd: options.cwd,
     hook: options.hook,
     repositoryId: options.repositoryId,
@@ -2929,10 +3057,24 @@ async function runGuidance(options) {
       throw new Error("invalid_hook_event");
     event = parsedEvent;
     const record = input;
-    const agents = readCredentials(options.environment).agents.filter(
+    const credentials = readCredentials(options.environment).agents;
+    const agents = projectScoped ? credentials.filter(
       (agent) => agent.controlPlane === options.controlPlane && agent.repositoryId === options.repositoryId
-    );
-    if (agents.length !== 1 || !agents[0]) throw new Error("guidance_connection_unavailable");
+    ) : (() => {
+      const selection = selectAgent(
+        credentials,
+        options.controlPlane,
+        void 0,
+        repositoryHint(options.cwd)
+      );
+      return selection.kind === "refused" ? [] : [selection.agent];
+    })();
+    if (agents.length !== 1 || !agents[0]) {
+      if (projectScoped) throw new Error("guidance_connection_unavailable");
+      if (event === "SessionStart" && !isQuiet(options.cwd, options.environment))
+        emit(untrackedLine(repositoryHint(options.cwd)));
+      return 0;
+    }
     const loaded = await loadGuidance({
       agent: agents[0],
       environment: options.environment,

package/dist/install.d.ts

@@ -19,5 +19,7 @@ export declare function runInstall(options: InstallOptions & {
     json: boolean;
     write: (text: string) => void;
     allowPartial?: boolean;
+    /** Carried into the one JSON object this prints, never as a second line. */
+    extra?: Record<string, unknown>;
 }): number;
 export {};

package/dist/install.js

@@ -344,6 +344,7 @@ export function runInstall(options) {
                 ...result,
                 status: result.manualPathRequired ? "path_pending" : result.status,
                 message,
+                ...(options.extra ?? {}),
             }) + "\n"
             : message + "\n");
         return result.manualPathRequired && !options.allowPartial ? 4 : 0;
@@ -353,7 +354,12 @@ export function runInstall(options) {
             ? error.message
             : "Installation could not access a required local file or command. Allow the reported installer operation and retry; no pairing has started.";
         options.write(options.json
-            ? JSON.stringify({ step: "install", status: "blocked", message }) + "\n"
+            ? JSON.stringify({
+                step: "install",
+                status: "blocked",
+                message,
+                ...(options.extra ?? {}),
+            }) + "\n"
             : message + "\n");
         return 4;
     }

package/dist/quiet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where a person said "not here".
+ *
+ * With Balladeer registered once per laptop, every session in every folder
+ * asks whether this folder is tracked. In one that is not, the hook says so
+ * once and names the command that would track it; a person who does not want
+ * to hear that again in a scratch clone silences the folder, and one who does
+ * not want it for a whole product silences the remote. The default is the
+ * folder, because "not here" usually means this checkout and not the repository.
+ */
+export type QuietList = Readonly<{
+    schemaVersion: 1;
+    folders: string[];
+    remotes: string[];
+}>;
+export declare function quietPath(environment?: NodeJS.ProcessEnv): string;
+export declare function readQuiet(environment?: NodeJS.ProcessEnv): QuietList;
+/** The folder a session is in, as git names it, so a worktree and a clone are
+ * each their own folder while the remote stays one thing. */
+export declare function folderKey(cwd: string): string;
+export declare function isQuiet(cwd: string, environment?: NodeJS.ProcessEnv): boolean;
+export declare function setQuiet(cwd: string, scope: "folder" | "repo", quiet: boolean, environment?: NodeJS.ProcessEnv): {
+    key: string;
+    changed: boolean;
+};

package/dist/quiet.js

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomically } from "./mcp-config.js";
+import { repositoryHint } from "./repository.js";
+import { configHome } from "./store.js";
+const EMPTY = { schemaVersion: 1, folders: [], remotes: [] };
+export function quietPath(environment = process.env) {
+    return join(configHome(environment), "quiet.json");
+}
+export function readQuiet(environment = process.env) {
+    const path = quietPath(environment);
+    if (!existsSync(path))
+        return EMPTY;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.schemaVersion !== 1)
+            return EMPTY;
+        return {
+            schemaVersion: 1,
+            folders: Array.isArray(parsed.folders) ? parsed.folders.filter(isString) : [],
+            remotes: Array.isArray(parsed.remotes) ? parsed.remotes.filter(isString) : [],
+        };
+    }
+    catch {
+        return EMPTY;
+    }
+}
+const isString = (value) => typeof value === "string";
+function writeQuiet(list, environment) {
+    mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
+    writeJsonAtomically(quietPath(environment), JSON.stringify(list, null, 2) + "\n");
+}
+/** The folder a session is in, as git names it, so a worktree and a clone are
+ * each their own folder while the remote stays one thing. */
+export function folderKey(cwd) {
+    try {
+        return realpathSync(execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 1000,
+        }).trim());
+    }
+    catch {
+        return realpathSync(cwd);
+    }
+}
+export function isQuiet(cwd, environment = process.env) {
+    const list = readQuiet(environment);
+    const folder = folderKey(cwd);
+    const remote = repositoryHint(cwd);
+    return (list.folders.includes(folder) ||
+        (remote !== "unknown/unknown" &&
+            list.remotes.some((r) => r.toLowerCase() === remote.toLowerCase())));
+}
+export function setQuiet(cwd, scope, quiet, environment = process.env) {
+    const list = readQuiet(environment);
+    const key = scope === "folder" ? folderKey(cwd) : repositoryHint(cwd);
+    if (scope === "repo" && key === "unknown/unknown")
+        throw new Error("This folder has no GitHub origin remote, so there is no repository to name.");
+    const field = scope === "folder" ? "folders" : "remotes";
+    const has = list[field].some((x) => x.toLowerCase() === key.toLowerCase());
+    if (has === quiet)
+        return { key, changed: false };
+    const next = {
+        ...list,
+        [field]: quiet
+            ? [...list[field], key]
+            : list[field].filter((x) => x.toLowerCase() !== key.toLowerCase()),
+    };
+    writeQuiet(next, environment);
+    return { key, changed: true };
+}

package/dist/user-scope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Install Balladeer once per laptop.
+ *
+ * Setup used to write two files into one repository checkout, uncommitted: an
+ * `.mcp.json` entry and a hook in `.claude/settings.json`. A coding host lists
+ * a project server only when that exact folder is open, so every other clone,
+ * every worktree and every teammate saw nothing, and `/mcp` on two laptops
+ * showed only the legacy server. This registers the same server and the same
+ * hook at the host's user scope instead: one entry that runs in every session,
+ * and decides at run time, from the folder's git remote, which connection it
+ * is for. Nothing to commit and nothing per folder.
+ *
+ * Every write here is an additive merge that refuses to touch an entry it does
+ * not own, exactly as the project writers do. What it owns is recognised by
+ * shape, never by trust in the name.
+ */
+export declare const USER_SCOPE_OWNER = "Balladeer current guidance (user scope, loader 1)";
+export type UserScopeHost = "claude" | "codex";
+export type UserScopeWrite = Readonly<{
+    host: UserScopeHost;
+    path: string;
+    status: "current" | "written" | "refused";
+    reason?: string;
+}>;
+/** The command a host runs to reach Balladeer, with no repository named: the
+ * directory decides. The published form is what a laptop gets; the checkout
+ * form exists so this repository's own tests can point a host at source. */
+export declare function userScopeCommand(published: boolean): {
+    command: string;
+    args: string[];
+};
+/** `~/.claude.json` carries the user-scope MCP list under `mcpServers`. */
+export declare function mergeClaudeUserMcp(home: string, published: boolean): UserScopeWrite;
+/** Ours when it runs `npx` on our published specifier, or `node` on this
+ * checkout's entry file, with `mcp` as the subcommand and no repository named:
+ * a repository argument at user scope would pin every folder to one connection. */
+export declare function isOurUserEntry(entry: unknown): boolean;
+/** `~/.claude/settings.json` carries user-scope hooks. */
+export declare function mergeClaudeUserHooks(home: string, published: boolean): UserScopeWrite;
+/** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
+ * one fenced block this command owns end to end. */
+export declare function mergeCodexUserConfig(home: string, published: boolean): UserScopeWrite;
+/** A copy of this command running out of a source checkout registers the
+ * checkout; any installed or npx copy registers the published package. */
+export declare function runningFromCheckout(entry?: string): boolean;
+/** The home whose host files get the entries. `BALLADEER_USER_HOME` exists for
+ * this repository's own tests, which cannot move HOME under a Volta-managed
+ * Node without losing Node. */
+export declare function userHome(environment?: NodeJS.ProcessEnv): string;
+/** Register both hosts. Codex is skipped, not refused, on a laptop without it. */
+export declare function installUserScope(options: {
+    environment: NodeJS.ProcessEnv;
+    published: boolean;
+    home?: string;
+}): UserScopeWrite[];

package/dist/user-scope.js

@@ -0,0 +1,234 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { parse } from "@iarna/toml";
+import { PUBLISHED_SPECIFIER, checkoutEntryPath } from "./release.js";
+import { writeJsonAtomically } from "./mcp-config.js";
+/**
+ * Install Balladeer once per laptop.
+ *
+ * Setup used to write two files into one repository checkout, uncommitted: an
+ * `.mcp.json` entry and a hook in `.claude/settings.json`. A coding host lists
+ * a project server only when that exact folder is open, so every other clone,
+ * every worktree and every teammate saw nothing, and `/mcp` on two laptops
+ * showed only the legacy server. This registers the same server and the same
+ * hook at the host's user scope instead: one entry that runs in every session,
+ * and decides at run time, from the folder's git remote, which connection it
+ * is for. Nothing to commit and nothing per folder.
+ *
+ * Every write here is an additive merge that refuses to touch an entry it does
+ * not own, exactly as the project writers do. What it owns is recognised by
+ * shape, never by trust in the name.
+ */
+export const USER_SCOPE_OWNER = "Balladeer current guidance (user scope, loader 1)";
+const CLAUDE_EVENTS = ["SessionStart", "UserPromptSubmit", "SubagentStart"];
+/** The command a host runs to reach Balladeer, with no repository named: the
+ * directory decides. The published form is what a laptop gets; the checkout
+ * form exists so this repository's own tests can point a host at source. */
+export function userScopeCommand(published) {
+    return published
+        ? { command: "npx", args: ["-y", PUBLISHED_SPECIFIER] }
+        : { command: "node", args: [checkoutEntryPath()] };
+}
+function ordinaryFile(path) {
+    return !existsSync(path) || (lstatSync(path).isFile() && !lstatSync(path).isSymbolicLink());
+}
+/** `~/.claude.json` carries the user-scope MCP list under `mcpServers`. */
+export function mergeClaudeUserMcp(home, published) {
+    const path = join(home, ".claude.json");
+    const host = "claude";
+    if (!ordinaryFile(path))
+        return { host, path, status: "refused", reason: "not an ordinary file" };
+    let root = {};
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error();
+            root = parsed;
+        }
+        catch {
+            return { host, path, status: "refused", reason: "could not read valid JSON" };
+        }
+    }
+    const servers = root.mcpServers && typeof root.mcpServers === "object" && !Array.isArray(root.mcpServers)
+        ? root.mcpServers
+        : {};
+    const { command, args } = userScopeCommand(published);
+    const expected = { type: "stdio", command, args: [...args, "mcp"] };
+    const current = servers.balladeer;
+    if (current !== undefined && !isOurUserEntry(current)) {
+        return {
+            host,
+            path,
+            status: "refused",
+            reason: "an entry named balladeer that is not Balladeer's is already there",
+        };
+    }
+    if (current !== undefined && JSON.stringify(current) === JSON.stringify(expected))
+        return { host, path, status: "current" };
+    root.mcpServers = { ...servers, balladeer: expected };
+    writeJsonAtomically(path, JSON.stringify(root, null, 2) + "\n");
+    return { host, path, status: "written" };
+}
+/** Ours when it runs `npx` on our published specifier, or `node` on this
+ * checkout's entry file, with `mcp` as the subcommand and no repository named:
+ * a repository argument at user scope would pin every folder to one connection. */
+export function isOurUserEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const record = entry;
+    if (!Array.isArray(record.args) || record.args.some((a) => typeof a !== "string"))
+        return false;
+    const args = record.args;
+    if (record.command === "npx")
+        return (args.length === 3 &&
+            args[0] === "-y" &&
+            /^balladeer@(?:latest|\d+\.\d+\.\d+)$/.test(args[1]) &&
+            args[2] === "mcp");
+    if (record.command === "node" || String(record.command).endsWith("/node"))
+        return args.length === 2 && args[0] === checkoutEntryPath() && args[1] === "mcp";
+    return false;
+}
+/** `~/.claude/settings.json` carries user-scope hooks. */
+export function mergeClaudeUserHooks(home, published) {
+    const path = join(home, ".claude", "settings.json");
+    const host = "claude";
+    if (!ordinaryFile(path))
+        return { host, path, status: "refused", reason: "not an ordinary file" };
+    let root = {};
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error();
+            root = parsed;
+        }
+        catch {
+            return { host, path, status: "refused", reason: "could not read valid JSON" };
+        }
+    }
+    const hooks = root.hooks && typeof root.hooks === "object" && !Array.isArray(root.hooks)
+        ? { ...root.hooks }
+        : {};
+    const { command, args } = userScopeCommand(published);
+    const line = [command, ...args, "guidance", "--hook", "claude"].join(" ");
+    let changed = false;
+    for (const event of CLAUDE_EVENTS) {
+        const rows = hooks[event] === undefined ? [] : hooks[event];
+        if (!Array.isArray(rows))
+            return { host, path, status: "refused", reason: `hooks.${event} is not a list` };
+        const own = rows.filter((row) => row?.hooks?.some((h) => h.statusMessage === USER_SCOPE_OWNER));
+        const expected = {
+            hooks: [
+                {
+                    type: "command",
+                    command: `${line} --event ${event}`,
+                    // npx resolves from its cache in well under this; the first run on
+                    // a laptop that has never fetched the package needs the network.
+                    timeout: 10,
+                    statusMessage: USER_SCOPE_OWNER,
+                },
+            ],
+        };
+        if (own.length > 1)
+            return { host, path, status: "refused", reason: `two Balladeer hooks under ${event}` };
+        if (own.length === 1 && JSON.stringify(own[0]) === JSON.stringify(expected))
+            continue;
+        hooks[event] = [...rows.filter((row) => !own.includes(row)), expected];
+        changed = true;
+    }
+    if (!changed)
+        return { host, path, status: "current" };
+    root.hooks = hooks;
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonAtomically(path, JSON.stringify(root, null, 2) + "\n");
+    return { host, path, status: "written" };
+}
+const CODEX_START = "# balladeer:user:start";
+const CODEX_END = "# balladeer:user:end";
+/** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
+ * one fenced block this command owns end to end. */
+export function mergeCodexUserConfig(home, published) {
+    const path = join(home, ".codex", "config.toml");
+    const host = "codex";
+    if (!ordinaryFile(path))
+        return { host, path, status: "refused", reason: "not an ordinary file" };
+    let previous = "";
+    try {
+        if (existsSync(path))
+            previous = readFileSync(path, "utf8");
+        parse(previous);
+    }
+    catch {
+        return { host, path, status: "refused", reason: "could not read valid TOML" };
+    }
+    const { command, args } = userScopeCommand(published);
+    const line = [command, ...args, "guidance", "--hook", "codex"].join(" ");
+    const block = [
+        CODEX_START,
+        "[mcp_servers.balladeer]",
+        `command = ${JSON.stringify(command)}`,
+        `args = ${JSON.stringify([...args, "mcp"])}`,
+        ...CLAUDE_EVENTS.flatMap((event) => [
+            `[[hooks.${event}]]`,
+            `[[hooks.${event}.hooks]]`,
+            'type = "command"',
+            `command = ${JSON.stringify(`${line} --event ${event}`)}`,
+            "timeout = 10",
+            "additionalContextLimit = 0",
+        ]),
+        CODEX_END,
+    ].join("\n");
+    const starts = [...previous.matchAll(/^# balladeer:user:start\r?$/gm)];
+    const ends = [...previous.matchAll(/^# balladeer:user:end\r?$/gm)];
+    if (starts.length !== ends.length || starts.length > 1)
+        return { host, path, status: "refused", reason: "the Balladeer block is malformed" };
+    if (starts[0] && ends[0]) {
+        if (starts[0].index >= ends[0].index)
+            return { host, path, status: "refused", reason: "the Balladeer block is malformed" };
+        const old = previous.slice(starts[0].index, ends[0].index + CODEX_END.length);
+        if (old === block)
+            return { host, path, status: "current" };
+        const after = previous.slice(0, starts[0].index) + block + previous.slice(ends[0].index + CODEX_END.length);
+        parse(after);
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonAtomically(path, after);
+        return { host, path, status: "written" };
+    }
+    if (/^\[mcp_servers\.balladeer\]/m.test(previous))
+        return {
+            host,
+            path,
+            status: "refused",
+            reason: "an mcp_servers.balladeer table that is not Balladeer's is already there",
+        };
+    const after = previous + (previous.endsWith("\n") || previous === "" ? "" : "\n") + block + "\n";
+    parse(after);
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonAtomically(path, after);
+    return { host, path, status: "written" };
+}
+/** A copy of this command running out of a source checkout registers the
+ * checkout; any installed or npx copy registers the published package. */
+export function runningFromCheckout(entry = process.argv[1] ?? "") {
+    const normalized = entry.replaceAll("\\", "/");
+    return normalized.includes("/packages/cli/dist/") && !normalized.includes("/node_modules/");
+}
+/** The home whose host files get the entries. `BALLADEER_USER_HOME` exists for
+ * this repository's own tests, which cannot move HOME under a Volta-managed
+ * Node without losing Node. */
+export function userHome(environment = process.env) {
+    return resolve(environment.BALLADEER_USER_HOME?.trim() || environment.HOME?.trim() || homedir());
+}
+/** Register both hosts. Codex is skipped, not refused, on a laptop without it. */
+export function installUserScope(options) {
+    const home = options.home ?? userHome(options.environment);
+    const writes = [
+        mergeClaudeUserMcp(home, options.published),
+        mergeClaudeUserHooks(home, options.published),
+    ];
+    if (existsSync(join(home, ".codex")))
+        writes.push(mergeCodexUserConfig(home, options.published));
+    return writes;
+}

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.7";
+export declare const CLI_VERSION = "1.0.8";
 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.7";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.8";
 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.7";
+export const CLI_VERSION = "1.0.8";
 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.7",
+  "version": "1.0.8",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,
@@ -22,7 +22,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node build-guidance.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm --dir ../.. compat:release"
   },
   "devDependencies": {
     "typescript": "5.9.3",