balladeer 1.0.0 → 1.0.1

package/README.md

@@ -19,11 +19,12 @@ The agent reads the setup instructions, runs the command, and hands you the two
 do. To run it yourself instead:
 
 ```sh
-npx balladeer@1.0.0 setup
+npx -y balladeer@latest setup
 ```
 
-Pin the version, every time. Never use an unpinned or `@latest` form. The bare name resolves to an
-unrelated package that installs a different program.
+Use `@latest` so a new session picks up the current command. Balladeer tells an older command when
+an update is available. Run `balladeer setup --refresh` to update an existing repository connection
+and its instructions without replacing other tools' settings.
 
 Run it inside the repository you want to protect. It prints the boundary explanation below, then one
 step at a time, and it exits within seconds rather than blocking on anything.
@@ -107,20 +108,22 @@ your own branch protection.
 
 ## Commands
 
-| Command                  | What it does                                                                   |
-| ------------------------ | ------------------------------------------------------------------------------ |
-| `balladeer setup`        | Run all five steps, then report what a person still has to do                  |
-| `balladeer repositories` | List what this machine could add, marking the one you are in and the ones in   |
-| `balladeer invite`       | Invite teammates by email, and say per address whether the email went          |
-| `balladeer status`       | Report this repository over its agent connection, and the workspace            |
-| `balladeer status <id>`  | Report one promise: whether it is holding, and if not, what the run reported   |
-| `balladeer propose`      | Propose one promise from a proposal file, over that connection                 |
-| `balladeer discover`     | File a whole catalog, up to ten promises from one file, behind one review link |
-| `balladeer touch-map`    | Record which files each promise's verifier runs, on this machine only          |
-| `balladeer affected`     | Say which promises the files you name touch, out of that record                |
-| `balladeer mcp`          | Forward one MCP session over stdio using this repository's connection          |
-| `balladeer explain`      | What Balladeer can and cannot see, where to watch it, and what leaving costs   |
-| `balladeer whoami`       | Report the stored session's workspace, role, scopes, and expiry                |
+| Command                  | What it does                                                                     |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| `balladeer setup`        | Run all five steps, then report what a person still has to do                    |
+| `balladeer repositories` | List what this machine could add, marking the one you are in and the ones in     |
+| `balladeer invite`       | Invite teammates by email, and say per address whether the email went            |
+| `balladeer status`       | Report this repository over its agent connection, and the workspace              |
+| `balladeer status <id>`  | Report one promise: whether it is holding, and if not, what the run reported     |
+| `balladeer prepare <id>` | Prepare a promise's one-time qualification setup, and write it where CI reads it |
+| `balladeer propose`      | Propose one promise from a proposal file, over that connection                   |
+| `balladeer discover`     | File a whole catalog, up to ten promises from one file, behind one review link   |
+| `balladeer touch-map`    | Record which files each promise's verifier runs, on this machine only            |
+| `balladeer affected`     | Say which promises the files you name touch, out of that record                  |
+| `balladeer session`      | Print the id for this piece of work, and the line to write into the commit       |
+| `balladeer mcp`          | Forward one MCP session over stdio using this repository's connection            |
+| `balladeer explain`      | What Balladeer can and cannot see, where to watch it, and what leaving costs     |
+| `balladeer whoami`       | Report the stored session's workspace, role, scopes, and expiry                  |
 
 `--json` emits one object per step on stdout and nothing else. `--wait` makes `setup` poll for the
 approval instead of exiting; without it the command exits and a later run finishes the pairing.
@@ -148,7 +151,17 @@ once they exist, and what stopping costs: your tests are yours, they keep runnin
 administrator can download everything Balladeer holds at any time.
 
 Exit codes: 0 progress reported truthfully, 2 pairing expired or denied or already claimed, 3 this
