balladeer 1.0.1 → 1.0.3

package/dist/commands/setup.js

@@ -2,17 +2,17 @@ import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { ClientTooOldError, RefusalError, TransportError, proposalReviewLink, request, } from "../client.js";
+import { ClientTooOldError, RefusalError, TransportError, proposalReviewLink, reviewLink, request, } from "../client.js";
+import { CODEX_CONFIG_FILE, hasManagedCodexEntry, mergeCodexConfig, readCodexEntry, } from "../codex-config.js";
 import { writeConventions } from "../conventions.js";
 import { APPROVE_IN_THE_RIGHT_WORKSPACE, DISCOVERY_PLAYBOOK, JOIN_OR_CREATE } from "../copy.js";
 import { ghLogin, readPublicRepositoryFacts, readRepositoryFacts, runCommand, setRepositoryVariable, } from "../gh.js";
 import { CI_BRANCH, commitWorkflowOnBranch, repositoryRoot, workflowOnDefaultBranch, } from "../git.js";
-import { MCP_CONFIG_FILE, currentEntry, entryRepositoryId, mergeMcpConfig, readMcpConfig, stdioEntry, } from "../mcp-config.js";
+import { MCP_CONFIG_FILE, currentEntry, entryRepositoryId, isOurEntry, mergeMcpConfig, readMcpConfig, stdioEntry, } from "../mcp-config.js";
 import { DESKTOP_CONFIG_FILE, desktopConfigLocation, desktopServerKey, desktopStdioEntry, mergeDesktopConfig, } from "../desktop-config.js";
 import { selectAgent } from "../agent.js";
 import { findLegacyInstall, legacyMessage } from "../legacy.js";
 import { formatInstant } from "../local-time.js";
