balladeer 1.0.0 → 1.0.2

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 `npx -y balladeer@latest 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.
@@ -33,6 +34,12 @@ connects this coding agent, records the CI identity and opens the pull request w
 and hands you the playbook for discovering this repository's own promises. The two things it never
 does are sign you in and agree to a promise; both of those are yours, in a browser.
 
+If you are joining an existing workspace, use `npx -y balladeer@latest setup --existing`. It
+completes browser onboarding without adding a repository or changing CI. When this checkout is
+already enrolled it connects this machine and writes its MCP configuration; when it is absent, setup
+leaves the checkout unchanged and Balladeer shows that enforcement tracking is unavailable until an
+administrator connects a repository.
+
 ## Requirements
 
 - Node 22 or newer. The command has no runtime dependencies at all: it uses Node builtins and
@@ -57,19 +64,20 @@ test output.
 The verify job in your CI runs your tests with your checkout and has no Balladeer credential. A
 separate publish job, with no checkout, sends only those outcomes and hashes.
 
-This setup creates two credentials, both of which you control. Approving in the browser lets this
-session act as you to add repositories, connect your coding agent, connect CI, and propose promises;
-it cannot approve, activate, or remove anything. That session lasts a day, each use buys it another
-day, and it is gone seven days after you approved it however much you used it. The coding agent's
-own connection has no expiry: it lets the agent read the promises your team has approved, propose
-new ones, and propose replacing, retiring, excepting, or reassigning one you already have; every one
-of those waits for a named person to decide it. It can also carry out one of those acts for you, and
-only this way: you open a Balladeer page in your own browser, read what the act is, sign it off
-there, and read back the one-time code that page gives you. That code covers that one act on that
-one thing, once, and Balladeer records you as the person who took it and the connection as the
-messenger. Without a code you signed, the connection cannot approve, activate, grant, transfer,
-retire, or delete anything. You can revoke either one at any time in Balladeer, and the setup
-session also ends on its own.
+Browser approval creates a temporary setup session limited by that person's workspace role. A
+contributor can connect this machine's coding agent to an already-enrolled repository and propose
+promises; an administrator can also add repositories, connect CI, and invite teammates. The session
+cannot approve, activate, rotate, revoke, or remove anything. It lasts a day, each use buys it
+another day, and it is gone seven days after approval however much it was used. When setup connects
+an enrolled repository it also issues that machine a coding-agent credential. That connection has no
+expiry: it lets the agent read the promises your team has approved, propose new ones, and propose
+replacing, retiring, excepting, or reassigning one you already have; every one of those waits for a
+named person to decide it. It can also carry out one of those acts for you, and only this way: you
+open a Balladeer page in your own browser, read what the act is, sign it off there, and read back
+the one-time code that page gives you. That code covers that one act on that one thing, once, and
+Balladeer records you as the person who took it and the connection as the messenger. Without a code
+you signed, the connection cannot approve, activate, grant, transfer, retire, or delete anything.
+You can revoke either one at any time in Balladeer, and the setup session also ends on its own.
 
 Adding the workflow puts a check on pull requests into your default branch. That check is advisory
 on Balladeer's side; whether it blocks a merge is your own branch protection.
@@ -107,20 +115,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                                                                     |
+| -------------------------------------- | -------------------------------------------------------------------------------- |
+| `npx -y balladeer@latest setup`        | Run all five steps, then report what a person still has to do                    |
+| `npx -y balladeer@latest repositories` | List what this machine could add, marking the one you are in and the ones in     |
+| `npx -y balladeer@latest invite`       | Invite teammates by email, and say per address whether the email went            |
+| `npx -y balladeer@latest status`       | Report this repository over its agent connection, and the workspace              |
+| `npx -y balladeer@latest status <id>`  | Report one promise: whether it is holding, and if not, what the run reported     |
+| `npx -y balladeer@latest prepare <id>` | Prepare a promise's one-time qualification setup, and write it where CI reads it |
+| `npx -y balladeer@latest propose`      | Propose one promise from a proposal file, over that connection                   |
+| `npx -y balladeer@latest discover`     | File a whole catalog, up to ten promises from one file, behind one review link   |
+| `npx -y balladeer@latest touch-map`    | Record which files each promise's verifier runs, on this machine only            |
+| `npx -y balladeer@latest affected`     | Say which promises the files you name touch, out of that record                  |
+| `npx -y balladeer@latest session`      | Print the id for this piece of work, and the line to write into the commit       |
+| `npx -y balladeer@latest mcp`          | Forward one MCP session over stdio using this repository's connection            |
+| `npx -y balladeer@latest explain`      | What Balladeer can and cannot see, where to watch it, and what leaving costs     |
+| `npx -y balladeer@latest 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.
@@ -129,7 +139,7 @@ approval instead of exiting; without it the command exits and a later run finish
 to be the one you are standing in, because connecting a coding agent writes files into a working
 tree and connecting CI pushes a branch to a remote. The rest are added to the workspace and nothing
 more, and the run says so for each of them; somebody runs setup in a checkout of each one to finish
