balladeer 1.0.0 → 1.0.2

package/dist/commands/setup.js

@@ -2,14 +2,16 @@ 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, request } from "../client.js";
+import { ClientTooOldError, RefusalError, TransportError, proposalReviewLink, reviewLink, request, } from "../client.js";
 import { writeConventions } from "../conventions.js";
-import { DISCOVERY_PLAYBOOK, JOIN_OR_CREATE } from "../copy.js";
-import { readPublicRepositoryFacts, readRepositoryFacts, runCommand, setRepositoryVariable, } from "../gh.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 { DESKTOP_CONFIG_FILE, desktopConfigLocation, desktopServerKey, desktopStdioEntry, mergeDesktopConfig, } from "../desktop-config.js";
 import { selectAgent } from "../agent.js";
-import { CONVENTIONS_VERSION } from "../conventions.js";
+import { findLegacyInstall, legacyMessage } from "../legacy.js";
+import { formatInstant } from "../local-time.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";
@@ -126,7 +128,7 @@ function pairedLines(session) {
         `  This session may: ${session.scopeMeanings.join(", ")}.`,
         ...narrowed,
         `  ${REFUSAL_SENTENCE}`,
-        `  It expires at ${session.expiresAt}. Revoke it any time under Connected sessions in Balladeer.`,
+        `  It expires at ${formatInstant(session.expiresAt)}. Revoke it any time under Connected sessions in Balladeer.`,
     ];
 }
 /**
@@ -147,8 +149,14 @@ function pendingLines(pending, repository, host, waiting, approvalUri) {
         ...opening,
         `  Open: ${approvalUri}`,
         `  The page will show this code: ${pending.userCode}`,
+        // A person who belongs to two workspaces approves into whichever one their
+        // browser is signed into, and twice that was not the one they meant: the
+        // repository was enrolled in the wrong workspace and an agent was connected
+        // there. The page now names the workspace and offers the switch, and this
+        // line is what makes somebody look at it.
+        `  ${APPROVE_IN_THE_RIGHT_WORKSPACE}`,
         `  Sent to Balladeer so far: a random code, the name "${repository}", and the hostname "${host}". Nothing else.`,
-        `  This pairing expires at ${pending.expiresAt}.`,
+        `  This pairing expires at ${formatInstant(pending.expiresAt)}.`,
         "  Approve in the browser, then run this command again to finish.",
         "",
         // Printed on the pairing step and nowhere else, because this is the one
@@ -244,6 +252,16 @@ function namedRepositories(options) {
  * a command that blocks for minutes and the pairing would be lost with it.
  */
 export async function runSetup(options) {
+    // First, before the banner and before either path writes a byte: a machine
+    // that still carries the July client gets one instruction and this run stops.
+    // Refresh is inside the check rather than outside it, because a repair writes
+    // the same two files a first setup writes.
+    const legacy = options.force === true
+        ? undefined
+        : findLegacyInstall(options.environment, options.controlPlane);
+    if (legacy !== undefined) {
+        return fail(options, "legacy_balladeer_present", legacyMessage(legacy), 6);
+    }
     if (options.refresh === true)
         return runRefresh(options);
     const { controlPlane } = options;
@@ -365,7 +383,7 @@ export async function runSetup(options) {
         return reportStartFailure(options, error);
     }
     if (lapsed !== undefined) {
-        say(options, `The earlier code ${lapsed.userCode} expired unapproved at ${lapsed.expiresAt}; here is a new one.`);
+        say(options, `The earlier code ${lapsed.userCode} expired unapproved at ${formatInstant(lapsed.expiresAt)}; here is a new one.`);
         emit(options, {
             step: "pair",
             status: "expired",
@@ -488,7 +506,7 @@ function terminalRefusal(pending, code) {
     const again = "Run this command again to start a new one.";
     if (code === "pairing_expired") {
         return {
-            message: `Pairing ${pending.userCode} expired at ${pending.expiresAt}. ${again}`,
+            message: `Pairing ${pending.userCode} expired at ${formatInstant(pending.expiresAt)}. ${again}`,
             status: "expired",
         };
     }
@@ -519,7 +537,7 @@ async function waitForApproval(options, credentials, pending, pollIntervalSecond
     const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
     const now = options.now ?? (() => new Date());
     const deadline = now().getTime() + MAX_WAIT_MS;
-    say(options, `  Waiting up to ${MAX_WAIT_MS / 60_000} minutes for someone to approve ${pending.userCode} at ${approvalLink(options, pending.verificationUri)}. Press Ctrl+C to stop; the pairing is saved either way, and the code stays approvable until ${pending.expiresAt}.`);
+    say(options, `  Waiting up to ${MAX_WAIT_MS / 60_000} minutes for someone to approve ${pending.userCode} at ${approvalLink(options, pending.verificationUri)}. Press Ctrl+C to stop; the pairing is saved either way, and the code stays approvable until ${formatInstant(pending.expiresAt)}.`);
     let interval = pollIntervalSeconds;
     while (now().getTime() < deadline) {
         await sleep(Math.max(interval, 2) * 1000);
@@ -566,6 +584,7 @@ async function runRemainingSteps(options, credentials, session) {
             return transportFailure(options, error.message);
         return fail(options, "setup_state_unreadable", `Balladeer could not report this workspace's setup: ${refusalSentence(error)}. Nothing was changed.`, 5);
     }
+    await claimGithubLogin(options, session);
     const chosen = chooseRepositories(namedRepositories(options), options.cwd);
     if (chosen.kind === "mismatch") {
         return fail(options, "repository_mismatch", chosen.message, 4);
@@ -586,13 +605,64 @@ 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.
+ *
+ * It sends a login and never a token. `gh` is the person's own tool, already
+ * signed in on their own machine, and the one thing read out of it here is the
+ * name of the account. Balladeer stores that as a claim: nothing checks it,
+ * nothing is granted by it, and the settings page lets the person take it back.
+ *
+ * Every failure is silent to the run and visible in the receipt. No `gh`, no
+ * login, an older control plane that has never heard of this call: setup goes
+ * on. A person cannot be stopped from enrolling a repository because a display
+ * detail could not be recorded.
+ */
+async function claimGithubLogin(options, session) {
+    const login = await ghLogin();
+    if (login === undefined) {
+        emit(options, { step: "github_login", status: "unavailable" });
+        return;
+    }
+    try {
+        const answer = await request(options.controlPlane, {
+            method: "POST",
+            path: "/api/setup/v1/github-login",
+            bearer: session.token,
+            body: { login },
+        });
+        if (answer.claimedLogin === null) {
+            emit(options, { step: "github_login", status: "refused" });
+            return;
+        }
+        say(options, `Signed in to GitHub as ${answer.claimedLogin}. Runs you start will carry your name on the promises they protect. Balladeer holds no GitHub token and has not checked this; clear it any time at ${options.controlPlane}/settings#members.\n`);
+        emit(options, { step: "github_login", status: "claimed", login: answer.claimedLogin });
+    }
+    catch {
+        emit(options, { step: "github_login", status: "refused" });
+    }
+}
 async function readState(options, session) {
     try {
         return await request(options.controlPlane, {
@@ -641,6 +711,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.");
     }
@@ -758,19 +837,67 @@ function blockedRepository(options, role, name, reason, next, publicFacts) {
     emit(options, { step: "repository", status: "blocked", repository: name, reason });
     return { view: undefined };
 }
-/**
- * What the person or the agent does next, for their own host.
- *
- * Two things go wrong here and look identical from the terminal: an agent host
- * that is already running does not pick up a project MCP entry written under it,
- * and a project-scoped server needs the person's approval before its tools
- * appear at all. Neither is a failure, and neither was mentioned anywhere, so a
- * truthful report of a proved connection still ended in a session with no
- * Balladeer tools in it and nobody knowing why.
- *
- * A restart is not part of the happy path. Setup finishes here either way, and
- * the next session loads the entry on its own.
- */
+const NO_DESKTOP = { lines: [], json: undefined };
+function connectClaudeDesktop(options, repositoryId, repositoryName) {
+    if (options.claudeDesktop === false)
+        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
+    // flag is owed the answer, and a person who typed nothing is not owed a line
+    // about an application they never mentioned.
+    const asked = options.claudeDesktop === true;
+    const location = desktopConfigLocation(options.environment);
+    if (location.kind === "unsupported") {
+        return asked
+            ? {
+                lines: [`  ${location.reason}`],
+                json: { status: "unsupported", reason: location.reason },
+            }
+            : NO_DESKTOP;
+    }
+    const key = desktopServerKey(repositoryName, repositoryId);
+    const entry = desktopStdioEntry(repositoryId, options.environment, options.controlPlane);
+    const merged = mergeDesktopConfig(location, key, entry, repositoryId, options.controlPlane);
+    if (merged.kind === "absent") {
+        return asked
+            ? { lines: [`  ${merged.reason}`], json: { status: "absent", reason: merged.reason } }
+            : NO_DESKTOP;
+    }
+    if (merged.kind === "refused") {
+        return {
+            lines: [
+                `  ${merged.reason}`,
+                "  Merge this block into it yourself:",
+                ...merged.block.split("\n").map((line) => `    ${line}`),
+            ],
+            json: { status: "refused", reason: merged.reason },
+        };
+    }
+    // `unknown/unknown` is what the origin parse answers when it read nothing, and
+    // reading it back at somebody as though it were a repository name is worse
+    // than not naming the repository at all.
+    const named = repositoryName === "unknown/unknown" || repositoryName.length === 0
+        ? "this repository"
+        : repositoryName;
+    return {
+        lines: merged.changed
+            ? [
+                `  Also connected Claude desktop chat for ${named}, as ${merged.key} in ${merged.path}. Every other server in that file is untouched and this one carries no credential.`,
+                // Said only where something changed. Telling somebody to restart an
+                // application over a file nothing wrote to is noise, and noise is how
+                // the line that does matter stops being read.
+                `  Quit Claude desktop completely and open it again: it reads ${DESKTOP_CONFIG_FILE} at startup, so an app that is already running will not see this.`,
+            ]
+            : [
+                `  Claude desktop chat already runs the current command for ${named} as ${merged.key}; I left ${merged.path} alone.`,
+            ],
+        json: {
+            status: merged.changed ? "connected" : "current",
+            key: merged.key,
+            path: merged.path,
+        },
+    };
+}
 function hostNextSteps() {
     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.`,
@@ -801,7 +928,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 = mergeMcpConfig(root, stdioEntry(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);
+        }
+    }
+    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 ${MCP_CONFIG_FILE} 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 ${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.`);
+            }
+        }
+    }
+    for (const line of configured.desktop.lines)
+        say(options, line);
+    for (const line of hostNextSteps())
+        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>")}\`; ${MCP_CONFIG_FILE} 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.
@@ -826,15 +1015,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;
     }
@@ -844,7 +1054,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, {
@@ -874,30 +1084,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"
+        ? `, ${MCP_CONFIG_FILE} 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}`
@@ -914,38 +1107,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.`);
-            }
-        }
-    }
-    // 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",
@@ -953,12 +1115,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 } : {}),
+        ...(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;
 }
@@ -970,6 +1135,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
@@ -986,7 +1179,7 @@ async function stepCi(options, session, view, name) {
     if (!upgrading && view.ciConfigured) {
         // "Connected" appears on this branch and nowhere else in the command: it is
         // the one state Balladeer observed rather than recorded.
-        say(options, `Step 4 of 5  CI connected  authenticated run observed at ${view.ciFirstValidatedAt ?? "an earlier run"}`);
+        say(options, `Step 4 of 5  CI connected  authenticated run observed at ${view.ciFirstValidatedAt === null ? "an earlier run" : formatInstant(view.ciFirstValidatedAt)}`);
         emit(options, {
             step: "ci",
             status: "connected",
@@ -1228,7 +1421,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.");
@@ -1241,7 +1434,7 @@ async function stepPromise(options, session, view, published) {
         return;
     }
     if (current.latestCandidateId !== null) {
-        const reviewUrl = `${options.controlPlane}/candidates/${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.");
@@ -1301,10 +1494,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
-        : `${options.controlPlane}/candidates/${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."
@@ -1402,11 +1597,14 @@ async function runRefresh(options) {
     }
     const existing = currentEntry(readMcpConfig(root));
     let stored;
+    let storedName;
     try {
         const credentials = readCredentials(options.environment);
         const selection = selectAgent(credentials.agents, options.controlPlane, undefined, repositoryHint(options.cwd));
-        if (selection.kind === "agent")
+        if (selection.kind === "agent") {
             stored = selection.agent.repositoryId;
+            storedName = selection.agent.repository;
+        }
     }
     catch {
         // A store this machine cannot read is not a reason to refuse the repair:
@@ -1433,6 +1631,12 @@ async function runRefresh(options) {
         say(options, conventions.reason);
         return failRefresh(options, "conventions_refused", conventions.reason);
     }
+    // The third stale thing, repaired by the same command and for the same
+    // reason. A desktop entry naming an interpreter that a node upgrade moved is
+    // a chat client that silently has no Balladeer in it, and nothing on screen
+    // says so. This rewrites it to the interpreter and entry point running right
+    // now, and leaves every other server in that file alone.
+    const desktop = connectClaudeDesktop(options, repositoryId, storedName ?? repositoryHint(options.cwd));
     const files = [];
     if (merged.changed)
         files.push(MCP_CONFIG_FILE);
@@ -1446,21 +1650,27 @@ async function runRefresh(options) {
             ? ""
             : ` (it was v${conventions.previousVersion})`}. Everything outside the markers is untouched.`
         : `${conventions.file} already carries conventions v${conventions.version}; I left it alone.`);
-    if (files.length === 0) {
+    // Said before the closing line, because it names a file outside the working
+    // tree and the closing line is about what to commit. The desktop entry is
+    // 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 (files.length === 0 && desktop.json?.status !== "connected") {
         say(options, "Nothing to change: this repository is already on the current form.");
     }
-    else {
+    else if (files.length > 0) {
         say(options, `Commit ${files.join(" and ")} when you are ready.`);
     }
     emit(options, {
         step: "refresh",
-        status: files.length === 0 ? "current" : "updated",
+        status: files.length === 0 && desktop.json?.status !== "connected" ? "current" : "updated",
         repositoryId,
         files,
         conventionsVersion: conventions.version,
         ...(conventions.previousVersion === undefined
             ? {}
             : { previousConventionsVersion: conventions.previousVersion }),
+        ...(desktop.json === undefined ? {} : { claudeDesktop: desktop.json }),
     });
     return 0;
 }

package/dist/commands/status.d.ts

@@ -18,6 +18,22 @@ export type StatusOptions = Readonly<{
     cwd: string;
     write: (text: string) => void;
 }>;
+/**
+ * The two postures in which Balladeer is reporting the behavior as holding.
+ *
+ * Named as the small set rather than as "everything that is not broken",
+ * because the states this command actually meets are mostly neither. A promise
+ * whose meaning somebody agreed and nobody has checked, one whose required run
+ * never arrived, one whose newest evidence aged out, and one whose seal no
+ * longer matches all have no failing run behind them, and a reader who takes
+ * the absence of a failing run for a pass has been told the one thing this
+ * product refuses to say. The published contract this mirrors is `NOT_HOLDING`
+ * in `@balladeer/service` and the posture enum in `@balladeer/contracts`; this
+ * command carries its own copy because the published package depends on
+ * neither, and `tests/cli/promise-status-posture.test.ts` fails if the two
+ * drift apart.
+ */
+export declare const HOLDING_POSTURES: ReadonlySet<string>;
 /**
  * What Balladeer looks like right now, read from the server and never from
  * anything this machine remembers.