balladeer 1.0.0 → 1.0.1

package/dist/commands/setup.js

@@ -2,13 +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, 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 { 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";
@@ -126,7 +129,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 +150,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 +253,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 +384,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 +507,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 +538,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 +585,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);
@@ -593,6 +613,44 @@ async function runRemainingSteps(options, credentials, 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, {
@@ -758,19 +816,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.`,
@@ -938,6 +1044,13 @@ async function stepAgent(options, credentials, session, view, name, published) {
             }
         }
     }
+    // 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.
@@ -959,6 +1072,7 @@ async function stepAgent(options, credentials, session, view, name, published) {
             : { 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;
 }
@@ -986,7 +1100,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",
@@ -1241,7 +1355,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);
         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.");
@@ -1304,7 +1418,7 @@ function printReceipts(options, session, state, view) {
     const promiseUrl = promiseId === null ? undefined : `${options.controlPlane}/promises/${promiseId}`;
     const reviewUrl = promiseId !== null || candidateId === null
         ? undefined
-        : `${options.controlPlane}/candidates/${candidateId}`;
+        : proposalReviewLink(options.controlPlane, candidateId);
     const promiseLink = promiseUrl ?? reviewUrl;
     const promiseSentence = promiseId !== null
         ? "Agreed. A named person agreed to this repository's first promise."
@@ -1402,11 +1516,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 +1550,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 +1569,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.

package/dist/commands/status.js

@@ -1,7 +1,8 @@
 import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
-import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
+import { ClientTooOldError, RefusalError, TransportError, proposalReviewLink, request, } from "../client.js";
 import { repositoryRoot } from "../git.js";
 import { MARKER_OBSERVATION_LIMITS, observeMissingMarkers, staleMarkerRow, } from "../markers.js";
+import { formatInstant } from "../local-time.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { SEALED_PATHS_SHOWN, sealedPromises } from "../seals.js";
@@ -13,6 +14,39 @@ import {} from "../wire.js";
  * `session_expired` pairs again and still holds nothing.
  */
 const NO_CREDENTIAL_HERE = "no_agent_credential_on_this_machine";
+/**
+ * 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 const HOLDING_POSTURES = new Set(["protected", "qualifying"]);
+/**
+ * Why a promise with no failing run behind it is still not holding.
+ *
+ * Two spellings of the broken seal, deliberately. `seal_broken` is what a read
+ * answers with; `custody_invalid` is what a Balladeer running behind this copy
+ * of the command still answers with, and a person talking to one of those is
+ * owed the sentence rather than the fallback.
+ */
+const POSTURE_REASONS = {
+    unknown: "No result could be trusted to say whether this holds.",
+    stale: "The bound verifier no longer matches the agreed meaning.",
+    seal_broken: "The last result could not be tied to the workflow this repository enrolled.",
+    custody_invalid: "The last result could not be tied to the workflow this repository enrolled.",
+    retired: "This promise was retired, and nothing checks it.",
+};
+/** What a posture this copy does not recognise says, rather than a green word. */
+const UNREPORTED_POSTURE = "Balladeer is not reporting this behavior as holding, and this copy of the command does not recognise the state it is in.";
 function noSessionSentence(controlPlane) {
     return `Every repository in the workspace is read over a setup session, and none is stored for ${controlPlane}. Run \`${commandLine(null, "setup")}\` to read the whole workspace.`;
 }
@@ -252,7 +286,7 @@ async function reportOnePromise(options, promiseId, agent, emit, say) {
     const structured = call.structured;
     if (structured.found === false) {
         const message = structuredString(call.structured, "reason") ??
-            `No current approved promise with the id ${promiseId} is available to this repository.`;
+            `No promise with the id ${promiseId} has meaning a named person has agreed in this repository, so there is nothing to read. Check the id with the person who gave it to you, or read what this repository has promised with list_promises.`;
         emit({ step: "promise", status: "unreadable", promiseId, message });
         say(message);
         return 4;
@@ -270,11 +304,35 @@ async function reportOnePromise(options, promiseId, agent, emit, say) {
         ...(promiseUrl === undefined ? {} : { promiseUrl }),
     };
     if (threat === undefined) {
-        emit({ step: "promise", status: "holding", ...named });
+        // Holding is read off the posture, never off the absence of a failing run.
+        // A promise nobody has built a check for has no failing run, and so does a
+        // promise whose required run never arrived, and answering "holding" to
+        // either one is the thing this product exists to refuse: agreed-but-
+        // unprotected meaning is context, and evidence that could not decide is
+        // Unknown. Both are green words away from anything green.
+        const holding = posture !== undefined && HOLDING_POSTURES.has(posture);
+        emit({ step: "promise", status: holding ? "holding" : "not_holding", ...named });
         say(`${title ?? promiseId} (${promiseId})`);
         if (posture !== undefined)
             say(`  Balladeer reports this promise as ${posture}.`);
-        say("  Nothing is reported broken here, so there is nothing to repair.");
+        // Agreed and nothing checking it is not a fault, so it is not reported as
+        // one. It is the one state where there is something to build, and the line
+        // that says what to run is the difference between a person reading
+        // "unqualified" and a person finishing the job.
+        if (posture === "unqualified") {
+            say("  Nobody has built a check for this promise yet, so nothing is proving it.");
+            say(`  Prepare its qualification setup with: ${commandLine(null, "prepare")} ${promiseId}`);
+        }
+        else if (holding) {
+            say("  Nothing is reported broken here, so there is nothing to repair.");
+        }
+        else {
+            // No run to read back, so none of the repair facts exist. What the person
+            // gets instead is why this is not holding and the page that carries the
+            // rest, rather than a sentence telling them nothing is wrong.
+            say(`  ${POSTURE_REASONS[posture ?? ""] ?? UNREPORTED_POSTURE}`);
+            say("  No run is recorded against it here, so there is nothing to read back yet.");
+        }
         if (promiseUrl !== undefined)
             say(`  Promise page: ${promiseUrl}`);
         return 0;
@@ -310,7 +368,7 @@ async function reportOnePromise(options, promiseId, agent, emit, say) {
     if (caseNote !== undefined)
         say(`  ${caseNote}`);
     if (observedAt !== undefined)
-        say(`  Observed: ${observedAt}`);
+        say(`  Observed: ${formatInstant(observedAt)}`);
     if (ownerName !== undefined)
         say(`  Owner: ${ownerName}`);
     if (promiseUrl !== undefined)
@@ -456,7 +514,9 @@ async function reportWorkspace(options, session, here, emit, say, alreadyReporte
         say(`  Default branch: ${repository.defaultBranch}`);
         say(`  Agent: ${repository.agentConfigured ? "connected" : "not connected"}`);
         say(`  CI: ${repository.ciConfigured
-            ? `connected, ${repository.ciValidatedRunCount} authenticated run${repository.ciValidatedRunCount === 1 ? "" : "s"}, first observed ${repository.ciFirstValidatedAt ?? "at an earlier run"}`
+            ? `connected, ${repository.ciValidatedRunCount} authenticated run${repository.ciValidatedRunCount === 1 ? "" : "s"}, first observed ${repository.ciFirstValidatedAt === null
+                ? "at an earlier run"
+                : formatInstant(repository.ciFirstValidatedAt)}`
             : repository.ciIdentityRecorded
                 ? "identity recorded, waiting for the first authenticated run"
                 : "not recorded"}`);
@@ -468,7 +528,7 @@ async function reportWorkspace(options, session, here, emit, say, alreadyReporte
             say(`  First promise: ${options.controlPlane}/promises/${repository.firstPromiseId}`);
         }
         if (repository.latestCandidateId !== null) {
-            say(`  Newest proposal: ${options.controlPlane}/candidates/${repository.latestCandidateId}`);
+            say(`  Newest proposal: ${proposalReviewLink(options.controlPlane, repository.latestCandidateId)}`);
         }
     }
     return 0;

package/dist/commands/whoami.js

@@ -1,5 +1,6 @@
 import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
 import { StoreError, dropSession, findSession, readCredentials, writeCredentials, } from "../store.js";
+import { formatInstant } from "../local-time.js";
 import { commandLine } from "../release.js";
 import {} from "../wire.js";
 function emit(options, step) {
@@ -48,7 +49,7 @@ export async function runWhoami(options) {
                 `Signed in as ${session.membershipDisplayName}, workspace "${session.workspaceName}" (${session.workspaceSlug}).`,
                 `Role: ${session.role}.`,
                 `This session may: ${session.scopeMeanings.join(", ")}.`,
-                `It expires at ${session.expiresAt}.`,
+                `It expires at ${formatInstant(session.expiresAt)}.`,
                 "",
             ].join("\n"));
         }

package/dist/conventions.d.ts

@@ -18,8 +18,16 @@ export declare const CONVENTIONS_END = "<!-- balladeer:conventions:end -->";
 /**
  * The version of the text between the markers. It is written into the block and
  * read back out of it, and nothing about finding the block depends on it.
+ *
+ * It moves when, and only when, `CONVENTIONS_BLOCK` changes. That block is the
+ * stable carrier: it lands in the customer's own instructions file at setup, and
+ * moving it means a pull request against every enrolled repository. Capture
+ * behavior is read every week and ships in `CAPTURE_BEHAVIOR`, which the server
+ * sends at the start of every session and which is versioned by the agent
+ * instructions marker instead. A bump here with no change to the block would
+ * rewrite twelve repositories to say exactly what they already said.
  */
-export declare const CONVENTIONS_VERSION = 10;
+export declare const CONVENTIONS_VERSION = 14;
 export declare function managedByLine(version: number): string;
 /**
  * Which version of the block a file already carries, or nothing when it carries

package/dist/conventions.js

@@ -22,8 +22,16 @@ export const CONVENTIONS_END = "<!-- balladeer:conventions:end -->";
 /**
  * The version of the text between the markers. It is written into the block and
  * read back out of it, and nothing about finding the block depends on it.
+ *
+ * It moves when, and only when, `CONVENTIONS_BLOCK` changes. That block is the
+ * stable carrier: it lands in the customer's own instructions file at setup, and
+ * moving it means a pull request against every enrolled repository. Capture
+ * behavior is read every week and ships in `CAPTURE_BEHAVIOR`, which the server
+ * sends at the start of every session and which is versioned by the agent
+ * instructions marker instead. A bump here with no change to the block would
+ * rewrite twelve repositories to say exactly what they already said.
  */
-export const CONVENTIONS_VERSION = 10;
+export const CONVENTIONS_VERSION = 14;
 /** Both spellings: the stable marker, and the versioned one version 1 wrote. */
 const START_MARKER = /<!-- balladeer:conventions:start(?: v(\d{1,4}))? -->/g;
 const END_MARKER = /<!-- balladeer:conventions:end -->/g;