-copy is too old for the server, 4 usage or credential store problem, 5 transport or server failure.
+copy is too old for the server, 4 usage or credential store problem, 5 transport or server failure,
+6 an earlier Balladeer is still installed on this machine and nothing was changed.
+
+## An earlier Balladeer on the same machine
+
+A machine that ran the earlier Balladeer still carries it: that client registers an MCP server named
+`balladeer` for the whole machine and installs a session hook of its own, and neither comes off when
+this one goes on. Setup finds it before it writes anything and stops with one instruction. If you
+used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it
+prints, then continue. That uninstall is reversible, it backs up `~/.balladeer`, and it leaves the
+old binary in place. `balladeer setup --force` runs anyway, for whoever has decided to keep both.
 
 ## Revoking
 

package/dist/cli.d.ts

@@ -6,6 +6,14 @@ type Parsed = Readonly<{
     wait: boolean;
     /** Repair the files a previous setup wrote, and do nothing else. */
     refresh: boolean;
+    /** `setup --force`: set up even though an earlier Balladeer is still installed. */
+    force: boolean;
+    /**
+     * `setup --claude-desktop` / `--no-claude-desktop`. Undefined is neither
+     * asked for nor refused, which is the ordinary run: connect the chat client
+     * where it is installed and say nothing where it is not.
+     */
+    claudeDesktop: boolean | undefined;
     repo: string | undefined;
     file: string | undefined;
     repository: string | undefined;
@@ -21,6 +29,12 @@ type Parsed = Readonly<{
     owner: string | undefined;
     /** `check-seals --install-hook`: write the optional pre-push hook. */
     installHook: boolean;
+    /** `session --new`: start a different session even though one is current. */
+    fresh: boolean;
+    /** `session --record`: read the trailer out of HEAD and record that commit. */
+    record: boolean;
+    /** `prepare --again`: mint a replacement packet and invalidate the unspent one. */
+    again: boolean;
     /** `check-seals --runner`: where the pinned runner is, when it has moved. */
     runner: string | undefined;
     createWorkspace: string | undefined;

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runAffected } from "./commands/affected.js";
@@ -7,9 +8,11 @@ import { runDiscover } from "./commands/discover.js";
 import { runExplain } from "./commands/explain.js";
 import { parseRole, runInvite } from "./commands/invite.js";
 import { runMcp } from "./commands/mcp.js";
+import { runPrepare } from "./commands/prepare.js";
 import { runPropose } from "./commands/propose.js";
 import { runRepositories } from "./commands/repositories.js";
 import { CREATE_WORKSPACE_MAX_LENGTH, runSetup } from "./commands/setup.js";
+import { runSession } from "./commands/session.js";
 import { runStatus } from "./commands/status.js";
 import { runTouchMap } from "./commands/touch-map.js";
 import { runWhoami } from "./commands/whoami.js";
@@ -19,7 +22,8 @@ import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
 const USAGE = `balladeer ${CLI_VERSION}
 
   balladeer setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
-                  [--create-workspace <name>] [--refresh]
+                  [--create-workspace <name>] [--refresh] [--force]
+                  [--claude-desktop | --no-claude-desktop]
       Pair this session, add this repository, connect this coding agent and CI,
       and report what a person still has to do. Name --repository more than once
       to add other repositories to the same workspace; each of those is added and
@@ -28,10 +32,18 @@ const USAGE = `balladeer ${CLI_VERSION}
       signs in and creates the workspace themselves; this command never creates
       one.
       --refresh does one thing and talks to nobody: it rewrites this
-      repository's balladeer entry in .mcp.json and its Balladeer instructions
-      block to the current form, leaves every other entry in that file alone,
-      and prints what it changed. Run it when Balladeer says a newer version is
-      available.
+      repository's balladeer entry in .mcp.json, its Balladeer instructions
+      block and its Claude desktop chat entry to the current form, leaves every
+      other entry in those files alone, and prints what it changed. Run it when
+      Balladeer says a newer version is available.
+      --force sets up even though an earlier Balladeer is still installed on
+      this machine. Without it, a run that finds the older client's machine-wide
+      MCP entry or session hook stops and says to remove it first.
+      Claude desktop chat is connected too, under a key named for this
+      repository, wherever the app is installed. --claude-desktop asks for it by
+      name, so a machine with no Claude desktop on it says so instead of
+      skipping quietly; --no-claude-desktop leaves that file alone entirely.
+      Quit and reopen the app afterwards: it reads its configuration at startup.
 
   balladeer repositories [--json] [--control-plane <url>]
       List the repositories this machine's GitHub account can see, marking the
@@ -54,6 +66,19 @@ const USAGE = `balladeer ${CLI_VERSION}
       Propose one promise from a proposal file, over this repository's agent
       connection. A named person still agrees to it.
 
+  balladeer prepare <promise id> [--again] [--repo owner/name] [--repository <uuid>]
+                    [--json] [--control-plane <url>]
+      Prepare the one-time qualification setup for a promise whose meaning is
+      agreed and which nothing is checking yet, and write it to
+      .continuity/qualification/<promise id>.json, which is where the sealed run
+      reads it. No sign-off and no code: agreeing the meaning was the person's
+      act, and building the check that proves it is yours. Then build the
+      verifier, seal it, and push to the default branch; protection starts by
+      itself when that run qualifies. It is one-time, so while nobody has
+      published against the packet already prepared this refuses and says who
+      prepared it and when. --again prepares a replacement and invalidates that
+      earlier packet: a run publishing its identities afterwards is refused.
+
   balladeer discover --file <path> [--repo owner/name] [--repository <uuid>]
                      [--owner <membership id>] [--json]
       Propose a whole discovered catalog, up to ten promises from one file, each
@@ -79,6 +104,16 @@ const USAGE = `balladeer ${CLI_VERSION}
       answer whose verifier has changed since the map was built. It reads one
       local file and contacts nothing.
 
+  balladeer session [--new] [--record] [--repo owner/name] [--repository <uuid>] [--json]
+                    [--control-plane <url>]
+      Print the id for this piece of work, and the one line to write into the
+      commit it produces. Pass the id to every promise read you make, so a check
+      that goes red later can be read back against what Balladeer told you
+      before you started. --new starts a different session; --record reads the
+      Balladeer-Session line out of the commit at HEAD and tells Balladeer which
+      commit this session wrote. Your commit message never leaves this machine:
+      only the session id and the commit SHA are sent.
+
   balladeer explain [--control-plane <url>]
       Print, word for word, what Balladeer can and cannot see, where to watch
       your promises, and what leaving costs.
@@ -95,7 +130,8 @@ const USAGE = `balladeer ${CLI_VERSION}
 
 Exit codes: 0 progress reported truthfully, 2 pairing expired or denied or already
 claimed, 3 this copy is too old for the server, 4 usage or credential store problem,
-5 transport or server failure.
+5 transport or server failure, 6 an earlier Balladeer is still installed on this
+machine and nothing was changed.
 `;
 const SUBCOMMANDS = { agent: ["rotate"] };
 export function parseArguments(argv) {
@@ -111,7 +147,12 @@ export function parseArguments(argv) {
     let json = false;
     let wait = false;
     let refresh = false;
+    let force = false;
+    let claudeDesktop;
     let installHook = false;
+    let fresh = false;
+    let record = false;
+    let again = false;
     let runner;
     let controlPlane;
     let repo;
@@ -147,14 +188,26 @@ export function parseArguments(argv) {
         const inline = rest.length > 0 ? rest.join("=") : undefined;
         if (name === "--json")
             json = true;
+        else if (name === "--again")
+            again = true;
         else if (name === "--install-hook")
             installHook = true;
+        else if (name === "--new")
+            fresh = true;
+        else if (name === "--record")
+            record = true;
         else if (name === "--runner")
             runner = value("--runner", inline);
         else if (name === "--wait")
             wait = true;
         else if (name === "--refresh")
             refresh = true;
+        else if (name === "--force")
+            force = true;
+        else if (name === "--claude-desktop")
+            claudeDesktop = true;
+        else if (name === "--no-claude-desktop")
+            claudeDesktop = false;
         else if (name === "--control-plane")
             controlPlane = value("--control-plane", inline);
         else if (name === "--repo")
@@ -181,8 +234,20 @@ export function parseArguments(argv) {
     // value that lost its flag, and it was refused before this loop learned to
     // collect them, so it is refused here rather than ignored.
     // `affected` is the other one, and the words it takes are paths in the change
-    // in front of the person.
-    if (positional.length > 0 && command !== "invite" && command !== "affected") {
+    // in front of the person. `prepare` and `status` each take exactly one bare
+    // word, the promise id a person copied off a promise page, which is the form
+    // both of those commands are told to people and to agents in.
+    // `--again` invalidates a packet somebody may be halfway through using, so it
+    // belongs to the one command that mints one. Accepted silently elsewhere, it
+    // would read as a general "do it anyway" flag.
+    if (again && command !== "prepare") {
+        throw new StoreError("usage", "--again belongs to prepare: run `balladeer prepare <promise id> --again`.");
+    }
+    if (positional.length > 0 &&
+        command !== "invite" &&
+        command !== "affected" &&
+        command !== "prepare" &&
+        command !== "status") {
         throw new StoreError("usage", `${command} takes no bare arguments: ${positional.join(", ")}.`);
     }
     // `--repository` names one repository everywhere but `setup`, where it names
@@ -195,6 +260,18 @@ export function parseArguments(argv) {
     if (refresh && command !== "setup") {
         throw new StoreError("usage", "--refresh belongs to setup: run `balladeer setup --refresh`.");
     }
+    // `--force` says one thing only: set up alongside an earlier Balladeer. Taken
+    // silently by another command it would read as a general "do it anyway" flag,
+    // which is exactly what nothing else here offers.
+    if (force && command !== "setup") {
+        throw new StoreError("usage", "--force belongs to setup: run `balladeer setup --force`.");
+    }
+    // Connecting a chat client is something setup does, so the flag belongs to
+    // setup. Accepted silently on `status`, it would let somebody believe they had
+    // connected Claude desktop when nothing had written a line.
+    if (claudeDesktop !== undefined && command !== "setup") {
+        throw new StoreError("usage", "--claude-desktop belongs to setup: run `balladeer setup --claude-desktop`.");
+    }
     if (command !== "setup" && repositories.length > 1) {
         throw new StoreError("usage", `${command} acts on one repository. Name --repository once, or run it again for the other.`);
     }
@@ -205,12 +282,17 @@ export function parseArguments(argv) {
         json,
         wait,
         refresh,
+        force,
+        claudeDesktop,
         repo,
         file,
         repository: repositories[0],
         repositories,
         owner,
         installHook,
+        fresh,
+        record,
+        again,
         runner,
         createWorkspace,
         positional,
@@ -248,6 +330,8 @@ async function dispatch(parsed, write) {
                 json: parsed.json,
                 wait: parsed.wait,
                 refresh: parsed.refresh,
+                force: parsed.force,
+                ...(parsed.claudeDesktop === undefined ? {} : { claudeDesktop: parsed.claudeDesktop }),
                 ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
                 repositories: parsed.repositories,
                 ...(parsed.createWorkspace === undefined
@@ -296,6 +380,18 @@ async function dispatch(parsed, write) {
                 cwd: process.cwd(),
                 write,
             });
+        case "session":
+            return runSession({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                record: parsed.record,
+                fresh: parsed.fresh,
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
         case "affected":
             return runAffected({
                 json: parsed.json,
@@ -322,6 +418,26 @@ async function dispatch(parsed, write) {
                 write,
             });
         }
+        case "prepare": {
+            // One id, and one only. Preparing two packets from one line would mint
+            // two one-time identities and write two files, and reporting the first
+            // silently would leave the second promise unprepared with nobody told.
+            if (parsed.positional.length !== 1) {
+                process.stderr.write("prepare reads one promise id: balladeer prepare <promise id> [--again].\n");
+                return 4;
+            }
+            return runPrepare({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                promiseId: parsed.positional[0],
+                again: parsed.again,
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        }
         case "propose":
             return runPropose({
                 controlPlane: parsed.controlPlane,
@@ -384,9 +500,32 @@ async function dispatch(parsed, write) {
             return 4;
     }
 }
+/**
+ * The real file behind a path, following symlinks.
+ *
+ * `npx` and every global install run this program through a
+ * `node_modules/.bin/balladeer` symlink, so `process.argv[1]` is the link and
+ * not the file Node loaded. `resolve` does not follow a link, so comparing
+ * resolved paths made the guard below false for every customer: the process
+ * exited 0 having printed nothing, and only a checkout running
+ * `node dist/cli.js` ever saw the program run at all.
+ *
+ * A path that cannot be read back falls through to the resolved form rather
+ * than throwing, because a guard that decides whether the program runs must
+ * never be the thing that stops it.
+ */
+function programPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
 // Only when this file is the program, so a test may import `main` without the
 // import itself running a command.
 const entry = process.argv[1];
-if (entry !== undefined && fileURLToPath(import.meta.url) === resolve(entry)) {
+if (entry !== undefined && programPath(fileURLToPath(import.meta.url)) === programPath(entry)) {
     process.exitCode = await main(process.argv.slice(2));
 }

package/dist/client.d.ts

@@ -18,7 +18,7 @@ export declare class RefusalError extends Error {
  *
  * Behind a platform proxy a server can resolve a link against the machine it is
  * running on rather than against the address customers use, and the first
- * production `propose` printed exactly that: `https://localhost:8080/candidates/...`
+ * production `propose` printed exactly that: a review link on `localhost:8080`
  * as the place to go and agree. A command that prints such a link is worse than
  * one that prints none, because the person tries it.
  *
@@ -27,6 +27,28 @@ export declare class RefusalError extends Error {
  * here for a server's own link to arrive through.
  */
 export declare function reviewLink(controlPlane: string, path: string): string;
+/**
+ * The one place this command decides where a person reads a proposal.
+ *
+ * Every review address this command prints, in a receipt, in a discovery run,
+ * or in its JSON, is built here, so the address is one edit rather than a hunt
+ * and a printed link cannot fall behind the page it names. It matches the
+ * server's own `proposal-links` helper: the page is `/proposals`, and
+ * the retired address redirects to it permanently, so a link an older copy of
+ * this command already printed still lands on it.
+ */
+export declare function proposalReviewLink(controlPlane: string, proposalId: string): string;
+/** The address the whole waiting inbox is read on. */
+export declare function proposalInboxLink(controlPlane: string): string;
+/**
+ * One link that opens exactly the proposals named, and nothing else.
+ *
+ * The ids travel in the query string because the batch is exactly these
+ * promises: a link to the whole inbox would also open whatever was already
+ * waiting there, and a filter by repository would open a different set
+ * tomorrow.
+ */
+export declare function batchProposalReviewLink(controlPlane: string, proposalIds: readonly string[]): string;
 export type RequestOptions = Readonly<{
     method: "GET" | "POST";
     path: string;

package/dist/client.js

@@ -34,7 +34,7 @@ export class RefusalError extends Error {
  *
  * Behind a platform proxy a server can resolve a link against the machine it is
  * running on rather than against the address customers use, and the first
- * production `propose` printed exactly that: `https://localhost:8080/candidates/...`
+ * production `propose` printed exactly that: a review link on `localhost:8080`
  * as the place to go and agree. A command that prints such a link is worse than
  * one that prints none, because the person tries it.
  *
@@ -45,6 +45,34 @@ export class RefusalError extends Error {
 export function reviewLink(controlPlane, path) {
     return new URL(path, ensureTrailing(controlPlane)).toString();
 }
+/**
+ * The one place this command decides where a person reads a proposal.
+ *
+ * Every review address this command prints, in a receipt, in a discovery run,
+ * or in its JSON, is built here, so the address is one edit rather than a hunt
+ * and a printed link cannot fall behind the page it names. It matches the
+ * server's own `proposal-links` helper: the page is `/proposals`, and
+ * the retired address redirects to it permanently, so a link an older copy of
+ * this command already printed still lands on it.
+ */
+export function proposalReviewLink(controlPlane, proposalId) {
+    return reviewLink(controlPlane, `proposals/${encodeURIComponent(proposalId)}`);
+}
+/** The address the whole waiting inbox is read on. */
+export function proposalInboxLink(controlPlane) {
+    return reviewLink(controlPlane, "proposals");
+}
+/**
+ * One link that opens exactly the proposals named, and nothing else.
+ *
+ * The ids travel in the query string because the batch is exactly these
+ * promises: a link to the whole inbox would also open whatever was already
+ * waiting there, and a filter by repository would open a different set
+ * tomorrow.
+ */
+export function batchProposalReviewLink(controlPlane, proposalIds) {
+    return reviewLink(controlPlane, `proposals/review?ids=${proposalIds.join(",")}`);
+}
 function ensureTrailing(controlPlane) {
     return controlPlane.endsWith("/") ? controlPlane : `${controlPlane}/`;
 }

package/dist/commands/affected.js

@@ -1,5 +1,6 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { TOUCH_MAP_FILE, affectedPaths, readLocalPackages, readTouchMap, verifierDigest, } from "../touch-map.js";
+import { formatInstant } from "../local-time.js";
 import {} from "../wire.js";
 import { promiseRoot } from "./touch-map.js";
 /** How many promises one path lists before the report says how many more. */
@@ -86,7 +87,7 @@ export async function runAffected(options) {
         changed: false,
     });
     if (touched.length === 0) {
-        say(`No promise in this map ran any of those files. The map was built ${reading.map.generatedAt}; a promise sealed since then is not in it.`);
+        say(`No promise in this map ran any of those files. The map was built ${formatInstant(reading.map.generatedAt)}; a promise sealed since then is not in it.`);
         return 0;
     }
     for (const answer of answers) {

package/dist/commands/discover.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { callAgentTool, selectAgent, structuredString } from "../agent.js";
-import { reviewLink } from "../client.js";
+import { batchProposalReviewLink, proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
@@ -140,7 +140,7 @@ function titleOf(request) {
  * different set tomorrow.
  */
 export function batchReviewLink(controlPlane, candidateIds) {
-    return reviewLink(controlPlane, `candidates/review?ids=${candidateIds.join(",")}`);
+    return batchProposalReviewLink(controlPlane, candidateIds);
 }
 /**
  * Failures of the connection rather than of one promise, which is the
@@ -254,7 +254,7 @@ export async function runDiscover(options) {
                 index: index + 1,
                 title,
                 candidateId: outcome.candidateId,
-                reviewUrl: reviewLink(options.controlPlane, `candidates/${outcome.candidateId}`),
+                reviewUrl: proposalReviewLink(options.controlPlane, outcome.candidateId),
             };
             filed.push(entry);
             emit({
@@ -336,6 +336,14 @@ async function proposeOne(agent, request, ownerId) {
         // are not nine equally certain readings, and an owner deciding which to read
         // first is entitled to see which one the agent was least sure of.
         confidence: request.teachBack.confidence,
+        // The gate, on every entry in the file. A discovery run is where an
+        // unfailable promise is easiest to write: nine behaviors read off nine
+        // sources, and any one of them can be a sentence nothing could ever
+        // contradict. The file is refused entry by entry rather than in bulk.
+        wrongOutcome: request.teachBack.wrongOutcome,
+        ...(request.teachBack.leastSure === undefined
+            ? {}
+            : { leastSure: request.teachBack.leastSure }),
     });
     switch (call.kind) {
         case "endpoint_refused":
@@ -387,7 +395,7 @@ async function proposeOne(agent, request, ownerId) {
     if (status !== "pending_review") {
         return {
             ok: false,
-            reason: "candidate_not_pending",
+            reason: "proposal_not_pending",
             message: `Balladeer matched an existing proposal, ${candidateId}, which is ${status ?? "in an unreported state"}. Nothing new was recorded.`,
         };
     }

package/dist/commands/explain.d.ts

@@ -4,7 +4,7 @@
  *
  * The boundary copy describes the product's boundary and is timeless; it names
  * two credentials, a CI workflow, and a check on pull requests. In balladeer
- * 1.0.0 the command reaches none of those, so saying so is the difference
+ * 1.0.1 the command reaches none of those, so saying so is the difference
  * between an explanation and a claim.
  */
 export declare const RELEASE_PREFACE: string;

package/dist/commands/explain.js

@@ -6,7 +6,7 @@ import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "../wire.js";
  *
  * The boundary copy describes the product's boundary and is timeless; it names
  * two credentials, a CI workflow, and a check on pull requests. In balladeer
- * 1.0.0 the command reaches none of those, so saying so is the difference
+ * 1.0.1 the command reaches none of those, so saying so is the difference
  * between an explanation and a claim.
  */
 export const RELEASE_PREFACE = [

package/dist/commands/invite.js

@@ -1,4 +1,5 @@
 import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
+import { formatInstant } from "../local-time.js";
 import { commandLine } from "../release.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
 import {} from "../wire.js";
@@ -127,7 +128,7 @@ async function inviteOne(options, session, email) {
         say(options, `Invited ${answer.email} to ${answer.workspaceName} as ${role}. Balladeer has sent them the email.`);
         say(options, `  They can ${ROLE_MEANINGS[answer.requestedRole]}. They join when they accept, and not before.`);
         if (answer.expiresAt !== null) {
-            say(options, `  The invitation stops working at ${answer.expiresAt}.`);
+            say(options, `  The invitation stops working at ${formatInstant(answer.expiresAt)}.`);
         }
         emit(options, {
             step: "invitation",

package/dist/commands/prepare.d.ts

@@ -0,0 +1,74 @@
+export type PrepareOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    promiseId: string;
+    /** Prepare a replacement, invalidating the packet nobody has spent. */
+    again: boolean;
+    /** The repository whose connection to use, named as `owner/name`. */
+    repo?: string;
+    /** The repository whose connection to use, named by id, as `mcp` takes it. */
+    repository?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+/**
+ * A refusal Balladeer wrote, as this terminal has to say it.
+ *
+ * Two changes and no others. The instants move onto the reader's own clock,
+ * because the server writes UTC and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reached somebody whose clock said two in the
+ * afternoon. And the argument is named the way this command takes it. Every
+ * other word, including what to do next and why, is the server's.
+ */
+export declare function atThisTerminal(text: string): string;
+/**
+ * The six keys the sealed run reads, and nothing else.
+ *
+ * The runner rejects an unknown field outright, so a metadata file that carried
+ * a helpful comment, a timestamp, or the whole packet would fail the customer's
+ * protected run for a reason that had nothing to do with their behavior. This
+ * command therefore writes the packet's own `qualificationMetadata` object and
+ * refuses to write anything it does not recognise.
+ */
+declare const METADATA_KEYS: readonly ["schemaVersion", "workspaceLocator", "receiptId", "revisionId", "bindingId", "workflowDigest"];
+type Metadata = Record<(typeof METADATA_KEYS)[number], string>;
+export declare function readQualificationMetadata(structured: unknown): Readonly<{
+    ok: true;
+    value: Metadata;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Where the file goes, refusing any path that would leave this repository.
+ *
+ * The path comes off the server's answer, and the whole point of this command is
+ * that it writes a file the person did not type. A server that answered with
+ * `../../etc/something` would otherwise have this command write there, so the
+ * resolved path has to stay under the directory the command was run in.
+ */
+export declare function metadataDestination(cwd: string, metadataPath: string): Readonly<{
+    ok: true;
+    path: string;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Prepares the one-time qualification setup for one promise, and writes the file
+ * where the sealed run reads it.
+ *
+ * It runs over this repository's own agent connection, which is what makes it
+ * usable at all: preparing a qualification setup is the agent's job, and the
+ * setup session that paired the machine expires. There is no sign-off here and
+ * no code to paste. Agreeing the meaning was the person's act; building the
+ * check that proves it is this command's caller's.
+ *
+ * The file is written once. A second run while nobody has published against the
+ * first packet is refused, naming who prepared it and when, and `--again` mints
+ * a replacement that invalidates the earlier one on the server as well as
+ * overwriting the file here.
+ */
+export declare function runPrepare(options: PrepareOptions): Promise<number>;
+export {};