-import { CONVENTIONS_VERSION } from "../conventions.js";
 import { checkoutEntryPath, commandLine, runningFromRegistryInstall } from "../release.js";
 import { hostHint, repositoryHint } from "../repository.js";
 import { StoreError, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
@@ -268,6 +268,7 @@ export async function runSetup(options) {
     const { controlPlane } = options;
     const now = options.now ?? (() => new Date());
     say(options, `Balladeer setup, version ${CLI_VERSION}.\n`);
+    say(options, `Agent client: ${options.client === "codex" ? "Codex" : "Claude"}. Use --client codex or --client claude to choose.`);
     emit(options, { step: "explain", version: CLI_VERSION });
     say(options, explainText(controlPlane));
     const chosen = chooseRepositories(namedRepositories(options), options.cwd);
@@ -289,6 +290,21 @@ export async function runSetup(options) {
     catch (error) {
         return storeFailure(options, error);
     }
+    // Workspace choice is explicit. Preserve all agent connections and other
+    // origins; persist the session replacement only when a new pairing starts.
+    const workspaceChoice = options.createWorkspace !== undefined
+        ? `create:${carriedName}`
+        : options.chooseWorkspace === true
+            ? "choose"
+            : undefined;
+    if (workspaceChoice !== undefined) {
+        credentials = {
+            ...credentials,
+            sessions: credentials.sessions.filter((entry) => entry.controlPlane !== controlPlane),
+            pendingPairings: credentials.pendingPairings.filter((entry) => entry.controlPlane !== controlPlane || entry.workspaceChoice === workspaceChoice),
+        };
+        say(options, "Choose the workspace in the new browser pairing. Existing agent connections remain saved.");
+    }
     // A still-valid session carries straight on to the steps that need it.
     const stored = findSession(credentials, controlPlane);
     if (stored && Date.parse(stored.expiresAt) > now().getTime()) {
@@ -376,6 +392,7 @@ export async function runSetup(options) {
             verificationUri: started.verificationUriComplete,
             expiresAt: started.expiresAt,
             startedAt: now().toISOString(),
+            ...(workspaceChoice === undefined ? {} : { workspaceChoice }),
         };
         credentials = putPendingPairing(credentials, pending);
         writeCredentials(credentials, options.environment);
@@ -606,13 +623,26 @@ async function runRemainingSteps(options, credentials, session) {
     if (view !== undefined) {
         const step3 = await stepAgent(options, credentials, session, view, name, published);
         view = step3 ?? view;
-        view = (await stepCi(options, session, view, name)) ?? view;
+        view =
+            (options.existingOnly === true
+                ? reportInviteeCi(options, view)
+                : await stepCi(options, session, view, name)) ?? view;
         await stepPromise(options, session, view, published);
     }
     const finalState = await readState(options, session);
     printReceipts(options, session, finalState ?? state, view);
     return 0;
 }
+const ENFORCEMENT_UNAVAILABLE_WARNING = "This repository is not connected to Balladeer enforcement yet. You can continue onboarding and record promises, but Balladeer cannot track whether this repository's promises are enforced until its CI reports an authenticated run.";
+const NO_REPOSITORY_WARNING = "No repository in this workspace is connected for this checkout yet. You can continue onboarding in Balladeer, but a repository must be connected before its promises can be recorded and their enforcement tracked.";
+function warnEnforcementUnavailable(options, message = ENFORCEMENT_UNAVAILABLE_WARNING) {
+    say(options, `  WARNING  ${message}`);
+    emit(options, {
+        step: "warning",
+        code: "enforcement_unavailable",
+        message,
+    });
+}
 /**
  * Hands over the GitHub login this machine is signed in as, so a run this
  * person starts reads as their name rather than as a handle.
@@ -699,6 +729,15 @@ async function stepRepository(options, session, state, name, role = "primary") {
         });
         return { view };
     }
+    if (options.existingOnly === true) {
+        const reason = `${name} is not already in ${session.workspaceName}, so this teammate run left repository enrollment unchanged`;
+        say(options, enrollmentHeadline(role, `${name} is not connected  onboarding continues`));
+        say(options, `  ${reason}.`);
+        say(options, `  You can keep using Balladeer in the browser. A workspace administrator can connect a repository later; this run will not add one or change CI.`);
+        warnEnforcementUnavailable(options, NO_REPOSITORY_WARNING);
+        emit(options, { step: "repository", status: "not_connected", repository: name, reason });
+        return { view: undefined };
+    }
     if (!/^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/.test(name) || name === "unknown/unknown") {
         return blockedRepository(options, role, name, "this directory has no GitHub origin remote I could read", "Run this command inside a repository with a GitHub origin, or name one with --repository owner/name.");
     }
@@ -818,7 +857,7 @@ function blockedRepository(options, role, name, reason, next, publicFacts) {
 }
 const NO_DESKTOP = { lines: [], json: undefined };
 function connectClaudeDesktop(options, repositoryId, repositoryName) {
-    if (options.claudeDesktop === false)
+    if (options.claudeDesktop === false || options.client === "codex")
         return NO_DESKTOP;
     // Asked for by name, or taken by default. The difference is only whether a
     // machine with no Claude desktop on it hears about it: a person who typed the
@@ -877,11 +916,28 @@ function connectClaudeDesktop(options, repositoryId, repositoryName) {
         },
     };
 }
-function hostNextSteps() {
+function hostConfigFile(options) {
+    return options.client === "codex" ? CODEX_CONFIG_FILE : MCP_CONFIG_FILE;
+}
+function mergeHostConfig(options, root, repositoryId, published) {
+    const entry = stdioEntry(repositoryId, published);
+    return options.client === "codex"
+        ? mergeCodexConfig(root, { ...entry, args: [...entry.args, "--control-plane", options.controlPlane] }, options.controlPlane)
+        : mergeMcpConfig(root, entry, options.controlPlane);
+}
+function writeHostConventions(options, root) {
+    return writeConventions(root, options.client === "codex" ? { file: "AGENTS.md" } : {});
+}
+function hostNextSteps(options) {
+    if (options.client === "codex")
+        return [
+            "  Codex project configuration is ready. Open this repository in Codex and trust the project if appropriate; Codex ignores project configuration in untrusted projects.",
+            "  Start a fresh Codex session to load .codex/config.toml and AGENTS.md, then check that Balladeer's tools are available. The connection probe does not prove your Codex host loaded them.",
+        ];
     return [
-        `  Your agent host reads ${MCP_CONFIG_FILE} when it starts, so the tools appear in its next session rather than in one already running. Nothing here needs a restart: finish setup first.`,
+        `  Your agent host reads ${hostConfigFile(options)} when it starts, so the tools appear in its next session rather than in one already running. Nothing here needs a restart: finish setup first.`,
         "  Claude Code asks you to approve a project MCP server the first time it sees one, so approve balladeer when it asks. In a session already running, /mcp lists the servers and reconnects them.",
-        "  Another host reads its own configuration rather than this file: add the same entry there, and start it again.",
+        "  For Codex, run setup --client codex --refresh to configure this project's Codex MCP and AGENTS.md, then review project trust and start a fresh Codex session.",
     ];
 }
 /**
@@ -907,7 +963,69 @@ async function proveAgent(agent) {
  * is not mistaken for this one's.
  */
 function credentialOnThisMachine(agents, controlPlane, repositoryId) {
-    return agents.some((agent) => agent.controlPlane === controlPlane && agent.repositoryId === repositoryId);
+    return agents.find((agent) => agent.controlPlane === controlPlane && agent.repositoryId === repositoryId);
+}
+/**
+ * Reconcile every local host surface whether the bearer was issued now or was
+ * already on this machine. A credential is not a project MCP installation:
+ * another checkout, a deleted uncommitted file, or an interrupted earlier run
+ * can leave the first present and the second absent.
+ */
+async function configureAgentHost(options, repositoryId, name, published) {
+    const root = await repositoryRoot(options.cwd);
+    const files = [];
+    let merged;
+    let conventions;
+    if (root !== undefined) {
+        merged = mergeHostConfig(options, root, repositoryId, published);
+        if (merged.kind === "written") {
+            if (merged.changed)
+                files.push(hostConfigFile(options));
+            conventions = writeHostConventions(options, root);
+            if (conventions.kind === "written" && conventions.changed)
+                files.push(conventions.file);
+        }
+    }
+    return {
+        root,
+        files,
+        merged,
+        conventions,
+        desktop: connectClaudeDesktop(options, repositoryId, name),
+    };
+}
+function reportAgentHost(options, configured, published) {
+    if (configured.root === undefined) {
+        say(options, `  This directory is not a git work tree, so I wrote no ${hostConfigFile(options)} and no instructions block.`);
+    }
+    else {
+        if (configured.merged?.kind === "refused") {
+            say(options, `  ${configured.merged.reason}`);
+            say(options, "  Merge this block into it yourself:");
+            for (const line of configured.merged.block.split("\n"))
+                say(options, `    ${line}`);
+        }
+        if (configured.conventions?.kind === "refused") {
+            say(options, `  ${configured.conventions.reason}`);
+            say(options, `  Repair the markers in ${configured.conventions.file}, or delete the block between them, then run this command again.`);
+        }
+        if (configured.merged?.kind === "written") {
+            say(options, `  The ${hostConfigFile(options)} entry runs this command's own MCP forwarder for this repository and reads the credential from that store, so there is nothing else to set. This command never prints the credential.`);
+            if (published === null && !existsSync(checkoutEntryPath())) {
+                say(options, `  That entry runs ${checkoutEntryPath()}, which this checkout has not built yet. Run \`pnpm --filter balladeer build\` once so your agent host can start it.`);
+            }
+        }
+    }
+    for (const line of configured.desktop.lines)
+        say(options, line);
+    for (const line of hostNextSteps(options))
+        say(options, line);
+    say(options, published === null
+        ? `  Setup does not install a global balladeer executable. This checkout's CLI runs as \`${commandLine(null, "<command>")}\` after it is built.`
+        : `  Setup does not install a global balladeer executable. Run the CLI as \`${commandLine(published, "<command>")}\`; ${hostConfigFile(options)} invokes that same package automatically.`);
+    if (configured.files.length > 0) {
+        say(options, `  ${configured.files.join(" and ")} ${configured.files.length === 1 ? "is an uncommitted change" : "are uncommitted changes"} in your working tree. Commit ${configured.files.length === 1 ? "it" : "them"} when you are ready; they carry no secret.`);
+    }
 }
 /**
  * Whose credential this step is about: this machine's.
@@ -932,15 +1050,36 @@ function credentialOnThisMachine(agents, controlPlane, repositoryId) {
  */
 async function stepAgent(options, credentials, session, view, name, published) {
     const heldHere = credentialOnThisMachine(credentials.agents, options.controlPlane, view.id);
-    if (heldHere && view.agentConfigured) {
-        say(options, "Step 3 of 5  This coding agent is already connected on this machine");
+    if (heldHere !== undefined && view.agentConfigured) {
+        const configured = await configureAgentHost(options, view.id, name, published);
+        const proof = await proveAgent(heldHere);
+        const repaired = configured.files.length > 0 ? `  repaired ${configured.files.join(" and ")}` : "";
+        say(options, proof.kind === "answered"
+            ? `Step 3 of 5  This coding agent is already connected on this machine${repaired}`
+            : `Step 3 of 5  This machine holds an agent credential  not yet proven${repaired}`);
         say(options, `  ${name}'s credential is in ${credentialsPath(options.environment)}, so nothing was issued and nothing was rotated. A credential belongs to the machine it was issued on: another machine runs this command there to get its own.`);
+        if (proof.kind === "answered") {
+            say(options, `  Balladeer answered a get_promise_setup call for ${name} over this connection just now.`);
+        }
+        else {
+            say(options, `  ${proof.reason}. ${proof.nextAction}`);
+        }
+        reportAgentHost(options, configured, published);
         emit(options, {
             step: "agent",
-            status: "already",
+            status: proof.kind === "answered" ? "already" : "unproven",
             repositoryId: view.id,
             storedHere: true,
             ...(view.agentConnectionId === null ? {} : { connectionId: view.agentConnectionId }),
+            files: configured.files,
+            ...(proof.kind === "answered"
+                ? { provedBy: "get_promise_setup" }
+                : { reason: proof.reason, nextAction: proof.nextAction }),
+            ...(configured.merged?.kind === "refused" ? { mcpConfig: configured.merged.reason } : {}),
+            ...(configured.conventions?.kind === "refused"
+                ? { conventions: configured.conventions.reason }
+                : {}),
+            ...(configured.desktop.json === undefined ? {} : { claudeDesktop: configured.desktop.json }),
         });
         return undefined;
     }
@@ -950,7 +1089,7 @@ async function stepAgent(options, credentials, session, view, name, published) {
     // A credential in this store, and no live connection anywhere for the
     // repository: the one this machine holds was revoked. Holding it is not being
     // connected, so this issues rather than reporting the stored entry as working.
-    const revokedHere = heldHere && !view.agentConfigured;
+    const revokedHere = heldHere !== undefined && !view.agentConfigured;
     let packet;
     try {
         packet = await request(options.controlPlane, {
@@ -980,30 +1119,13 @@ async function stepAgent(options, credentials, session, view, name, published) {
     catch (error) {
         return blockedAgent(options, view, error instanceof StoreError ? error.message : "the credential store could not be written");
     }
-    const root = await repositoryRoot(options.cwd);
-    const files = [];
-    let merged;
-    let conventions;
-    if (root !== undefined) {
-        // The stdio forwarder, bound to this repository. It reads the bearer from
-        // the credential store this step just wrote, so the connection works from
-        // here with nothing further for anyone to set, and the file carries no
-        // secret.
-        merged = mergeMcpConfig(root, stdioEntry(packet.repositoryId, published), options.controlPlane);
-        if (merged.kind === "written") {
-            if (merged.changed)
-                files.push(MCP_CONFIG_FILE);
-            conventions = writeConventions(root);
-            if (conventions.kind === "written" && conventions.changed)
-                files.push(conventions.file);
-        }
-    }
+    const configured = await configureAgentHost(options, packet.repositoryId, name, published);
     // The probe runs after the files, because the files are not what it proves.
     // The credential, the endpoint, and the frames this command's own forwarder
     // sends are.
     const proof = await proveAgent(agent);
-    const wrote = merged?.kind === "written" && conventions?.kind === "written"
-        ? `, ${MCP_CONFIG_FILE} and ${conventions.file} updated`
+    const wrote = configured.merged?.kind === "written" && configured.conventions?.kind === "written"
+        ? `, ${hostConfigFile(options)} and ${configured.conventions.file} updated`
         : "";
     say(options, proof.kind === "answered"
         ? `Step 3 of 5  Connected this coding agent on this machine  credential stored in ${credentialsPath(options.environment)}${wrote}`
@@ -1020,45 +1142,7 @@ async function stepAgent(options, credentials, session, view, name, published) {
         say(options, `  The credential is stored, but ${proof.reason}, so this is not reported as connected.`);
         say(options, `  ${proof.nextAction}`);
     }
-    if (root === undefined) {
-        say(options, `  This directory is not a git work tree, so I wrote no ${MCP_CONFIG_FILE} and no instructions block.`);
-    }
-    else {
-        if (merged?.kind === "refused") {
-            say(options, `  ${merged.reason}`);
-            say(options, "  Merge this block into it yourself:");
-            for (const line of merged.block.split("\n"))
-                say(options, `    ${line}`);
-        }
-        if (conventions?.kind === "refused") {
-            say(options, `  ${conventions.reason}`);
-            say(options, `  Repair the markers in ${conventions.file}, or delete the block between them, then run this command again.`);
-        }
-        if (merged?.kind === "written") {
-            // Nothing further is asked of anybody about the credential. The entry runs
-            // this command's own forwarder, which reads the bearer out of the store
-            // above, so there is no variable to export and no secret to carry by hand.
-            say(options, `  The ${MCP_CONFIG_FILE} entry runs this command's own MCP forwarder for this repository and reads the credential from that store, so there is nothing else to set. This command never prints the credential.`);
-            if (published === null && !existsSync(checkoutEntryPath())) {
-                say(options, `  That entry runs ${checkoutEntryPath()}, which this checkout has not built yet. Run \`pnpm --filter balladeer build\` once so your agent host can start it.`);
-            }
-        }
-    }
-    // The chat client, connected from the same credential this step just stored.
-    // It is not conditional on a git work tree, because the desktop app has no
-    // notion of a project and its file lives in this person's home directory
-    // rather than in the repository.
-    const desktop = connectClaudeDesktop(options, packet.repositoryId, name);
-    for (const line of desktop.lines)
-        say(options, line);
-    // Said on every ending of this step, including the ones where no file was
-    // written: whoever is reading has to configure that host by hand, and they
-    // need the same two facts about when a host picks an entry up.
-    for (const line of hostNextSteps())
-        say(options, line);
-    if (files.length > 0) {
-        say(options, `  ${files.join(" and ")} ${files.length === 1 ? "is an uncommitted change" : "are uncommitted changes"} in your working tree. Commit ${files.length === 1 ? "it" : "them"} when you are ready; they carry no secret.`);
-    }
+    reportAgentHost(options, configured, published);
     emit(options, {
         step: "agent",
         status: proof.kind === "answered" ? "connected" : "unproven",
@@ -1066,13 +1150,15 @@ async function stepAgent(options, credentials, session, view, name, published) {
         connectionId: packet.connectionId,
         storedHere: true,
         ...(connectedElsewhere ? { alreadyConnectedElsewhere: true } : {}),
-        files,
+        files: configured.files,
         ...(proof.kind === "answered"
             ? { provedBy: "get_promise_setup" }
             : { reason: proof.reason, nextAction: proof.nextAction }),
-        ...(merged?.kind === "refused" ? { mcpConfig: merged.reason } : {}),
-        ...(conventions?.kind === "refused" ? { conventions: conventions.reason } : {}),
-        ...(desktop.json === undefined ? {} : { claudeDesktop: desktop.json }),
+        ...(configured.merged?.kind === "refused" ? { mcpConfig: configured.merged.reason } : {}),
+        ...(configured.conventions?.kind === "refused"
+            ? { conventions: configured.conventions.reason }
+            : {}),
+        ...(configured.desktop.json === undefined ? {} : { claudeDesktop: configured.desktop.json }),
     });
     return undefined;
 }
@@ -1084,6 +1170,34 @@ function blockedAgent(options, view, reason) {
     return undefined;
 }
 /* ----------------------------- Step 4 ------------------------------------ */
+/**
+ * A teammate run reports CI truth and never becomes repository maintenance.
+ * Adding or updating a workflow, setting repository variables, and opening a
+ * pull request all belong to the administrator/maintainer path.
+ */
+function reportInviteeCi(options, view) {
+    if (view.ciConfigured) {
+        say(options, `Step 4 of 5  CI already connected  ${view.ciValidatedRunCount} authenticated run${view.ciValidatedRunCount === 1 ? "" : "s"} observed`);
+        emit(options, {
+            step: "ci",
+            status: "connected",
+            repositoryId: view.id,
+            validatedRunCount: view.ciValidatedRunCount,
+            ...(view.ciFirstValidatedAt === null ? {} : { firstValidatedAt: view.ciFirstValidatedAt }),
+        });
+        return undefined;
+    }
+    say(options, "Step 4 of 5  CI is not connected  teammate onboarding continues");
+    say(options, "  This run did not write a workflow, set GitHub variables, push a branch, or open a pull request.");
+    warnEnforcementUnavailable(options);
+    emit(options, {
+        step: "ci",
+        status: "not_changed",
+        repositoryId: view.id,
+        reason: "Teammate setup leaves repository CI unchanged.",
+    });
+    return undefined;
+}
 async function stepCi(options, session, view, name) {
     // Checked on every run, and BEFORE the connected branch below, because an
     // already-connected repository is exactly the one this happens to. Balladeer
@@ -1342,7 +1456,7 @@ async function stepPromise(options, session, view, published) {
     const state = await readState(options, session);
     const current = state?.repositories.find((repository) => repository.id === view.id) ?? view;
     if (current.firstPromiseId !== null) {
-        const promiseUrl = `${options.controlPlane}/promises/${current.firstPromiseId}`;
+        const promiseUrl = reviewLink(options.controlPlane, `promises/${encodeURIComponent(current.firstPromiseId)}`, session.workspaceId);
         say(options, "Step 5 of 5  A named person agreed to the first promise");
         say(options, `  ${promiseUrl}`);
         say(options, "  It stands agreed and is not yet protected. Protection starts on its own the moment a verifier qualifies, once the verifier pull request has merged. Nobody is asked to turn it on.");
@@ -1355,7 +1469,7 @@ async function stepPromise(options, session, view, published) {
         return;
     }
     if (current.latestCandidateId !== null) {
-        const reviewUrl = proposalReviewLink(options.controlPlane, current.latestCandidateId);
+        const reviewUrl = proposalReviewLink(options.controlPlane, current.latestCandidateId, session.workspaceId);
         say(options, "Step 5 of 5  A first promise is proposed and waiting for a person");
         say(options, `  Review it: ${reviewUrl}`);
         say(options, "  A named person reads the proposal and clicks Agree. Nothing else can.");
@@ -1415,10 +1529,12 @@ function printReceipts(options, session, state, view) {
     // promise the receipt below it said already stood agreed.
     const promiseId = current?.firstPromiseId ?? null;
     const candidateId = current?.latestCandidateId ?? null;
-    const promiseUrl = promiseId === null ? undefined : `${options.controlPlane}/promises/${promiseId}`;
+    const promiseUrl = promiseId === null
+        ? undefined
+        : reviewLink(options.controlPlane, `promises/${encodeURIComponent(promiseId)}`, state.workspace.id);
     const reviewUrl = promiseId !== null || candidateId === null
         ? undefined
-        : proposalReviewLink(options.controlPlane, candidateId);
+        : proposalReviewLink(options.controlPlane, candidateId, state.workspace.id);
     const promiseLink = promiseUrl ?? reviewUrl;
     const promiseSentence = promiseId !== null
         ? "Agreed. A named person agreed to this repository's first promise."
@@ -1508,13 +1624,21 @@ export function refreshPublishedForm(existing) {
  * changed. Run twice it changes nothing the second time, which is what makes it
  * safe to put in a nag an agent will act on without asking.
  */
-async function runRefresh(options) {
+async function runRefresh(input) {
+    let options = input;
     say(options, `Balladeer setup --refresh, version ${CLI_VERSION}.\n`);
     const root = await repositoryRoot(options.cwd);
     if (root === undefined) {
         return failRefresh(options, "not_a_repository", "This directory is not a git work tree, so there is no repository configuration to refresh.");
     }
-    const existing = currentEntry(readMcpConfig(root));
+    if (options.client === undefined && hasManagedCodexEntry(root, options.controlPlane)) {
+        if (isOurEntry(currentEntry(readMcpConfig(root)), options.controlPlane)) {
+            return failRefresh(options, "client_ambiguous", "Both Codex and Claude have Balladeer project entries. Run setup --client codex --refresh or setup --client claude --refresh. No files were changed.");
+        }
+        options = { ...options, client: "codex" };
+        say(options, "Using Codex for refresh because this repository has only its managed Balladeer entry.");
+    }
+    const existing = options.client === "codex" ? readCodexEntry(root) : currentEntry(readMcpConfig(root));
     let stored;
     let storedName;
     try {
@@ -1535,9 +1659,9 @@ async function runRefresh(options) {
     // that never paired can still repair a checkout somebody else set up.
     const repositoryId = stored ?? entryRepositoryId(existing);
     if (repositoryId === undefined) {
-        return failRefresh(options, "not_connected", `Nothing here names a repository to refresh: this machine holds no Balladeer credential for it and ${MCP_CONFIG_FILE} has no balladeer entry. Run \`${commandLine(null, "setup")}\` to connect it.`);
+        return failRefresh(options, "not_connected", `Nothing here names a repository to refresh: this machine holds no Balladeer credential for it and ${hostConfigFile(options)} has no balladeer entry. Run \`${commandLine(null, "setup")}\` to connect it.`);
     }
-    const merged = mergeMcpConfig(root, stdioEntry(repositoryId, refreshPublishedForm(existing)), options.controlPlane);
+    const merged = mergeHostConfig(options, root, repositoryId, refreshPublishedForm(existing));
     if (merged.kind === "refused") {
         say(options, merged.reason);
         say(options, "Merge this block into it yourself:");
@@ -1545,7 +1669,7 @@ async function runRefresh(options) {
             say(options, `  ${line}`);
         return failRefresh(options, "mcp_config_refused", merged.reason);
     }
-    const conventions = writeConventions(root);
+    const conventions = writeHostConventions(options, root);
     if (conventions.kind === "refused") {
         say(options, conventions.reason);
         return failRefresh(options, "conventions_refused", conventions.reason);
@@ -1558,12 +1682,12 @@ async function runRefresh(options) {
     const desktop = connectClaudeDesktop(options, repositoryId, storedName ?? repositoryHint(options.cwd));
     const files = [];
     if (merged.changed)
-        files.push(MCP_CONFIG_FILE);
+        files.push(hostConfigFile(options));
     if (conventions.changed)
         files.push(conventions.file);
     say(options, merged.changed
-        ? `Rewrote the balladeer entry in ${MCP_CONFIG_FILE}. Every other entry in that file is untouched.`
-        : `${MCP_CONFIG_FILE} already names the current command; I left it alone.`);
+        ? `Rewrote the balladeer entry in ${hostConfigFile(options)}. Every other entry in that file is untouched.`
+        : `${hostConfigFile(options)} already names the current command; I left it alone.`);
     say(options, conventions.changed
         ? `Rewrote the Balladeer block in ${conventions.file} to conventions v${conventions.version}${conventions.previousVersion === undefined
             ? ""
@@ -1574,6 +1698,9 @@ async function runRefresh(options) {
     // never a change anybody commits: it lives in this person's home directory.
     for (const line of desktop.lines)
         say(options, line.replace(/^ {2}/, ""));
+    if (options.client === "codex")
+        for (const line of hostNextSteps(options))
+            say(options, line);
     if (files.length === 0 && desktop.json?.status !== "connected") {
         say(options, "Nothing to change: this repository is already on the current form.");
     }

package/dist/commands/status.js

@@ -1,5 +1,5 @@
-import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
-import { ClientTooOldError, RefusalError, TransportError, proposalReviewLink, request, } from "../client.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
+import { ClientTooOldError, RefusalError, TransportError, proposalReviewLink, reviewLink, request, } from "../client.js";
 import { repositoryRoot } from "../git.js";
 import { MARKER_OBSERVATION_LIMITS, observeMissingMarkers, staleMarkerRow, } from "../markers.js";
 import { formatInstant } from "../local-time.js";
@@ -7,7 +7,7 @@ import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { SEALED_PATHS_SHOWN, sealedPromises } from "../seals.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 /**
  * The bounded code for "this machine holds no credential for that repository".
  * It is its own code rather than the session's: an agent branching on
@@ -104,7 +104,23 @@ async function reportBalladeer(options) {
     }
     const here = options.repo ?? repositoryHint(options.cwd);
     const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
-    const session = findSession(credentials, options.controlPlane);
+    const storedSession = findSession(credentials, options.controlPlane);
+    const repositoryScoped = options.repo !== undefined ||
+        options.repository !== undefined ||
+        here !== "unknown/unknown" ||
+        (await repositoryRoot(options.cwd)) !== undefined;
+    const hasBoundSession = typeof storedSession?.workspaceId === "string" && storedSession.workspaceId.trim().length > 0;
+    // A setup session belongs to one workspace, not to every repository whose
+    // agent happens to be stored on this machine. Establish that relationship
+    // before sending its bearer or fetching its workspace-wide context.
+    const session = hasBoundSession &&
+        (!repositoryScoped ||
+            (selection.kind === "agent" && selection.agent.workspaceId === storedSession.workspaceId))
+        ? storedSession
+        : undefined;
+    const missingWorkspace = () => sayWorkspaceUnavailable(emit, say, storedSession === undefined ? "no_stored_setup_session" : "setup_session_scope_unverified", storedSession === undefined
+        ? noSessionSentence(options.controlPlane)
+        : "An optional workspace view was skipped because the saved setup session could not be tied to this request. No workspace read was sent.");
     // The credential this machine holds is what this repository is read over, so
     // its absence is the first thing said, and it is said in its own words. What
     // the founder got instead was the workspace half's refusal, "Balladeer refused
@@ -120,21 +136,13 @@ async function reportBalladeer(options) {
         else {
             options.write(`${message}\n`);
         }
-        if (session === undefined) {
-            sayWorkspaceUnavailable(emit, say, "no_stored_setup_session", noSessionSentence(options.controlPlane));
-        }
-        else {
-            // A different question, over a different credential, so it is still
-            // answered underneath. Its outcome never becomes this run's exit code:
-            // this repository went unreported whatever the workspace read did.
-            await reportWorkspace(options, session, here, emit, say, true);
-        }
+        missingWorkspace();
         return 4;
     }
     if (selection.kind === "refused" && session === undefined) {
         // Nothing stored can answer anything, so this names the form that always
         // works: the one this copy was run as.
-        return fail("nothing_stored", `${selection.reason} No Balladeer setup session is stored for ${options.controlPlane} either. Run: ${commandLine(null, "setup")}`, 4);
+        return fail("nothing_stored", `${selection.reason} ${storedSession === undefined ? `No Balladeer setup session is stored for ${options.controlPlane} either.` : "The stored setup session was not read because its workspace could not be established for this request."} Run: ${commandLine(null, "setup")}`, 4);
     }
     // One promise, by id: a different question, answered over the same connection
     // and on its own. Somebody who pasted the repair line wants what the failing
@@ -150,9 +158,13 @@ async function reportBalladeer(options) {
     let reported = false;
     if (selection.kind === "agent") {
         reported = await reportThisRepository(options, selection.agent, emit, say);
+        // A revoked or mismatched repository connection must not become a
+        // successful repository report through a different credential.
+        if (!reported && repositoryScoped)
+            return 4;
     }
     if (session === undefined) {
-        sayWorkspaceUnavailable(emit, say, "no_stored_setup_session", noSessionSentence(options.controlPlane));
+        missingWorkspace();
         return reported ? 0 : 4;
     }
     return reportWorkspace(options, session, here, emit, say, reported);
@@ -167,6 +179,7 @@ async function reportBalladeer(options) {
  */
 async function reportThisRepository(options, agent, emit, say) {
     const call = await callAgentTool(agent, "get_promise_setup", {});
+    reportAgentEnforcementWarning(call, options);
     if (call.kind !== "result") {
         say(`This repository could not be read over its Balladeer agent connection: ${reason(call)}`);
         return false;
@@ -277,6 +290,7 @@ async function reportStaleMarkers(options, agent, emit, say) {
  */
 async function reportOnePromise(options, promiseId, agent, emit, say) {
     const call = await callAgentTool(agent, "get_promise", { promiseId });
+    reportAgentEnforcementWarning(call, options);
     if (call.kind !== "result") {
         const message = `${promiseId} could not be read over this repository's Balladeer agent connection: ${reason(call)}`;
         emit({ step: "promise", status: "unreadable", promiseId, message });
@@ -409,7 +423,7 @@ async function reportSealedPaths(options, emit, say) {
         say(`    ${promise.sealedPath}${promise.title === undefined ? "" : `  ${promise.title}`}`);
     if (sealed.length > shown.length)
         say(`    and ${sealed.length - shown.length} more, not listed here.`);
-    say("  Run `balladeer check-seals` before you push to find out whether your change broke one.");
+    say(`  Run \`${CLI_INVOCATION} check-seals\` before you push to find out whether your change broke one.`);
 }
 function reason(call) {
     switch (call.kind) {
@@ -476,6 +490,15 @@ async function reportWorkspace(options, session, here, emit, say, alreadyReporte
         }
         return failOutside(options, emit, code, "Balladeer could not report this workspace.", 5);
     }
+    if (state?.workspace?.id !== session.workspaceId) {
+        sayWorkspaceUnavailable(emit, say, "setup_workspace_mismatch", "The setup session answered for a different workspace, so none of its workspace context was reported.");
+        return alreadyReported ? 0 : 4;
+    }
+    const scopedReviewLink = (url) => {
+        const scoped = new URL(url);
+        scoped.searchParams.set("workspaceId", state.workspace.id);
+        return scoped.toString();
+    };
     const active = state.repositories.filter((repository) => repository.status === "active");
     emit({
         step: "receipt",
@@ -525,10 +548,10 @@ async function reportWorkspace(options, session, here, emit, say, alreadyReporte
         // awaiting them, and a rejected proposal is listed nowhere at all.
         say(`  Promises: ${repository.promiseCount} agreed, ${repository.candidateCount} proposed and awaiting a person.`);
         if (repository.firstPromiseId !== null) {
-            say(`  First promise: ${options.controlPlane}/promises/${repository.firstPromiseId}`);
+            say(`  First promise: ${scopedReviewLink(reviewLink(options.controlPlane, `promises/${encodeURIComponent(repository.firstPromiseId)}`))}`);
         }
         if (repository.latestCandidateId !== null) {
-            say(`  Newest proposal: ${proposalReviewLink(options.controlPlane, repository.latestCandidateId)}`);
+            say(`  Newest proposal: ${scopedReviewLink(proposalReviewLink(options.controlPlane, repository.latestCandidateId))}`);
         }
     }
     return 0;

package/dist/commands/touch-map.js

@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { runCommand } from "../gh.js";
 import { repositoryRoot } from "../git.js";
 import { CONTINUITY_DIRECTORY, TOUCH_MAP_FILE, buildTouchMap, executedPaths, mappablePath, measurableWithNode, readCoverageDirectory, readLocalPackages, repositoryPath, serializeTouchMap, touchMapBody, touchMapEnvironment, verifierCwd, verifierDigest, } from "../touch-map.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 /** A verifier gets this long before the measurement gives up on it. */
 const DEFAULT_TIMEOUT_MS = 120_000;
 /** However long a package asks for, no verifier holds this command longer. */
@@ -214,7 +214,7 @@ export async function runTouchMap(options) {
             say(`  and ${map.unmapped.length - NAMED_LIMIT} more, not listed here.`);
     }
     say("");
-    say("Ask it which promises a change touches with: balladeer affected <paths...>");
+    say(`Ask it which promises a change touches with: ${CLI_INVOCATION} affected <paths...>`);
     return 0;
 }
 /**