-it. `balladeer repositories` is what you read first to decide which ones to name.
+it. `npx -y balladeer@latest repositories` is what you read first to decide which ones to name.
 
 `invite` takes one or more addresses and `--role contributor|viewer|administrator`, defaulting to
 contributor. It goes over the setup session's `workspace:invite` grant, so it works only for a
@@ -148,7 +158,18 @@ 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. `npx -y balladeer@latest setup --force` runs anyway, for whoever has decided to
+keep both.
 
 ## Revoking
 

package/dist/agent.d.ts

@@ -124,3 +124,8 @@ export declare function safeJson(response: Response): Promise<unknown>;
 export declare function updateLine(payload: unknown): string;
 /** One field of a tool result, when it is a string. Never a guess. */
 export declare function structuredString(structured: unknown, field: string): string | undefined;
+/** Render the server's live enforcement limitation once per CLI operation. */
+export declare function reportAgentEnforcementWarning(call: AgentToolCall, output: Readonly<{
+    json: boolean;
+    write: (text: string) => void;
+}>): void;

package/dist/agent.js

@@ -21,7 +21,8 @@ const REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
 export function selectAgent(agents, controlPlane, repositoryId, currentRepository) {
     const here = agents.filter((agent) => agent.controlPlane === controlPlane);
     if (repositoryId !== undefined) {
-        const named = here.find((agent) => agent.repositoryId === repositoryId);
+        const named = here.find((agent) => agent.repositoryId === repositoryId ||
+            agent.repository?.toLowerCase() === repositoryId.toLowerCase());
         if (named === undefined) {
             return {
                 kind: "refused",
@@ -207,3 +208,14 @@ export function structuredString(structured, field) {
     const value = structured[field];
     return typeof value === "string" ? value : undefined;
 }
+/** Render the server's live enforcement limitation once per CLI operation. */
+export function reportAgentEnforcementWarning(call, output) {
+    if (call.kind !== "result" && call.kind !== "tool_refusal")
+        return;
+    const message = structuredString(call.structured, "enforcementWarning");
+    if (message === undefined)
+        return;
+    output.write(output.json
+        ? `${JSON.stringify({ step: "warning", code: "enforcement_unavailable", message })}\n`
+        : `WARNING  ${message}\n`);
+}

package/dist/cli.d.ts

@@ -6,6 +6,16 @@ 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 --existing`: connect only when this checkout is already enrolled. */
+    existingOnly: 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 +31,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,19 +8,23 @@ 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";
 import { updateNotice } from "./currency.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
-import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
+import { CLI_INVOCATION, 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]
+  ${CLI_INVOCATION} setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
+                  [--create-workspace <name>] [--refresh] [--force]
+                  [--existing]
+                  [--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
@@ -27,21 +32,32 @@ const USAGE = `balladeer ${CLI_VERSION}
       --create-workspace carries a name to the approval page, where a person
       signs in and creates the workspace themselves; this command never creates
       one.
+      --existing is for an invited teammate and never enrolls repositories or changes CI.
+      If this repository is already connected, connect this machine; otherwise
+      continue in the browser while an administrator connects it.
       --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>]
+  ${CLI_INVOCATION} repositories [--json] [--control-plane <url>]
       List the repositories this machine's GitHub account can see, marking the
       one you are standing in and the ones Balladeer already has.
 
-  balladeer invite <email>... [--role contributor|viewer|administrator] [--json]
+  ${CLI_INVOCATION} invite <email>... [--role contributor|viewer|administrator] [--json]
       Invite teammates into this workspace by email, and say per address whether
       the invitation went. Inviting is an administrator's act.
 
-  balladeer status [<promise id>] [--repo owner/name] [--repository <uuid>] [--json]
+  ${CLI_INVOCATION} status [<promise id>] [--repo owner/name] [--repository <uuid>] [--json]
                    [--control-plane <url>]
       Report this repository over its agent connection, and every repository in
       the workspace when a setup session is still live. Named with a promise id,
@@ -50,17 +66,30 @@ const USAGE = `balladeer ${CLI_VERSION}
       the agreed meaning that run was checking. That is the form the line on a
       broken promise tells a person to run first.
 
-  balladeer propose --file <path> [--repo owner/name] [--repository <uuid>] [--json]
+  ${CLI_INVOCATION} propose --file <path> [--repo owner/name] [--repository <uuid>] [--json]
       Propose one promise from a proposal file, over this repository's agent
       connection. A named person still agrees to it.
 
-  balladeer discover --file <path> [--repo owner/name] [--repository <uuid>]
+  ${CLI_INVOCATION} 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.
+
+  ${CLI_INVOCATION} 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
       owned by whoever paired this machine, and print one link that opens all of
       them. A named person still agrees to every one.
 
-  balladeer check-seals [--json] [--runner <path>] [--install-hook]
+  ${CLI_INVOCATION} check-seals [--json] [--runner <path>] [--install-hook]
       Say whether what you are about to push would break a promise's seal. It
       prints nothing and exits 0 when it would not, and names the promise, its
       owner, its page and the line that seals it again when it would. It runs
@@ -68,34 +97,45 @@ const USAGE = `balladeer ${CLI_VERSION}
       writes .git/hooks/pre-push so every push asks first; nothing installs it
       for you, and deleting that file removes it.
 
-  balladeer touch-map [--json]
+  ${CLI_INVOCATION} touch-map [--json]
       Run this repository's promise verifiers under coverage and write down
       which files each one actually executed, to .continuity/touch-map.json.
       It runs offline and the map stays on this machine: Balladeer is never
       sent it. Node verifiers only in this release.
 
-  balladeer affected <paths...> [--json]
+  ${CLI_INVOCATION} affected <paths...> [--json]
       Say which promises the named files touch, out of that map, marking any
       answer whose verifier has changed since the map was built. It reads one
       local file and contacts nothing.
 
-  balladeer explain [--control-plane <url>]
+  ${CLI_INVOCATION} 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.
+
+  ${CLI_INVOCATION} explain [--control-plane <url>]
       Print, word for word, what Balladeer can and cannot see, where to watch
       your promises, and what leaving costs.
 
-  balladeer whoami [--json] [--control-plane <url>]
+  ${CLI_INVOCATION} whoami [--json] [--control-plane <url>]
       Report the stored setup session's workspace, role, scopes, and expiry.
 
-  balladeer agent rotate [--control-plane <url>]
+  ${CLI_INVOCATION} agent rotate [--control-plane <url>]
       Replace this repository's agent credential. A setup session cannot do this,
       because rotating revokes the connections the repository already has.
 
-  balladeer mcp [--repository <uuid>] [--control-plane <url>]
+  ${CLI_INVOCATION} mcp [--repository <uuid>] [--control-plane <url>]
       Forward one MCP session over stdio using this repository's agent connection.
 
 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 +151,13 @@ export function parseArguments(argv) {
     let json = false;
     let wait = false;
     let refresh = false;
+    let force = false;
+    let existingOnly = false;
+    let claudeDesktop;
     let installHook = false;
+    let fresh = false;
+    let record = false;
+    let again = false;
     let runner;
     let controlPlane;
     let repo;
@@ -147,14 +193,28 @@ 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 === "--existing")
+            existingOnly = 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 +241,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 \`${CLI_INVOCATION} 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
@@ -193,7 +265,28 @@ export function parseArguments(argv) {
     // nothing else. Accepting it silently elsewhere would let somebody run
     // `status --refresh`, see no error, and believe their install was repaired.
     if (refresh && command !== "setup") {
-        throw new StoreError("usage", "--refresh belongs to setup: run `balladeer setup --refresh`.");
+        throw new StoreError("usage", `--refresh belongs to setup: run \`${CLI_INVOCATION} 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 \`${CLI_INVOCATION} setup --force\`.`);
+    }
+    if (existingOnly && command !== "setup") {
+        throw new StoreError("usage", `--existing belongs to setup: run \`${CLI_INVOCATION} setup --existing\`.`);
+    }
+    if (existingOnly && createWorkspace !== undefined) {
+        throw new StoreError("usage", "--existing cannot be combined with --create-workspace: one refuses repository enrollment and the other starts a new workspace.");
+    }
+    if (existingOnly && repositories.length > 1) {
+        throw new StoreError("usage", "--existing connects one checkout and never adds repositories. Leave off --repository, or name only this checkout.");
+    }
+    // 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 \`${CLI_INVOCATION} 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 +298,18 @@ export function parseArguments(argv) {
         json,
         wait,
         refresh,
+        force,
+        existingOnly,
+        claudeDesktop,
         repo,
         file,
         repository: repositories[0],
         repositories,
         owner,
         installHook,
+        fresh,
+        record,
+        again,
         runner,
         createWorkspace,
         positional,
@@ -248,6 +347,9 @@ async function dispatch(parsed, write) {
                 json: parsed.json,
                 wait: parsed.wait,
                 refresh: parsed.refresh,
+                force: parsed.force,
+                existingOnly: parsed.existingOnly,
+                ...(parsed.claudeDesktop === undefined ? {} : { claudeDesktop: parsed.claudeDesktop }),
                 ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
                 repositories: parsed.repositories,
                 ...(parsed.createWorkspace === undefined
@@ -296,6 +398,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 +436,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: ${CLI_INVOCATION} 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 +518,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.
  *
@@ -26,7 +26,29 @@ export declare class RefusalError extends Error {
  * identifier and this builds the address, which is why there is no parameter
  * here for a server's own link to arrive through.
  */
-export declare function reviewLink(controlPlane: string, path: string): string;
+export declare function reviewLink(controlPlane: string, path: string, workspaceId?: 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, workspaceId?: 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;