balladeer 0.0.5 → 1.0.1

package/dist/commands/setup.js

@@ -0,0 +1,1600 @@
+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 { 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 { 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";
+import { CLI_VERSION, DELEGATED_SCOPES, } from "../wire.js";
+import { explainText } from "./explain.js";
+import { probeAgentConnection } from "./mcp.js";
+const REFUSAL_SENTENCE = "It may not agree to what a promise means, agree a change to what a promise means, grant an exception, transfer ownership, supersede, retire, or offboard anything.";
+const MAX_WAIT_MS = 10 * 60 * 1000;
+/** The bound the control plane's own name check holds, refused here so a name
+ * nobody could create never costs a pairing code. */
+export const CREATE_WORKSPACE_MAX_LENGTH = 120;
+const REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+export function chooseRepositories(named, cwd) {
+    const here = repositoryHint(cwd);
+    // `unknown/unknown` is what the origin parse answers when it read nothing, so
+    // it is the absence of a repository rather than a repository with that name.
+    const inCheckoutOf = here === "unknown/unknown" || !REPOSITORY_NAME.test(here) ? undefined : here;
+    if (named.length === 0) {
+        return { kind: "chosen", primary: inCheckoutOf ?? here, also: [] };
+    }
+    if (inCheckoutOf === undefined) {
+        return { kind: "chosen", primary: named[0], also: named.slice(1) };
+    }
+    const match = named.find((name) => name.toLowerCase() === inCheckoutOf.toLowerCase());
+    if (match === undefined) {
+        const list = named.join(", ");
+        return {
+            kind: "mismatch",
+            message: `This run names ${list}, and none of them is ${inCheckoutOf}, which is this directory's origin remote. ` +
+                `Nothing was changed. One named repository has to be the one you are standing in, because connecting a coding agent and CI writes files here and pushes a branch to this remote. ` +
+                `Run this command inside a checkout of ${named[0]}, add ${inCheckoutOf} to the list, or drop the names to set up ${inCheckoutOf}.`,
+        };
+    }
+    return {
+        kind: "chosen",
+        primary: match,
+        also: named.filter((name) => name.toLowerCase() !== inCheckoutOf.toLowerCase()),
+    };
+}
+/**
+ * The approval link, carrying the workspace name this run was given.
+ *
+ * `--create-workspace` creates nothing. A workspace is created by a person who
+ * signs in and clicks Create, and an agent may not do that on anybody's behalf,
+ * so all this flag can honestly do is carry the name the person typed to the
+ * page where that click happens, so they do not type it twice. The parameter is
+ * a pre-fill and the control plane treats it as one.
+ *
+ * A link the server sent that does not parse is printed exactly as it arrived.
+ * Rewriting somebody's address to add a convenience is not worth the chance of
+ * printing an address they cannot open.
+ */
+function approvalLink(options, verificationUri) {
+    const name = options.createWorkspace?.trim();
+    if (name === undefined || name === "")
+        return verificationUri;
+    try {
+        const url = new URL(verificationUri);
+        url.searchParams.set("create", name);
+        return url.toString();
+    }
+    catch {
+        return verificationUri;
+    }
+}
+function newVerifier() {
+    const verifier = randomBytes(32).toString("base64url");
+    return {
+        verifier,
+        digest: `sha256:${createHash("sha256").update(verifier, "utf8").digest("hex")}`,
+    };
+}
+function emit(options, step) {
+    if (options.json)
+        options.write(`${JSON.stringify(step)}\n`);
+}
+function say(options, text) {
+    if (!options.json)
+        options.write(`${text}\n`);
+}
+/**
+ * The one exit every failure takes.
+ *
+ * `--json` is the mode an agent runs in, so a failure has to arrive as an object
+ * it can read rather than as a sentence suppressed by that very flag. The plain
+ * sentence and the object carry the same words, and `changed` answers the
+ * question a caller asks next: does anything need undoing?
+ */
+function fail(options, reason, message, exitCode, changed = false) {
+    say(options, message);
+    emit(options, { step: "error", reason, message, changed, exitCode });
+    return exitCode;
+}
+function storeFailure(options, error) {
+    const reason = error instanceof StoreError ? error.code : "credential_store_unusable";
+    const message = error instanceof StoreError ? error.message : String(error);
+    return fail(options, reason, message, 4);
+}
+function transportFailure(options, message) {
+    return fail(options, "control_plane_unreachable", `Balladeer could not be reached at ${options.controlPlane}: ${message}. Nothing was changed.`, 5);
+}
+function pairedLines(session) {
+    // The boundary copy printed above every run describes the widest approval a
+    // person can give. An approver whose own role is narrower hands over less, and
+    // saying so here is what keeps the two consistent for a contributor.
+    const narrowed = session.scopes.length < DELEGATED_SCOPES.length
+        ? [
+            "  The approver's role granted less than the boundary explanation above describes. This session carries only what is listed here.",
+        ]
+        : [];
+    return [
+        "Step 1 of 5  Paired",
+        `  Signed in as ${session.membershipDisplayName}, workspace "${session.workspaceName}".`,
+        `  This session may: ${session.scopeMeanings.join(", ")}.`,
+        ...narrowed,
+        `  ${REFUSAL_SENTENCE}`,
+        `  It expires at ${formatInstant(session.expiresAt)}. Revoke it any time under Connected sessions in Balladeer.`,
+    ];
+}
+/**
+ * A pairing nobody has collected yet. The opening line is the only difference
+ * between the run that created it and a later run that found it still waiting;
+ * everything under it is the same, so a person re-reading the output does not
+ * have to work out which run they are looking at.
+ *
+ * The link is printed on every run, not only the first. A person whose terminal
+ * scrolled, or an agent whose context was compacted, is told to approve in the
+ * browser, and no other command in this release can produce that URL again.
+ */
+function pendingLines(pending, repository, host, waiting, approvalUri) {
+    const opening = waiting
+        ? ["Step 1 of 5  Waiting for approval", `  Nobody has approved ${pending.userCode} yet.`]
+        : ["Step 1 of 5  Sign in and approve this session"];
+    return [
+        ...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 ${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
+        // moment the answer matters: the person is standing in front of a page that
+        // either joins them to a workspace or makes one, and until now nothing said
+        // so. The bytes are the control plane's `/agent` copy, compared by a test,
+        // so the terminal and the page cannot come to describe it differently.
+        ...JOIN_OR_CREATE.split("\n").map((line) => (line.length === 0 ? "" : `  ${line}`)),
+    ];
+}
+function storeSession(credentials, controlPlane, token, session) {
+    return putSession(dropPendingPairing(credentials, controlPlane), {
+        controlPlane,
+        sessionId: session.sessionId,
+        token,
+        workspaceId: session.workspaceId,
+        workspaceName: session.workspaceName,
+        workspaceSlug: session.workspaceSlug,
+        ...(session.membershipId === undefined ? {} : { membershipId: session.membershipId }),
+        membershipDisplayName: session.membershipDisplayName,
+        scopes: session.scopes,
+        expiresAt: session.expiresAt,
+    });
+}
+function reportPaired(options, session) {
+    for (const line of pairedLines(session))
+        say(options, line);
+    emit(options, {
+        step: "pair",
+        status: "paired",
+        expiresAt: session.expiresAt,
+        workspace: {
+            id: session.workspaceId,
+            name: session.workspaceName,
+            slug: session.workspaceSlug,
+        },
+        scopes: session.scopes,
+    });
+}
+/**
+ * The receipt for a run that never got past pairing. There is nothing to report
+ * about repositories, an agent, CI, or a promise, so it says exactly that rather
+ * than printing four empty rows.
+ */
+function pairingOnlyReceipt(options, sentence) {
+    emit(options, {
+        step: "receipt",
+        setup: { complete: false, sentence },
+        firstPromise: {
+            complete: false,
+            sentence: "Not yet. Nothing has been proposed, because this session is not paired.",
+        },
+        protection: { complete: false, sentence: "Not yet." },
+        connection: {
+            complete: false,
+            sentence: "Not yet. No agent connection has been issued here, so nothing this run leaves behind outlives the setup session.",
+        },
+        repositories: [],
+    });
+    if (options.json)
+        return;
+    options.write("\n");
+    options.write(`Setup receipt          ${sentence}\n`);
+    options.write("First-promise receipt  Not yet. Nothing has been proposed, because this session is not paired.\n");
+    options.write("Protection receipt     Not yet.\n");
+    options.write("Connection receipt     Not yet. No agent connection has been issued here, so nothing this run leaves behind outlives the setup session.\n");
+}
+/**
+ * Every repository this run was told about, however it was told.
+ *
+ * `repo` is the single name the flag has always taken and the shape the tests
+ * and every existing caller pass; `repositories` is the list a caller building
+ * a whole team's workspace passes. They are the same instruction, so they are
+ * read as one list rather than as two features that could disagree.
+ */
+function namedRepositories(options) {
+    const named = [
+        ...(options.repositories ?? []),
+        ...(options.repo === undefined ? [] : [options.repo]),
+    ];
+    const seen = new Set();
+    return named.filter((name) => {
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * One run. It prints what it found, does what it can, and exits within seconds.
+ * Waiting is the person's choice, behind `--wait`, because an agent shell kills
+ * 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;
+    const now = options.now ?? (() => new Date());
+    say(options, `Balladeer setup, version ${CLI_VERSION}.\n`);
+    emit(options, { step: "explain", version: CLI_VERSION });
+    say(options, explainText(controlPlane));
+    const chosen = chooseRepositories(namedRepositories(options), options.cwd);
+    if (chosen.kind === "mismatch") {
+        return fail(options, "repository_mismatch", chosen.message, 4);
+    }
+    // Before the pairing is started, not after: a name the control plane would
+    // refuse must cost nobody a code they then have to abandon, and this run has
+    // sent nothing yet.
+    const carriedName = options.createWorkspace?.trim() ?? "";
+    if (options.createWorkspace !== undefined &&
+        (carriedName.length === 0 || carriedName.length > CREATE_WORKSPACE_MAX_LENGTH)) {
+        return fail(options, "workspace_name_invalid", `--create-workspace needs a workspace name of 1 to ${CREATE_WORKSPACE_MAX_LENGTH} characters. Nothing was changed.`, 4);
+    }
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return storeFailure(options, error);
+    }
+    // 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()) {
+        try {
+            const answer = await request(controlPlane, {
+                method: "GET",
+                path: "/api/pair/session",
+                bearer: stored.token,
+            });
+            reportPaired(options, answer.session);
+            return runRemainingSteps(options, credentials, stored);
+        }
+        catch (error) {
+            if (error instanceof ClientTooOldError) {
+                return fail(options, "client_too_old", error.message, 3);
+            }
+            if (error instanceof TransportError) {
+                return transportFailure(options, error.message);
+            }
+            // The session is gone on the server's side; fall through and pair again.
+            credentials = {
+                ...credentials,
+                sessions: credentials.sessions.filter((entry) => entry.controlPlane !== controlPlane),
+            };
+            try {
+                writeCredentials(credentials, options.environment);
+            }
+            catch (writeError) {
+                return storeFailure(options, writeError);
+            }
+        }
+    }
+    const repository = chosen.primary;
+    const host = hostHint();
+    // Filtered by exact origin, so a pending pairing's claim secret is never sent
+    // to a control plane other than the one that issued it.
+    let pending = findPendingPairing(credentials, controlPlane);
+    // A code that ran out is dropped, and remembered until this run has said so.
+    // Replacing it silently is what happened to the founder: the page in front of
+    // him showed one code, the terminal printed another, and nothing on either
+    // said the first one had expired.
+    let lapsed;
+    if (pending && Date.parse(pending.expiresAt) <= now().getTime()) {
+        lapsed = pending;
+        credentials = dropPendingPairing(credentials, controlPlane);
+        pending = undefined;
+    }
+    if (pending) {
+        const outcome = await claimOnce(options, credentials, pending);
+        if (outcome.kind === "claimed") {
+            return runRemainingSteps(options, outcome.credentials, outcome.session);
+        }
+        if (outcome.kind === "failed")
+            return outcome.exitCode;
+        // Printed before the wait as well as instead of it: a run that blocks for ten
+        // minutes without ever naming the link is the run whose person cannot act.
+        for (const line of pendingLines(pending, repository, host, true, approvalLink(options, pending.verificationUri)))
+            say(options, line);
+        emit(options, {
+            step: "pair",
+            status: "pending",
+            userCode: pending.userCode,
+            verificationUri: approvalLink(options, pending.verificationUri),
+            expiresAt: pending.expiresAt,
+        });
+        if (!options.wait) {
+            pairingOnlyReceipt(options, "Nothing yet: this pairing is still waiting for someone to approve it.");
+            return 0;
+        }
+        return waitForApproval(options, credentials, pending, outcome.pollIntervalSeconds);
+    }
+    let started;
+    try {
+        const { verifier, digest } = newVerifier();
+        started = await request(controlPlane, {
+            method: "POST",
+            path: "/api/pair/start",
+            body: { verifierDigest: digest, repositoryHint: repository, hostHint: host },
+        });
+        pending = {
+            controlPlane,
+            pairingId: started.pairingId,
+            userCode: started.userCode,
+            verifier,
+            verificationUri: started.verificationUriComplete,
+            expiresAt: started.expiresAt,
+            startedAt: now().toISOString(),
+        };
+        credentials = putPendingPairing(credentials, pending);
+        writeCredentials(credentials, options.environment);
+    }
+    catch (error) {
+        return reportStartFailure(options, error);
+    }
+    if (lapsed !== undefined) {
+        say(options, `The earlier code ${lapsed.userCode} expired unapproved at ${formatInstant(lapsed.expiresAt)}; here is a new one.`);
+        emit(options, {
+            step: "pair",
+            status: "expired",
+            userCode: lapsed.userCode,
+            expiresAt: lapsed.expiresAt,
+        });
+    }
+    for (const line of pendingLines(pending, repository, host, false, approvalLink(options, pending.verificationUri)))
+        say(options, line);
+    emit(options, {
+        step: "pair",
+        status: "pending",
+        userCode: pending.userCode,
+        verificationUri: approvalLink(options, pending.verificationUri),
+        expiresAt: pending.expiresAt,
+    });
+    if (options.wait) {
+        return waitForApproval(options, credentials, pending, started.pollIntervalSeconds);
+    }
+    pairingOnlyReceipt(options, "Started a pairing and printed the link. Nobody has approved it yet.");
+    return 0;
+}
+function reportStartFailure(options, error) {
+    if (error instanceof ClientTooOldError) {
+        return fail(options, "client_too_old", error.message, 3);
+    }
+    if (error instanceof StoreError) {
+        return storeFailure(options, error);
+    }
+    if (error instanceof TransportError) {
+        return transportFailure(options, error.message);
+    }
+    if (error instanceof RefusalError) {
+        return fail(options, error.code, `Balladeer refused to start a pairing (${error.code}). Nothing was changed.`, 5);
+    }
+    return fail(options, "pairing_start_failed", "Balladeer could not start a pairing. Nothing was changed.", 5);
+}
+/** Exactly one claim attempt, and every refusal turns into one plain sentence. */
+async function claimOnce(options, credentials, pending) {
+    try {
+        const answer = await request(options.controlPlane, {
+            method: "POST",
+            path: "/api/pair/poll",
+            body: { pairingId: pending.pairingId, verifier: pending.verifier },
+        });
+        if (answer.status === "pending") {
+            return { kind: "pending", pollIntervalSeconds: answer.pollIntervalSeconds };
+        }
+        const updated = storeSession(credentials, options.controlPlane, answer.token, answer.session);
+        writeCredentials(updated, options.environment);
+        reportPaired(options, answer.session);
+        const session = findSession(updated, options.controlPlane);
+        if (session === undefined) {
+            return {
+                kind: "failed",
+                exitCode: fail(options, "session_not_stored", "Balladeer paired this session but could not store it.", 4),
+            };
+        }
+        return { kind: "claimed", credentials: updated, session };
+    }
+    catch (error) {
+        if (error instanceof ClientTooOldError) {
+            return { kind: "failed", exitCode: fail(options, "client_too_old", error.message, 3) };
+        }
+        if (error instanceof StoreError) {
+            return { kind: "failed", exitCode: storeFailure(options, error) };
+        }
+        if (error instanceof TransportError) {
+            return { kind: "failed", exitCode: transportFailure(options, error.message) };
+        }
+        if (error instanceof RefusalError) {
+            if (error.code === "poll_too_fast") {
+                return { kind: "pending", pollIntervalSeconds: 5 };
+            }
+            const terminal = terminalRefusal(pending, error.code);
+            if (terminal) {
+                // The stale pairing goes, so the next run starts a clean one rather than
+                // re-claiming something the server has finished with.
+                let changed = false;
+                try {
+                    writeCredentials(dropPendingPairing(credentials, options.controlPlane), options.environment);
+                    changed = true;
+                }
+                catch {
+                    // The refusal has already been reported; a store failure here changes
+                    // nothing about what the person must do next.
+                }
+                if (terminal.status) {
+                    emit(options, {
+                        step: "pair",
+                        status: terminal.status,
+                        userCode: pending.userCode,
+                    });
+                }
+                return {
+                    kind: "failed",
+                    exitCode: fail(options, error.code, terminal.message, 2, changed),
+                };
+            }
+            return {
+                kind: "failed",
+                exitCode: fail(options, error.code, `Balladeer refused this claim (${error.code}). Nothing was changed.`, 5),
+            };
+        }
+        return {
+            kind: "failed",
+            exitCode: fail(options, "pairing_claim_failed", "Balladeer could not complete this pairing. Nothing was changed.", 5),
+        };
+    }
+}
+/**
+ * The sentence names the state that actually happened.
+ *
+ * A verifier mismatch is not a browser denial and a pairing the server has never
+ * heard of did not expire at a time this machine recorded. Both used to be
+ * reported as the wrong event, which is the one thing a person then repeats to
+ * someone else.
+ */
+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 ${formatInstant(pending.expiresAt)}. ${again}`,
+            status: "expired",
+        };
+    }
+    if (code === "pairing_not_found") {
+        return {
+            message: `Balladeer has no pairing ${pending.userCode}. This machine cannot finish it. ${again}`,
+        };
+    }
+    if (code === "pairing_denied") {
+        return {
+            message: `Pairing ${pending.userCode} was denied in the browser. ${again}`,
+            status: "denied",
+        };
+    }
+    if (code === "pairing_verifier_mismatch") {
+        return {
+            message: `Pairing ${pending.userCode} did not accept this machine's claim secret, so this credential store is not the one that started it. Nobody denied it in the browser. ${again}`,
+        };
+    }
+    if (code === "pairing_already_claimed") {
+        return {
+            message: `Pairing ${pending.userCode} was already claimed by another process. ${again}`,
+        };
+    }
+    return undefined;
+}
+async function waitForApproval(options, credentials, pending, pollIntervalSeconds) {
+    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 ${formatInstant(pending.expiresAt)}.`);
+    let interval = pollIntervalSeconds;
+    while (now().getTime() < deadline) {
+        await sleep(Math.max(interval, 2) * 1000);
+        const outcome = await claimOnce(options, credentials, pending);
+        if (outcome.kind === "claimed") {
+            return runRemainingSteps(options, outcome.credentials, outcome.session);
+        }
+        if (outcome.kind === "failed")
+            return outcome.exitCode;
+        interval = outcome.pollIntervalSeconds;
+    }
+    // The pending step object was already emitted before the wait began, so this
+    // is the human line only: the link again, because ten minutes have passed
+    // since the person last saw it.
+    say(options, `  Still waiting for ${pending.userCode}. Approve it at ${approvalLink(options, pending.verificationUri)}, then run this command again to finish.`);
+    pairingOnlyReceipt(options, "Nothing yet: this pairing is still waiting for someone to approve it.");
+    return 0;
+}
+/* ------------------------------------------------------------------------- *
+ * Steps 2 to 5. Each one reads server truth first, does only what is missing,
+ * and reports a state it observed rather than a state it attempted.
+ * ------------------------------------------------------------------------- */
+function refusalSentence(error) {
+    if (error instanceof RefusalError)
+        return `${error.message} (${error.code})`;
+    if (error instanceof TransportError)
+        return error.message;
+    return error instanceof Error ? error.message : String(error);
+}
+async function runRemainingSteps(options, credentials, session) {
+    let state;
+    try {
+        state = await request(options.controlPlane, {
+            method: "GET",
+            path: "/api/setup/v1/state",
+            bearer: session.token,
+        });
+    }
+    catch (error) {
+        if (error instanceof ClientTooOldError) {
+            return fail(options, "client_too_old", error.message, 3);
+        }
+        if (error instanceof TransportError)
+            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);
+    }
+    const name = chosen.primary;
+    // How this deployment says the command is run. It is the server's answer
+    // rather than a literal here, because only the server knows whether the
+    // package has been published, and a sentence naming a registry version that
+    // does not exist is worse than one naming a checkout.
+    const published = state.client.publishedVersion;
+    const step2 = await stepRepository(options, session, state, name);
+    // The rest of the named repositories, added and nothing more, before this run
+    // goes on to the steps that can only touch the tree it is standing in. They
+    // are printed here rather than at the end so a person reads the whole
+    // enrollment in one place.
+    await addAlsoNamed(options, session, state, chosen.also);
+    let view = step2.view;
+    if (view !== undefined) {
+        const step3 = await stepAgent(options, credentials, session, view, name, published);
+        view = step3 ?? view;
+        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;
+}
+/**
+ * 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, {
+            method: "GET",
+            path: "/api/setup/v1/state",
+            bearer: session.token,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ----------------------------- Step 2 ------------------------------------ */
+function byHandLine(controlPlane, name) {
+    return `  By hand: add ${name} at ${controlPlane}/setup`;
+}
+function enrollmentHeadline(role, rest) {
+    return role === "primary" ? `Step 2 of 5  ${rest}` : `Also  ${rest}`;
+}
+async function stepRepository(options, session, state, name, role = "primary") {
+    const existing = state.repositories.find((repository) => repository.status === "active" && repository.displayName.toLowerCase() === name.toLowerCase());
+    if (existing !== undefined) {
+        // The enrollment is real, so nothing below this line may report it as not
+        // added. The one thing that can still be missing is the GitHub owner id: a
+        // repository added through the web page before Balladeer recorded owner ids
+        // holds none, and step 4 refuses without one because Balladeer cannot say
+        // whose signed runs count. This run already reads that id from `gh`, so it
+        // offers it rather than sending the person to a form.
+        const view = existing.githubOwnerId === null
+            ? await backfillOwnerId(options, session, name, existing)
+            : existing;
+        const recorded = existing.githubOwnerId === null ? view.githubOwnerId : null;
+        say(options, enrollmentHeadline(role, `${name} is already added  default branch ${view.defaultBranch}` +
+            (recorded === null ? "" : `  recorded its GitHub owner id ${recorded}`)));
+        if (view.githubOwnerId === null) {
+            say(options, `  Balladeer holds no GitHub owner id for it, so step 4 cannot say whose runs count, and I could not record one from here.`);
+            say(options, `  Next: add it at ${options.controlPlane}/setup, in "Connect your CI", in the field "GitHub account or organization ID".`);
+        }
+        emit(options, {
+            step: "repository",
+            status: "already",
+            repository: name,
+            repositoryId: view.id,
+            defaultBranch: view.defaultBranch,
+            ...(recorded === null ? {} : { githubOwnerIdRecorded: recorded }),
+        });
+        return { view };
+    }
+    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.");
+    }
+    const lookup = await readRepositoryFacts(name);
+    if (lookup.kind === "unavailable") {
+        // The public read is for rendering the by-hand block with real values, and
+        // never for enrolling: an unauthenticated answer proves nothing about who is
+        // asking, and the enrollment is the record that says this workspace speaks
+        // for this repository.
+        const publicFacts = await readPublicRepositoryFacts(name);
+        return blockedRepository(options, role, name, `I could not read this repository's ids: ${lookup.reason}`, lookup.next, publicFacts.kind === "found" ? publicFacts.facts : undefined);
+    }
+    // A courtesy check on this machine, and nothing more. Balladeer holds no
+    // GitHub token, so the server cannot see who controls a repository and does
+    // not pretend to: what the enrollment records is an identity, and the first
+    // authenticated OIDC run from that repository's own CI is what proves it. This
+    // check exists so a person who cannot push finds out here rather than after
+    // opening a pull request they cannot merge.
+    if (!lookup.facts.canWrite) {
+        return blockedRepository(options, role, name, role === "primary"
+            ? `your GitHub account can read ${name} but cannot push to it, and the later steps push a branch and open a pull request`
+            : `your GitHub account can read ${name} but cannot push to it, and adding it records that this workspace speaks for the repository`, `Ask someone with write access to ${name} to run this command, or add it by hand.`);
+    }
+    try {
+        const answer = await request(options.controlPlane, {
+            method: "POST",
+            path: "/api/setup/v1/repositories",
+            bearer: session.token,
+            body: {
+                repository: name,
+                githubRepositoryId: lookup.facts.githubRepositoryId,
+                githubOwnerId: lookup.facts.githubOwnerId,
+                defaultBranch: lookup.facts.defaultBranch,
+            },
+        });
+        const verb = answer.alreadyEnrolled ? "is already added" : `added to ${session.workspaceName}`;
+        say(options, enrollmentHeadline(role, `${name} ${verb}  default branch ${answer.repository.defaultBranch}`));
+        emit(options, {
+            step: "repository",
+            status: answer.alreadyEnrolled ? "already" : "added",
+            repository: name,
+            repositoryId: answer.repository.id,
+            defaultBranch: answer.repository.defaultBranch,
+        });
+        return { view: answer.repository };
+    }
+    catch (error) {
+        return blockedRepository(options, role, name, `Balladeer refused this repository: ${refusalSentence(error)}`, `Add it by hand at ${options.controlPlane}/setup.`);
+    }
+}
+/**
+ * Every other repository this run was told to add, added and no more.
+ *
+ * A repository named from somewhere that is not a checkout of it can honestly
+ * be enrolled and nothing else: connecting its coding agent writes files into
+ * its working tree, and connecting its CI pushes a branch to its remote. So this
+ * does the one step it can do from here, and says per repository what is still
+ * waiting, rather than reporting a repository as set up because the workspace
+ * has heard of it.
+ *
+ * Each one is independent. A repository the person cannot read, or cannot push
+ * to, refuses on its own line and the rest still go in.
+ */
+async function addAlsoNamed(options, session, state, names) {
+    if (names.length === 0)
+        return;
+    for (const name of names) {
+        const added = await stepRepository(options, session, state, name, "also");
+        if (added.view === undefined)
+            continue;
+        say(options, `  ${name} is in the workspace and nothing else: run this command inside a checkout of it to connect its coding agent and its CI.`);
+    }
+}
+/**
+ * Offers the GitHub owner id for a repository that was added without one.
+ *
+ * The enrollment endpoint is idempotent and reports a repeat rather than
+ * refusing it, so re-sending it is the whole mechanism: the server fills in a
+ * missing owner id from the request and never replaces a recorded one. Every
+ * failure here answers with the repository exactly as it was, because a
+ * repository that is added stays added whatever `gh` or the network did.
+ */
+async function backfillOwnerId(options, session, name, existing) {
+    const lookup = await readRepositoryFacts(name);
+    if (lookup.kind !== "found")
+        return existing;
+    try {
+        const answer = await request(options.controlPlane, {
+            method: "POST",
+            path: "/api/setup/v1/repositories",
+            bearer: session.token,
+            body: {
+                repository: name,
+                githubRepositoryId: lookup.facts.githubRepositoryId,
+                githubOwnerId: lookup.facts.githubOwnerId,
+                defaultBranch: lookup.facts.defaultBranch,
+            },
+        });
+        return answer.repository;
+    }
+    catch {
+        return existing;
+    }
+}
+function blockedRepository(options, role, name, reason, next, publicFacts) {
+    say(options, enrollmentHeadline(role, role === "primary"
+        ? "Add this repository to the workspace  not done"
+        : `Add ${name} to the workspace  not done`));
+    say(options, `  ${reason}.`);
+    say(options, `  Next: ${next}`);
+    say(options, byHandLine(options.controlPlane, name));
+    if (publicFacts !== undefined) {
+        say(options, `  The page asks for these: repository id ${publicFacts.githubRepositoryId}, owner id ${publicFacts.githubOwnerId}, default branch ${publicFacts.defaultBranch}. They are public, and reading them proved nothing about who is asking, which is why I did not add it myself.`);
+    }
+    emit(options, { step: "repository", status: "blocked", repository: name, reason });
+    return { view: undefined };
+}
+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.`,
+        "  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.",
+    ];
+}
+/**
+ * One real call over the connection, through the forwarder's own request path.
+ *
+ * Never a claim assembled from what this command just did. A credential that was
+ * minted, stored, and written into a configuration file is still a credential no
+ * server has been asked to accept, and reporting success from the steps
+ * performed rather than from the state observed is exactly how a broken install
+ * reads as a working one.
+ */
+async function proveAgent(agent) {
+    const probe = await probeAgentConnection(agent);
+    return probe.kind === "answered"
+        ? { kind: "answered" }
+        : { kind: "unproven", reason: probe.reason, nextAction: probe.nextAction };
+}
+/**
+ * Whether this machine already holds a credential for this repository.
+ *
+ * Keyed on the control plane and the repository, exactly as the store keys what
+ * it writes, so a credential for another workspace's repository of the same name
+ * is not mistaken for this one's.
+ */
+function credentialOnThisMachine(agents, controlPlane, repositoryId) {
+    return agents.some((agent) => agent.controlPlane === controlPlane && agent.repositoryId === repositoryId);
+}
+/**
+ * Whose credential this step is about: this machine's.
+ *
+ * The repository being connected is a fact about the repository; holding a
+ * credential is a fact about the machine, and this step used to read the first
+ * and report the second. A repository connected in the browser, where the bearer
+ * is shown once to whoever was there, made this step say "already connected" and
+ * issue nothing, and the machine it said that on ended up with `agents: []` and
+ * with `status` and `propose` both unable to run.
+ *
+ * So the store decides, with the server's answer as the check on it. Where this
+ * machine holds nothing, a connection is issued for it even when the repository
+ * already has others: the service allows a repository many live connections,
+ * authenticates each bearer against its own record, and revokes them one at a
+ * time, so issuing here rotates nothing and takes nothing away from the machine
+ * or the browser that has one already. Rotation is a separate act, refused to a
+ * delegated session, and this step never asks for it. Where the machine holds
+ * one and the server reports no live connection at all, the stored entry is a
+ * revoked credential rather than a working one, and holding it is not being
+ * connected: that issues too.
+ */
+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");
+        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.`);
+        emit(options, {
+            step: "agent",
+            status: "already",
+            repositoryId: view.id,
+            storedHere: true,
+            ...(view.agentConnectionId === null ? {} : { connectionId: view.agentConnectionId }),
+        });
+        return undefined;
+    }
+    // The repository already has one, issued somewhere else. It stays exactly as it
+    // is; what this run adds is a second live connection, for here.
+    const connectedElsewhere = view.agentConfigured;
+    // 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;
+    let packet;
+    try {
+        packet = await request(options.controlPlane, {
+            method: "POST",
+            path: `/api/setup/v1/repositories/${view.id}/agent`,
+            bearer: session.token,
+            body: { label: `${session.workspaceName.slice(0, 100)} planning agent` },
+        });
+    }
+    catch (error) {
+        return blockedAgent(options, view, `Balladeer refused to issue a connection: ${refusalSentence(error)}`);
+    }
+    const agent = {
+        controlPlane: options.controlPlane,
+        workspaceId: session.workspaceId,
+        repositoryId: packet.repositoryId,
+        repository: name,
+        connectionId: packet.connectionId,
+        mcpUrl: packet.mcpUrl,
+        token: packet.token,
+    };
+    // The bearer goes to the developer's own credential store, mode 600 inside a
+    // 0700 directory, and never into the repository or into a config file.
+    try {
+        writeCredentials(putAgent(credentials, agent), options.environment);
+    }
+    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);
+        }
+    }
+    // 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`
+        : "";
+    say(options, proof.kind === "answered"
+        ? `Step 3 of 5  Connected this coding agent on this machine  credential stored in ${credentialsPath(options.environment)}${wrote}`
+        : `Step 3 of 5  Issued this coding agent's connection  not yet proven${wrote}`);
+    say(options, connectedElsewhere
+        ? `  Already connected elsewhere; issued a credential for this machine. ${name} had a live connection issued somewhere else, and this machine held none. That one is untouched: a repository's connections coexist, and each is revoked on its own.`
+        : revokedHere
+            ? `  The credential this machine held is not a live connection for ${name} any more, so this issued a new one for this machine and replaced the stored entry.`
+            : `  This credential belongs to this machine. Another machine runs this command there and gets its own; revoking either leaves the other working.`);
+    if (proof.kind === "answered") {
+        say(options, `  Balladeer answered a get_promise_setup call for ${name} over this connection just now, so the credential and the endpoint are proved rather than assumed.`);
+    }
+    else {
+        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.`);
+    }
+    emit(options, {
+        step: "agent",
+        status: proof.kind === "answered" ? "connected" : "unproven",
+        repositoryId: view.id,
+        connectionId: packet.connectionId,
+        storedHere: true,
+        ...(connectedElsewhere ? { alreadyConnectedElsewhere: true } : {}),
+        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 }),
+    });
+    return undefined;
+}
+function blockedAgent(options, view, reason) {
+    say(options, "Step 3 of 5  Connect this coding agent  not done");
+    say(options, `  ${reason}.`);
+    say(options, `  By hand: issue a connection at ${options.controlPlane}/setup`);
+    emit(options, { step: "agent", status: "blocked", repositoryId: view.id, reason });
+    return undefined;
+}
+/* ----------------------------- Step 4 ------------------------------------ */
+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
+    // moves the enrollment onto a newly published release itself, in every
+    // workspace, so the server is never asked to move anything here. What
+    // Balladeer cannot touch is the pinned line in this repository's own workflow
+    // file: until that changes, the repository still runs the release it was
+    // moved off, and this step exists to open the pull request that changes it. A
+    // truthy test rather than a comparison with null, so a deployment that
+    // predates the field is silent here rather than being read as "the pin is
+    // behind".
+    const upgrading = Boolean(view.ciSupersededAttestorReleaseId);
+    let current = view;
+    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 === null ? "an earlier run" : formatInstant(view.ciFirstValidatedAt)}`);
+        emit(options, {
+            step: "ci",
+            status: "connected",
+            repositoryId: view.id,
+            validatedRunCount: view.ciValidatedRunCount,
+            ...(view.ciFirstValidatedAt === null ? {} : { firstValidatedAt: view.ciFirstValidatedAt }),
+        });
+        return undefined;
+    }
+    if (!upgrading) {
+        // Re-asserted on every run until a real run has been observed, not only when
+        // nothing is recorded yet. The server derives every value from the enrollment
+        // and rotates the registration only when they differ, so a repeat is a no-op
+        // when the identity is right and a repair when it is wrong. The first dogfood
+        // run recorded a mangled identity by hand and had no way back but this one.
+        //
+        // Skipped while the pin is behind. The enrollment is already on the release
+        // the deployment publishes, the caller identity is not what is out of date,
+        // and re-recording it would put this repository back through a request whose
+        // whole purpose is the identity rather than the file.
+        try {
+            const answer = await request(options.controlPlane, {
+                method: "POST",
+                path: `/api/setup/v1/repositories/${view.id}/ci`,
+                bearer: session.token,
+                body: { eventClasses: ["push", "pull_request"] },
+            });
+            current = answer.repository;
+        }
+        catch (error) {
+            return blockedCi(options, view, `Balladeer refused to record a CI identity: ${refusalSentence(error)}`);
+        }
+    }
+    let workflow;
+    try {
+        workflow = await request(options.controlPlane, {
+            method: "GET",
+            path: `/api/setup/v1/repositories/${view.id}/caller-workflow`,
+            bearer: session.token,
+        });
+    }
+    catch (error) {
+        return blockedCi(options, current, `Balladeer could not render the workflow: ${refusalSentence(error)}`);
+    }
+    const root = await repositoryRoot(options.cwd);
+    // Two states, one set of words each, so every ending below says the same true
+    // thing about which of them this run is in. A move is never reported as
+    // "connected": the enrollment moved, the repository's own file has not, and
+    // the proof is a run on the new pin that has not happened yet.
+    const headline = upgrading
+        ? `Step 4 of 5  Connect CI  moved to Balladeer release ${workflow.attestorSha}`
+        : "Step 4 of 5  Connect CI  identity recorded, waiting for the first authenticated run";
+    const recorded = upgrading
+        ? { status: "release_upgraded", attestorReleaseSha: workflow.attestorSha }
+        : { status: "identity_recorded" };
+    const proof = upgrading ? "that run, on the new pin, is the proof" : "that run is the proof";
+    // The finished case first. Once the pull request is merged the workflow is on
+    // the default branch and the branch it arrived on is usually deleted, so
+    // looking only for that branch would answer "not done" for a repository where
+    // the work is complete, and the command would go on to tell a person to commit
+    // a file they had already merged.
+    const onDefaultBranch = root === undefined
+        ? undefined
+        : await workflowOnDefaultBranch(root, workflow.defaultBranch, workflow.workflowPath);
+    if (onDefaultBranch === workflow.workflowYaml) {
+        say(options, headline);
+        say(options, `  ${workflow.workflowPath} is already on ${workflow.defaultBranch}, so there is nothing to commit. GitHub runs it there; ${proof}.`);
+        say(options, "  Next: run this command again in a minute to see the run.");
+        emit(options, {
+            step: "ci",
+            ...recorded,
+            repositoryId: current.id,
+            workflowInstalled: true,
+        });
+        return current;
+    }
+    const alreadyPushed = root === undefined
+        ? false
+        : (await runCommand("git", [
+            "-C",
+            root,
+            "ls-remote",
+            "--exit-code",
+            "--heads",
+            "origin",
+            CI_BRANCH,
+        ])).ok;
+    // A pushed branch is a finished state only while the pin on it is the one
+    // Balladeer now expects. On a move it is the branch that has to change, so the
+    // work below updates it rather than reporting it as already done.
+    if (alreadyPushed && !upgrading) {
+        say(options, headline);
+        say(options, `  The ${CI_BRANCH} branch is already pushed. GitHub runs the workflow on its pull request; ${proof}.`);
+        say(options, "  Next: run this command again in a minute to see the run.");
+        emit(options, { step: "ci", ...recorded, repositoryId: current.id });
+        return current;
+    }
+    for (const variable of workflow.variables) {
+        const set = await setRepositoryVariable(name, variable.name, variable.value);
+        if (!set.ok) {
+            return ciFallback(options, current, workflow, name, set.stderr || "gh could not set a repository variable");
+        }
+    }
+    if (root === undefined) {
+        return ciFallback(options, current, workflow, name, "this directory is not a git work tree");
+    }
+    const bodyPath = join(mkdtempSync(join(tmpdir(), "balladeer-pr-")), "body.md");
+    writeFileSync(bodyPath, (upgrading
+        ? [
+            `Moves the pinned Balladeer runner to release ${workflow.attestorSha}.`,
+            "",
+            "Balladeer has already recorded this repository against the new release, and it still",
+            "accepts runs from the release this file pins today, so merging this is an ordinary change",
+            "rather than a cutover. The run GitHub makes on the new pin is what proves the move landed.",
+            "",
+            "The check is advisory on Balladeer's side. Whether it blocks a merge is this repository's own",
+            "branch protection.",
+            "",
+        ]
+        : [
+            "Adds the Balladeer continuity workflow.",
+            "",
+            "GitHub runs it on this pull request. That authenticated run is what proves the CI connection;",
+            "until Balladeer observes it, the connection is recorded and not connected.",
+            "",
+            "The check is advisory on Balladeer's side. Whether it blocks a merge is this repository's own",
+            "branch protection.",
+            "",
+        ]).join("\n"), "utf8");
+    const opened = await commitWorkflowOnBranch({
+        root,
+        defaultBranch: workflow.defaultBranch,
+        workflowPath: workflow.workflowPath,
+        workflowYaml: workflow.workflowYaml,
+        repository: name,
+        bodyPath,
+        ...(upgrading ? { subject: "Update the Balladeer CI release pin" } : {}),
+    });
+    if (opened.kind === "refused") {
+        return ciFallback(options, current, workflow, name, opened.reason);
+    }
+    if (opened.kind === "unchanged") {
+        say(options, headline);
+        say(options, `  ${workflow.workflowPath} is already what this branch carries, so there was nothing to commit. GitHub runs it; ${proof}.`);
+        say(options, "  Next: run this command again in a minute to see the run.");
+        emit(options, {
+            step: "ci",
+            ...recorded,
+            repositoryId: current.id,
+            workflowInstalled: true,
+        });
+        return current;
+    }
+    say(options, headline);
+    say(options, `  ${opened.kind === "updated" ? "Updated the open pull request" : "Opened a pull request"}${opened.pullRequestUrl ? ` (${opened.pullRequestUrl})` : ""}. GitHub runs the workflow on that pull request; ${proof}.`);
+    say(options, "  Next: run this command again in a minute to see the run.");
+    emit(options, {
+        step: "ci",
+        ...recorded,
+        repositoryId: current.id,
+        ...(opened.pullRequestUrl === undefined ? {} : { pullRequestUrl: opened.pullRequestUrl }),
+    });
+    return current;
+}
+/**
+ * What a person who can actually do it needs, when this machine's `gh` or `git`
+ * could not: every action in order, numbered as a list a person works down, with
+ * the rendered file and both values. The step is reported unfinished and the
+ * command exits 0, because a truthful partial result is not a failure and an
+ * agent that sees a non-zero code stops.
+ */
+function ciFallback(options, view, workflow, name, reason) {
+    say(options, "Step 4 of 5  Connect CI  identity recorded, the repository changes are not done");
+    say(options, `  I could not make the changes in ${name}: ${reason}.`);
+    say(options, "  Someone with write access to the repository does these things, in order:");
+    // Numbered across the whole list rather than inside the loop: two variables
+    // printed as step 1 twice reads as one instruction somebody repeated.
+    let action = 1;
+    for (const variable of workflow.variables) {
+        say(options, `  ${action}. Set the repository variable ${variable.name} to ${variable.value}`);
+        action += 1;
+    }
+    say(options, `  ${action}. Commit this file as ${workflow.workflowPath}:`);
+    for (const line of workflow.workflowYaml.split("\n"))
+        say(options, `     ${line}`);
+    action += 1;
+    say(options, `  ${action}. Open a pull request into ${workflow.defaultBranch}. Its run is the proof.`);
+    emit(options, { step: "ci", status: "blocked", repositoryId: view.id, reason });
+    return view;
+}
+function blockedCi(options, view, reason) {
+    say(options, "Step 4 of 5  Connect CI  not done");
+    say(options, `  ${reason}.`);
+    say(options, `  By hand: connect CI at ${options.controlPlane}/setup`);
+    emit(options, { step: "ci", status: "blocked", repositoryId: view.id, reason });
+    return view;
+}
+/* ----------------------------- Step 5 ------------------------------------ */
+/**
+ * The playbook, printed for the agent that is reading this output, followed by
+ * the one runnable line only the server can name.
+ *
+ * It used to ask for a single behavior, which left the person a shelf with one
+ * thing on it and no way to tell whether Balladeer had understood their
+ * repository. The command still invents no meaning: the agent reads the
+ * repository's own tests, pull requests, documents and reverts, and a named
+ * person agrees to what it wrote.
+ *
+ * The playbook lines are printed unindented and unwrapped, because the very same
+ * bytes are served at the control plane's `/agent` page and a packaging test
+ * compares the two. Anything this function did to them would be drift.
+ */
+function discoveryGuidance(published) {
+    return [
+        ...DISCOVERY_PLAYBOOK.split("\n"),
+        "",
+        `  ${commandLine(published, "discover --file <path>")}`,
+        "",
+        "One promise at a time still works, with the propose subcommand or with the propose tool on the",
+        "Balladeer MCP server you just connected. Both go the same way this one does, over this",
+        "repository's agent connection, which does not expire, so proposing keeps working long after this",
+        "setup session has ended.",
+        "",
+        `  ${commandLine(published, "propose --file <path>")}`,
+    ];
+}
+/**
+ * What this repository's first promise is actually doing, in three states that
+ * cannot be confused for one another: agreed, waiting for a person, or not yet
+ * proposed.
+ *
+ * The distinction is the whole point of the step. An agreed promise reported as
+ * waiting sends the person who just agreed to it back to the browser to agree
+ * again, and a rejected proposal reported as waiting sends them to a record
+ * somebody already refused. The server now counts only what is genuinely
+ * waiting, so the states are read from it rather than inferred.
+ */
+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}`;
+        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.");
+        emit(options, {
+            step: "promise",
+            status: "agreed",
+            promiseId: current.firstPromiseId,
+            promiseUrl,
+        });
+        return;
+    }
+    if (current.latestCandidateId !== null) {
+        const reviewUrl = proposalReviewLink(options.controlPlane, current.latestCandidateId);
+        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.");
+        emit(options, {
+            step: "promise",
+            status: "proposed",
+            candidateId: current.latestCandidateId,
+            reviewUrl,
+        });
+        return;
+    }
+    say(options, "Step 5 of 5  Discover this repository's promises");
+    for (const line of discoveryGuidance(published))
+        say(options, line);
+    emit(options, { step: "promise", status: "none" });
+}
+/* ---------------------------- The receipts ------------------------------- */
+function repositoryLine(view) {
+    return {
+        repository: view.displayName,
+        agent: view.agentConfigured ? "agent connected" : "no agent connection",
+        ci: view.ciConfigured
+            ? `CI connected, ${view.ciValidatedRunCount} authenticated run${view.ciValidatedRunCount === 1 ? "" : "s"}`
+            : view.ciIdentityRecorded
+                ? "CI identity recorded, waiting for the first authenticated run"
+                : "CI not recorded",
+    };
+}
+/**
+ * What this machine holds now, read from the store at receipt time.
+ *
+ * Read again rather than carried down from the start of the run, because step 3
+ * may have written a credential since, and a receipt that reported the state
+ * before its own run would be exactly the stale claim these receipts exist to
+ * prevent. A store this run cannot read is reported as holding nothing, which is
+ * the truthful answer to "can `propose` run here".
+ */
+function credentialHere(options, repositoryId) {
+    try {
+        return readCredentials(options.environment).agents.some((agent) => agent.controlPlane === options.controlPlane && agent.repositoryId === repositoryId);
+    }
+    catch {
+        return false;
+    }
+}
+function printReceipts(options, session, state, view) {
+    const active = state.repositories.filter((repository) => repository.status === "active");
+    const rows = active.map(repositoryLine);
+    const current = view === undefined ? undefined : active.find((item) => item.id === view.id);
+    const setupComplete = current !== undefined && current.agentConfigured && current.ciConfigured;
+    const names = active.map((repository) => repository.displayName).join(", ");
+    const setupSentence = active.length === 0
+        ? `Paired as ${session.membershipDisplayName} in ${state.workspace.name}. No repository is enrolled yet.`
+        : `Paired as ${session.membershipDisplayName} in ${state.workspace.name}. ${active.length} repositor${active.length === 1 ? "y" : "ies"} enrolled: ${names}.`;
+    // Agreed first, waiting second, and nothing proposed last. Reading the two in
+    // the other order is what produced a receipt that asked a person to agree to a
+    // 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 reviewUrl = promiseId !== null || candidateId === null
+        ? undefined
+        : proposalReviewLink(options.controlPlane, candidateId);
+    const promiseLink = promiseUrl ?? reviewUrl;
+    const promiseSentence = promiseId !== null
+        ? "Agreed. A named person agreed to this repository's first promise."
+        : candidateId !== null
+            ? "Proposed, and not yet agreed. A named person agrees to it in the browser."
+            : "Not yet. No promise has been proposed for this repository.";
+    const protectedCount = current?.promiseCount ?? 0;
+    const protectionSentence = protectedCount > 0
+        ? `${protectedCount} promise${protectedCount === 1 ? " stands" : "s stand"} agreed. Protection starts on its own the moment a verifier qualifies, once the verifier pull request has merged.`
+        : "Not yet. Next: a person agrees to the promise, then merge the verifier pull request; protection starts on its own when the verifier qualifies.";
+    // What a person can still do tomorrow, from this machine, which is a different
+    // fact from what was set up today and a different fact again from what the
+    // repository has. The setup session ends; the credential this machine holds
+    // does not, and `propose` and `status` run over that one. A repository
+    // connected from a browser or another laptop leaves this machine with nothing
+    // to run over, so this receipt reads the store rather than the server.
+    const currentName = current?.displayName ?? "This repository";
+    const heldHere = current !== undefined && credentialHere(options, current.id);
+    const connectionSentence = heldHere
+        ? `${currentName} has an agent connection issued for this machine, which does not expire. \`propose\` and \`status\` run over it here, so they keep working after this setup session ends. Each machine holds its own: another one runs setup there to get one.`
+        : current?.agentConfigured === true
+            ? `${currentName} has an agent connection, but not on this machine. \`propose\` and \`status\` run over a credential this machine holds, so run setup here to issue one; the connections already out there are untouched.`
+            : "Not yet. Without an agent credential on this machine, `propose` and `status` have nothing to run over once this setup session ends.";
+    emit(options, {
+        step: "receipt",
+        setup: { complete: setupComplete, sentence: setupSentence },
+        firstPromise: {
+            complete: promiseId !== null,
+            sentence: promiseSentence,
+            ...(reviewUrl === undefined ? {} : { reviewUrl }),
+            ...(promiseUrl === undefined ? {} : { promiseUrl }),
+        },
+        protection: { complete: false, sentence: protectionSentence },
+        connection: { complete: heldHere, sentence: connectionSentence },
+        repositories: rows,
+    });
+    if (options.json)
+        return;
+    options.write("\n");
+    options.write(`Setup receipt          ${setupSentence}\n`);
+    for (const row of rows) {
+        options.write(`                       ${row.repository}: ${row.agent}, ${row.ci}.\n`);
+    }
+    options.write(`First-promise receipt  ${promiseSentence}\n`);
+    if (promiseLink !== undefined)
+        options.write(`                       ${promiseLink}\n`);
+    options.write(`Protection receipt     ${protectionSentence}\n`);
+    options.write(`Connection receipt     ${connectionSentence}\n`);
+    // An offer, and nothing more than an offer. Writing into somebody's
+    // hooks directory uninvited takes over a file they may already be using, and
+    // the first they would know of it is a push that stopped for a reason they
+    // cannot find. So the line names the command and waits to be typed.
+    const published = state.client.publishedVersion;
+    options.write("\n");
+    options.write("Optional  A promise's files are sealed, and an ordinary edit inside one breaks the seal.\n");
+    options.write("          This says so before you push, and says nothing otherwise:\n");
+    options.write(`            ${commandLine(published, "check-seals")}\n`);
+    options.write("          This makes every push from this checkout ask first:\n");
+    options.write(`            ${commandLine(published, "check-seals --install-hook")}\n`);
+    options.write("          Nothing installs that hook for you, and deleting the file it writes removes it.\n");
+}
+/* ---------------------------- setup --refresh ----------------------------- */
+/**
+ * Which invocation this repair writes, decided without asking anybody.
+ *
+ * A repair runs where the stale install is, and the server is not always
+ * reachable from there, so the two honest local sources are how this copy was
+ * itself obtained and what the file already says. A copy running out of a
+ * registry install writes the registry form. A copy running out of a checkout
+ * leaves a registry form alone rather than downgrading a published install to
+ * an absolute path on one person's laptop, and writes the checkout form only
+ * where the file was already a checkout form or had no entry at all.
+ */
+export function refreshPublishedForm(existing) {
+    if (runningFromRegistryInstall())
+        return CLI_VERSION;
+    const command = existing?.command;
+    return command === "npx" ? CLI_VERSION : null;
+}
+/**
+ * `balladeer setup --refresh`: a stale install repairs itself in one command.
+ *
+ * The two files setup writes are the two files that go stale, and they go stale
+ * silently: an `.mcp.json` entry naming a version keeps working, and a
+ * conventions block from three releases ago keeps being read. This rewrites both
+ * to the current form, touches nothing else in either file, and says what it
+ * 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) {
+    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));
+    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") {
+            stored = selection.agent.repositoryId;
+            storedName = selection.agent.repository;
+        }
+    }
+    catch {
+        // A store this machine cannot read is not a reason to refuse the repair:
+        // the entry in the file names the repository too, and that is what is being
+        // rewritten.
+    }
+    // The stored credential first, because it is this machine's own record of
+    // which repository it is connected for; the file second, because a machine
+    // 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.`);
+    }
+    const merged = mergeMcpConfig(root, stdioEntry(repositoryId, refreshPublishedForm(existing)), options.controlPlane);
+    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}`);
+        return failRefresh(options, "mcp_config_refused", merged.reason);
+    }
+    const conventions = writeConventions(root);
+    if (conventions.kind === "refused") {
+        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);
+    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.`);
+    say(options, conventions.changed
+        ? `Rewrote the Balladeer block in ${conventions.file} to conventions v${conventions.version}${conventions.previousVersion === undefined
+            ? ""
+            : ` (it was v${conventions.previousVersion})`}. Everything outside the markers is untouched.`
+        : `${conventions.file} already carries conventions v${conventions.version}; I left it alone.`);
+    // 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 if (files.length > 0) {
+        say(options, `Commit ${files.join(" and ")} when you are ready.`);
+    }
+    emit(options, {
+        step: "refresh",
+        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;
+}
+function failRefresh(options, reason, message) {
+    say(options, message);
+    emit(options, { step: "refresh", status: "blocked", files: [], reason, message });
+    return 4;
+}