balladeer 1.0.8 → 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;
@@ -19,7 +21,6 @@ type Parsed = Readonly<{
      */
     claudeDesktop: boolean | undefined;
     repo: string | undefined;
-    repoScope: boolean;
     file: string | undefined;
     repository: string | undefined;
     /**

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,9 +19,10 @@ 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 { 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}
@@ -31,13 +33,19 @@ const USAGE = `balladeer ${CLI_VERSION}
       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.
+  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.
 
-  ${CLI_INVOCATION} setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
+  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]
@@ -68,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
@@ -167,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) {
@@ -184,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;
@@ -197,7 +209,6 @@ export function parseArguments(argv) {
     let runner;
     let controlPlane;
     let repo;
-    let repoScope = false;
     let file;
     let owner;
     let createWorkspace;
@@ -257,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")
@@ -277,8 +290,6 @@ 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")
@@ -373,6 +384,7 @@ export function parseArguments(argv) {
         subcommand,
         json,
         wait,
+        noOpen,
         refresh,
         client,
         chooseWorkspace,
@@ -380,7 +392,6 @@ export function parseArguments(argv) {
         existingOnly,
         claudeDesktop,
         repo,
-        repoScope,
         file,
         repository: repositories[0],
         repositories,
@@ -418,64 +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 "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(),
+        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,
             });
-            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({
+            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,
-                json: parsed.json,
-                write,
-                extra: { userScope: writes },
+                cwd: process.cwd(),
             });
-            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`);
+            if (earlier.length === 0) {
+                write("No earlier Balladeer is on this machine.\n");
                 return 0;
             }
-            catch (error) {
-                write(`${error instanceof Error ? error.message : String(error)}\n`);
-                return 4;
-            }
+            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 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,5 +1,13 @@
 import { type GuidanceEvent } from "../guidance.js";
-/** What a session hears, once, in a folder Balladeer is not tracking. */
+/**
+ * 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;
@@ -14,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

@@ -2,15 +2,22 @@ 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. */
+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 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).`);
+    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) => {
@@ -90,15 +97,13 @@ export async function runGuidance(options) {
             ? credentials.filter((agent) => agent.controlPlane === options.controlPlane &&
                 agent.repositoryId === options.repositoryId)
             : (() => {
-                const selection = selectAgent(credentials, options.controlPlane, undefined, repositoryHint(options.cwd));
+                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. Said once, at session start, and never when silenced.
-            if (event === "SessionStart" && !isQuiet(options.cwd, options.environment))
-                emit(untrackedLine(repositoryHint(options.cwd)));
+            // Untracked: nothing is said. `status` in the folder says why.
             return 0;
         }
         const loaded = await loadGuidance({
@@ -107,6 +112,14 @@ export async function runGuidance(options) {
             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,7 @@ 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";
@@ -171,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

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