balladeer 1.0.7 → 1.0.11

package/dist/agent.d.ts

@@ -41,7 +41,7 @@ export type AgentSelection = Readonly<{
  * points somewhere other than the control plane it belongs to is refused: a
  * server response must not be able to send this credential to a new host.
  */
-export declare function selectAgent(agents: readonly StoredAgent[], controlPlane: string, repositoryId: string | undefined, currentRepository: string): AgentSelection;
+export declare function selectAgent(agents: readonly StoredAgent[], controlPlane: string, repositoryId: string | undefined, currentRepository: string | readonly string[]): AgentSelection;
 /**
  * What a command says when this machine holds no credential for the repository.
  *

package/dist/agent.js

@@ -20,6 +20,18 @@ const REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
  */
 export function selectAgent(agents, controlPlane, repositoryId, currentRepository) {
     const here = agents.filter((agent) => agent.controlPlane === controlPlane);
+    // Several remotes, as `repositoryHints` lists them: the first with a
+    // connection is the folder's repository. One string is the older one-remote
+    // form and every caller of it still works.
+    if (typeof currentRepository !== "string") {
+        const candidates = currentRepository.filter((name) => REPOSITORY_NAME.test(name) && name !== "unknown/unknown");
+        for (const name of candidates) {
+            const found = selectAgent(agents, controlPlane, repositoryId, name);
+            if (found.kind !== "refused")
+                return found;
+        }
+        return selectAgent(agents, controlPlane, repositoryId, candidates[0] ?? "unknown/unknown");
+    }
     if (repositoryId !== undefined) {
         const named = here.find((agent) => agent.repositoryId === repositoryId ||
             agent.repository?.toLowerCase() === repositoryId.toLowerCase());

package/dist/cli.d.ts

@@ -4,11 +4,13 @@ type Parsed = Readonly<{
     subcommand: string | undefined;
     json: boolean;
     wait: boolean;
+    /** `setup --no-open`: print the approval link instead of opening it. */
+    noOpen: boolean;
     /** Repair the files a previous setup wrote, and do nothing else. */
     refresh: boolean;
     client: "codex" | "claude" | undefined;
     chooseWorkspace: boolean;
-    /** `setup --force`: set up even though an earlier Balladeer is still installed. */
+    /** `setup --force`: set up alongside an earlier Balladeer instead of removing it. */
     force: boolean;
     /** `setup --existing`: connect only when this checkout is already enrolled. */
     existingOnly: boolean;

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,17 +19,33 @@ 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 { 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 { 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} setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
+  balladeer update
+      Move the durable balladeer command to the latest published release. The
+      hooks and MCP entries already run the latest release on their own.
+
+  balladeer remove-earlier
+      Take the earlier Balladeer (the July client) off this machine and out of
+      this repository: its MCP server under the same name, its hooks and status
+      line, its guidance blocks and managed files (under your home and in this
+      repository's CLAUDE.md or AGENTS.md), and its 0.x command. A file git
+      does not track is copied beside itself first; a tracked one is for you
+      to commit. setup runs this itself when it finds one.
+
+  ${CLI_INVOCATION} setup [--repository owner/name]... [--json] [--wait] [--no-open] [--control-plane <url>]
                   [--create-workspace <name>] [--choose-workspace] [--refresh] [--force]
                   [--client codex|claude]
                   [--existing]
@@ -59,9 +76,12 @@ const USAGE = `balladeer ${CLI_VERSION}
       other entry in those files alone, and prints what it changed. Installing
       the command may contact npm; refresh never contacts Balladeer. Run it when
       Balladeer says a newer version is available.
-      --force sets up even though an earlier Balladeer is still installed on
-      this machine. Without it, a run that finds the older client's machine-wide
-      MCP entry or session hook stops and says to remove it first.
+      At a terminal with a person at it, the approval page opens in their
+      browser and the run waits for the approval; --no-open prints the link
+      instead. An agent shell, or --json, always prints the link and returns.
+      --force sets up alongside an earlier Balladeer instead of removing it.
+      Without it, a run that finds the older client takes it off first, with a
+      copy of every file it changes kept beside the file.
       Claude desktop chat is connected too, under a key named for this
       repository, wherever the app is installed. --claude-desktop asks for it by
       name, so a machine with no Claude desktop on it says so instead of
@@ -158,7 +178,7 @@ const USAGE = `balladeer ${CLI_VERSION}
 Exit codes: 0 progress reported truthfully, 2 pairing expired or denied or already
 claimed, 3 this copy is too old for the server, 4 usage or credential store problem,
 5 transport or server failure, 6 an earlier Balladeer is still installed on this
-machine and nothing was changed.
+machine and part of it could not be removed.
 `;
 const SUBCOMMANDS = { agent: ["rotate"] };
 export function parseArguments(argv) {
@@ -175,6 +195,7 @@ export function parseArguments(argv) {
     let event;
     let json = false;
     let wait = false;
+    let noOpen = false;
     let refresh = false;
     let client;
     let chooseWorkspace = false;
@@ -247,6 +268,8 @@ export function parseArguments(argv) {
             runner = value("--runner", inline);
         else if (name === "--wait")
             wait = true;
+        else if (name === "--no-open")
+            noOpen = true;
         else if (name === "--refresh")
             refresh = true;
         else if (name === "--choose-workspace")
@@ -361,6 +384,7 @@ export function parseArguments(argv) {
         subcommand,
         json,
         wait,
+        noOpen,
         refresh,
         client,
         chooseWorkspace,
@@ -405,26 +429,114 @@ export async function main(argv) {
         process.stderr.write(`${notice}\n`);
     return code;
 }
+/** What `balladeer --version` answers on this PATH, or nothing. */
+function commandVersion(name) {
+    const result = spawnSync(name, ["--version"], { encoding: "utf8", env: process.env });
+    const text = result.status === 0 ? result.stdout.trim() : "";
+    return /^\d+\.\d+\.\d+/.test(text) ? text : undefined;
+}
+/**
+ * Once per laptop: the durable command, then the same server and hook
+ * registered where every session on this machine reads them, naming that
+ * command by path so a session start costs node's startup and no npx. When
+ * the durable install is refused, the entries are still written, on the
+ * `npx` form of the current major: a blocked PATH must not keep a laptop from
+ * getting them. Nothing here needs approving in the coding host; Claude Code
+ * runs hooks from a person's own settings as they are.
+ */
+function installEverything(options) {
+    const published = !runningFromCheckout();
+    let writes;
+    const register = (installed) => {
+        writes = installUserScope({
+            environment: process.env,
+            published,
+            ...(installed === undefined ? {} : { installed }),
+        });
+        return writes;
+    };
+    const code = runInstall({
+        environment: process.env,
+        json: options.json,
+        write: options.write,
+        allowPartial: options.allowPartial,
+        onInstalled: (result) => ({ userScope: register(result.command) }),
+    });
+    if (writes === undefined) {
+        const fallback = register();
+        if (options.json)
+            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback })}\n`);
+    }
+    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`);
+    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;
+}
 async function dispatch(parsed, write) {
     switch (parsed.command) {
         case "explain":
             return runExplain(write, parsed.controlPlane);
+        case "update": {
+            // The latest published copy installs itself as the durable command, so
+            // this is one child process and its own report. Old and new are read
+            // from the command on PATH, before and after.
+            const before = commandVersion("balladeer");
+            const result = spawnSync("npx", ["-y", PUBLISHED_SPECIFIER, "install"], {
+                stdio: "inherit",
+                env: process.env,
+            });
+            if (result.status !== 0) {
+                write(`The update did not finish (exit ${result.status ?? "signal"}). Nothing else was changed.\n`);
+                return result.status ?? 5;
+            }
+            const after = commandVersion("balladeer");
+            write(before === after
+                ? `balladeer is already ${after ?? "installed"}.\n`
+                : `balladeer ${before ?? "(not on PATH)"} is now ${after ?? "installed"}.\n`);
+            return 0;
+        }
+        case "remove-earlier": {
+            const earlier = findEarlier({
+                home: userHome(process.env),
+                controlPlane: parsed.controlPlane,
+                environment: process.env,
+                cwd: process.cwd(),
+            });
+            if (earlier.length === 0) {
+                write("No earlier Balladeer is on this machine.\n");
+                return 0;
+            }
+            write("An earlier Balladeer is on this machine:\n");
+            for (const line of describeEarlier(earlier))
+                write(`${line}\n`);
+            const report = removeEarlier(earlier);
+            for (const line of describeRemoval(report))
+                write(`${line}\n`);
+            if (parsed.json)
+                write(`${JSON.stringify({ step: "earlier", removed: report.removed, failed: report.failed })}\n`);
+            return report.failed.length === 0 ? 0 : 6;
+        }
         case "install":
-            return runInstall({ environment: process.env, json: parsed.json, write });
+            return installEverything({ json: parsed.json, write, allowPartial: false });
         case "setup":
             return runSetup({
                 installCommand: () => {
-                    const result = runInstall({
-                        environment: process.env,
-                        json: parsed.json,
-                        write,
-                        allowPartial: true,
-                    });
+                    const result = installEverything({ json: parsed.json, write, allowPartial: true });
                     return process.platform === "win32" ? 0 : result;
                 },
                 controlPlane: parsed.controlPlane,
                 json: parsed.json,
                 wait: parsed.wait,
+                // A person is here when both ends of the terminal are a TTY; an agent
+                // shell has neither and keeps the print-and-return behaviour.
+                interactive: !parsed.noOpen &&
+                    !parsed.json &&
+                    process.stdout.isTTY === true &&
+                    process.stdin.isTTY === true,
                 refresh: parsed.refresh,
                 chooseWorkspace: parsed.chooseWorkspace,
                 ...(parsed.client === undefined ? {} : { client: parsed.client }),

package/dist/commands/discover.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { callAgentTool, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
 import { batchProposalReviewLink, proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
-import { repositoryHint } from "../repository.js";
+import { repositoryHint, repositoryHints } from "../repository.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
 import { CLI_INVOCATION } from "../wire.js";
 import { readTeachBackFile } from "./propose.js";
@@ -217,7 +217,7 @@ export async function runDiscover(options) {
     catch (error) {
         return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
     }
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHint(options.cwd));
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHints(options.cwd));
     if (selection.kind === "refused") {
         return fail("no_agent_connection", `${selection.reason} Run \`${commandLine(null, "setup")}\` in this repository first. Nothing was sent.`, 4);
     }

package/dist/commands/guidance.d.ts

@@ -1,4 +1,14 @@
 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.
+ */
+export declare function untrackedLine(remote: string): string;
 export type GuidanceOptions = Readonly<{
     controlPlane: string;
     repositoryId?: string;
@@ -12,6 +22,8 @@ export type GuidanceOptions = Readonly<{
     error?: (text: string) => void;
     fetchImpl?: typeof fetch;
     now?: () => number;
+    /** Runs the background update; injected so tests never reach npm. */
+    startUpdate?: (command: string, args: readonly string[]) => 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

@@ -1,6 +1,24 @@
 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 { 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.
+ */
+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. ` +
+        `To connect it, run \`balladeer setup\` in this folder.`);
+}
 function readInput(stream) {
     return new Promise((resolve, reject) => {
         let bytes = 0;
@@ -51,8 +69,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,15 +92,34 @@ 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, repositoryHints(options.cwd));
+                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.
+            return 0;
+        }
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,
             timeoutMs: 750,
             ...(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 } : {}),
+            });
         const sessionId = identifier(record.session_id);
         const agentId = identifier(record.agent_id);
         recordGuidanceContext({

package/dist/commands/mcp.js

@@ -2,7 +2,9 @@ import { createInterface } from "node:readline";
 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 { repositoryHint, repositoryHints } 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 {
@@ -136,7 +171,7 @@ export async function runMcp(options) {
         options.error(`${error instanceof StoreError ? error.message : String(error)}\n`);
         return 4;
     }
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repositoryId, repositoryHint(options.cwd));
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repositoryId, repositoryHints(options.cwd));
     if (selection.kind === "refused") {
         // Issuing one in the browser is what this used to suggest here, and it is the
         // move that produces this state: the bearer is shown once, there, and the
@@ -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/commands/prepare.js

@@ -3,7 +3,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, } from "../agent.js";
 import { inReadersZone } from "../local-time.js";
 import { commandLine } from "../release.js";
-import { repositoryHint } from "../repository.js";
+import { repositoryHint, repositoryHints } from "../repository.js";
 import { StoreError, readCredentials } from "../store.js";
 import {} from "../wire.js";
 const PROMISE_ID = /^prom_[a-z0-9]{8,64}$/;
@@ -138,7 +138,7 @@ export async function runPrepare(options) {
     catch (error) {
         return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
     }
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHint(options.cwd));
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHints(options.cwd));
     if (selection.kind === "refused") {
         if (selection.missingFor !== undefined) {
             return fail("no_agent_credential_on_this_machine", `${noAgentCredentialSentence(selection.missingFor)} Nothing was prepared.`, 4);

package/dist/commands/propose.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
 import { proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
-import { repositoryHint } from "../repository.js";
+import { repositoryHint, repositoryHints } from "../repository.js";
 import { StoreError, readCredentials } from "../store.js";
 import { CLI_INVOCATION } from "../wire.js";
 const MAX_FILE_BYTES = 64 * 1024;
@@ -215,7 +215,7 @@ export async function runPropose(options) {
     catch (error) {
         return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
     }
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHint(options.cwd));
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHints(options.cwd));
     if (selection.kind === "refused") {
         // The repository being connected somewhere else is not this machine holding
         // a credential, and a proposal runs over the one this machine holds. Said in

package/dist/commands/session.js

@@ -1,6 +1,6 @@
 import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, } from "../agent.js";
 import { headCommit } from "../git.js";
-import { repositoryHint } from "../repository.js";
+import { repositoryHint, repositoryHints } from "../repository.js";
 import { AGENT_SESSION_TRAILER, agentSessionTrailerLine, currentSession, readAgentSessionTrailer, } from "../session.js";
 import { StoreError, readCredentials } from "../store.js";
 import { CLI_INVOCATION } from "../wire.js";
@@ -43,7 +43,7 @@ export async function runSession(options) {
         return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
     }
     const here = options.repo ?? repositoryHint(options.cwd);
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHints(options.cwd));
     if (selection.kind === "refused") {
         const message = selection.missingFor === undefined
             ? selection.reason

package/dist/commands/setup.d.ts

@@ -2,6 +2,15 @@ export type SetupOptions = Readonly<{
     controlPlane: string;
     json: boolean;
     wait: boolean;
+    /**
+     * A person is at this terminal. The pairing link is opened in their browser
+     * and the run waits for the approval, so one command carries them through.
+     * Off in an agent shell, in `--json`, and under `--no-open`: those print the
+     * link and return. Robert, 22 September 2026.
+     */
+    interactive?: boolean;
+    /** Opens a page for the person; injected so tests never reach a browser. */
+    openLink?: (url: string) => boolean;
     repo?: string;
     createWorkspace?: string;
     client?: "codex" | "claude";
@@ -93,6 +102,12 @@ export declare function chooseRepositories(named: readonly string[], cwd: string
  * a command that blocks for minutes and the pairing would be lost with it.
  */
 export declare function runSetup(options: SetupOptions): Promise<number>;
+/**
+ * The link, opened for a person at the terminal and for nobody else. Whether a
+ * browser appeared is not known here; the line beside the link says what to do
+ * if none did.
+ */
+export declare function openForPerson(options: SetupOptions, url: string): boolean;
 /**
  * Which invocation this repair writes, decided without asking anybody.
  *