balladeer 1.0.1 → 1.0.3

package/README.md

@@ -23,8 +23,9 @@ npx -y balladeer@latest setup
 ```
 
 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.
+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. For Codex, keep
+`--client codex` on the refresh command: `npx -y balladeer@latest setup --client codex --refresh`.
 
 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.
@@ -34,10 +35,16 @@ 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
-  nothing else, so installing it pulls nothing else down.
+- Node 22 or newer. The command uses Node builtins and the pinned `@iarna/toml` parser to preserve
+  Codex project configuration safely.
 - `git`, and the GitHub CLI (`gh`) signed in to an account with push access to the repository. Your
   `gh` is how the command reads the repository's ids and opens the pull request that carries the
   workflow. Balladeer itself never holds a GitHub credential.
@@ -58,19 +65,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.
@@ -93,10 +101,10 @@ with your checkout and no Balladeer credential.
 It writes, locally and visibly: your credentials to `$XDG_CONFIG_HOME/balladeer/credentials.json`,
 or `~/.config/balladeer/credentials.json`, with mode 600 inside a directory with mode 700, and it
 refuses to write them anywhere a commit could pick them up; a `balladeer` entry in the repository's
-`.mcp.json`, added beside whatever is already there and never over the top of somebody else's entry;
-and a marker-fenced block in the repository's `CLAUDE.md` or `AGENTS.md`, replaced between the
-markers on each run and never outside them. A file whose markers are damaged is left alone and
-reported rather than appended to.
+`.mcp.json` for Claude, or `.codex/config.toml` with `--client codex`, preserving unrelated entries;
+and a marker-fenced block in `AGENTS.md` for Codex (the existing `CLAUDE.md` or `AGENTS.md` for
+Claude), replaced between the markers on each run and never outside them. A file whose markers are
+damaged is left alone and reported rather than appended to.
 
 It changes, on your GitHub repository and through your own `gh`: the repository variables the
 workflow reads, so the workflow file itself names no host by hand.
@@ -108,22 +116,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 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                  |
+| 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.
@@ -132,7 +140,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
@@ -161,16 +169,42 @@ A machine that ran the earlier Balladeer still carries it: that client registers
 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.
+old binary in place. `npx -y balladeer@latest setup --force` runs anyway, for whoever has decided to
+keep both.
 
 ## Revoking
 
 Both credentials are yours to end. Revoke the setup session or the coding agent's connection at any
 time in Balladeer; the setup session also ends on its own. Removing the `balladeer` entry from
-`.mcp.json` disconnects the agent locally, and deleting the credential store leaves this machine
-with nothing of yours on it.
+`.mcp.json` (Claude) or the managed table in `.codex/config.toml` (Codex) disconnects that project
+host locally after its next reload. Archiving the credential store removes this machine's saved
+Balladeer access without changing the server's records.
 
 ## Licence
 
 Apache License 2.0. The full text ships in this package as `LICENSE`, so you can read the rights you
 have from the copy on your own machine rather than taking a field in a manifest on trust.
+
+## Choose Codex or reconnect a workspace
+
+Run `npx -y balladeer@latest setup --client codex` in the repository to write its
+`.codex/config.toml` and the managed Balladeer block in `AGENTS.md`. This leaves Claude files,
+Claude Desktop, global Codex settings and unrelated MCP entries alone. The default client remains
+Claude; choose it explicitly with `--client claude`.
+
+Open and trust the project in Codex if appropriate, then start a fresh session. Project settings are
+ignored in untrusted projects; the setup connection probe does not prove the host loaded its tools.
+Check the actual Balladeer tools in that new session. Refresh only local Codex configuration with
+`setup --client codex --refresh`; no pairing or network request is made.
+
+To reconnect a different existing workspace, run:
+
+```sh
+npx -y balladeer@latest setup --client codex --existing --choose-workspace --wait
+```
+
+Choose the workspace and approve pairing in the browser. The current control plane's setup session
+is replaced only after a new pairing starts; all stored agent connections and other control planes
+remain. `--create-workspace "Team name"` likewise opens fresh pairing instead of silently reusing
+the previous workspace. It pre-fills the name; a human still creates the workspace. An interrupted
+command can resume the same pending choice by running it again with the same flags.

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,8 +6,12 @@ type Parsed = Readonly<{
     wait: boolean;
     /** Repair the files a previous setup wrote, and do nothing else. */
     refresh: boolean;
+    client: "codex" | "claude" | undefined;
+    chooseWorkspace: 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

package/dist/cli.js

@@ -18,22 +18,37 @@ 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] [--force]
+  ${CLI_INVOCATION} setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
+                  [--create-workspace <name>] [--choose-workspace] [--refresh] [--force]
+                  [--client codex|claude]
+                  [--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
       nothing more, because connecting an agent and CI happens in a checkout.
+      --client codex writes project .codex/config.toml and AGENTS.md.
+      Trust the project in Codex and start a fresh session to load its tools.
+      --client claude (the default) preserves the Claude setup behavior.
+      For --refresh only, a lone managed Codex entry selects Codex automatically.
+      If both clients have Balladeer entries, choose --client explicitly.
+      --choose-workspace starts fresh browser pairing for this control plane,
+      preserving other saved agent connections. Use it with --existing to
+      reconnect an existing workspace. --create-workspace also starts fresh
+      pairing instead of reusing the previously selected workspace.
+
       --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, its Balladeer instructions
-      block and its Claude desktop chat entry to the current form, leaves every
+      selected client's project MCP entry and Balladeer instructions block
+      (and Claude desktop entry for Claude) 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
@@ -45,15 +60,15 @@ const USAGE = `balladeer ${CLI_VERSION}
       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,
@@ -62,11 +77,11 @@ 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 prepare <promise id> [--again] [--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
@@ -79,13 +94,13 @@ const USAGE = `balladeer ${CLI_VERSION}
       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>]
+  ${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
@@ -93,18 +108,18 @@ 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 session [--new] [--record] [--repo owner/name] [--repository <uuid>] [--json]
+  ${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
@@ -114,18 +129,18 @@ const USAGE = `balladeer ${CLI_VERSION}
       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>]
+  ${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
@@ -147,7 +162,10 @@ export function parseArguments(argv) {
     let json = false;
     let wait = false;
     let refresh = false;
+    let client;
+    let chooseWorkspace = false;
     let force = false;
+    let existingOnly = false;
     let claudeDesktop;
     let installHook = false;
     let fresh = false;
@@ -170,6 +188,7 @@ export function parseArguments(argv) {
         "--owner": "a membership id",
         "--create-workspace": "a workspace name",
         "--role": "contributor, viewer, or administrator",
+        "--client": "codex or claude",
         "--runner": "a path to the pinned runner's cli.js",
     };
     const value = (flag, inline) => {
@@ -202,8 +221,18 @@ export function parseArguments(argv) {
             wait = true;
         else if (name === "--refresh")
             refresh = true;
+        else if (name === "--choose-workspace")
+            chooseWorkspace = true;
+        else if (name === "--client") {
+            const requested = value("--client", inline);
+            if (requested !== "codex" && requested !== "claude")
+                throw new StoreError("usage", "--client needs codex or claude.");
+            client = requested;
+        }
         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")
@@ -241,7 +270,7 @@ export function parseArguments(argv) {
     // 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`.");
+        throw new StoreError("usage", `--again belongs to prepare: run \`${CLI_INVOCATION} prepare <promise id> --again\`.`);
     }
     if (positional.length > 0 &&
         command !== "invite" &&
@@ -257,20 +286,39 @@ export function parseArguments(argv) {
     // `--refresh` repairs the files setup writes, so it belongs to setup and to
     // nothing else. Accepting it silently elsewhere would let somebody run
     // `status --refresh`, see no error, and believe their install was repaired.
+    if ((client !== undefined || chooseWorkspace || createWorkspace !== undefined) &&
+        command !== "setup") {
+        throw new StoreError("usage", "--client, --choose-workspace and --create-workspace belong to setup.");
+    }
+    if (refresh && (chooseWorkspace || createWorkspace !== undefined)) {
+        throw new StoreError("usage", "--refresh only repairs local files; omit it to choose or create a workspace.");
+    }
+    if (client === "codex" && claudeDesktop === true) {
+        throw new StoreError("usage", "--client codex leaves Claude configuration alone; run a separate --client claude setup to connect Claude Desktop.");
+    }
     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 `balladeer setup --force`.");
+        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 `balladeer setup --claude-desktop`.");
+        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.`);
@@ -282,7 +330,10 @@ export function parseArguments(argv) {
         json,
         wait,
         refresh,
+        client,
+        chooseWorkspace,
         force,
+        existingOnly,
         claudeDesktop,
         repo,
         file,
@@ -330,7 +381,10 @@ async function dispatch(parsed, write) {
                 json: parsed.json,
                 wait: parsed.wait,
                 refresh: parsed.refresh,
+                chooseWorkspace: parsed.chooseWorkspace,
+                ...(parsed.client === undefined ? {} : { client: parsed.client }),
                 force: parsed.force,
+                existingOnly: parsed.existingOnly,
                 ...(parsed.claudeDesktop === undefined ? {} : { claudeDesktop: parsed.claudeDesktop }),
                 ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
                 repositories: parsed.repositories,
@@ -423,7 +477,7 @@ async function dispatch(parsed, write) {
             // 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");
+                process.stderr.write(`prepare reads one promise id: ${CLI_INVOCATION} prepare <promise id> [--again].\n`);
                 return 4;
             }
             return runPrepare({

package/dist/client.d.ts

@@ -26,7 +26,7 @@ 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.
  *
@@ -37,7 +37,7 @@ export declare function reviewLink(controlPlane: string, path: string): string;
  * 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;
+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;
 /**

package/dist/client.js

@@ -42,8 +42,11 @@ export 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 function reviewLink(controlPlane, path) {
-    return new URL(path, ensureTrailing(controlPlane)).toString();
+export function reviewLink(controlPlane, path, workspaceId) {
+    const url = new URL(path, ensureTrailing(controlPlane));
+    if (workspaceId !== undefined)
+        url.searchParams.set("workspaceId", workspaceId);
+    return url.toString();
 }
 /**
  * The one place this command decides where a person reads a proposal.
@@ -55,8 +58,8 @@ export function reviewLink(controlPlane, path) {
  * 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)}`);
+export function proposalReviewLink(controlPlane, proposalId, workspaceId) {
+    return reviewLink(controlPlane, `proposals/${encodeURIComponent(proposalId)}`, workspaceId);
 }
 /** The address the whole waiting inbox is read on. */
 export function proposalInboxLink(controlPlane) {

package/dist/codex-config.d.ts

@@ -0,0 +1,7 @@
+import { type MergeResult, type StdioMcpEntry } from "./mcp-config.js";
+export declare const CODEX_CONFIG_FILE = ".codex/config.toml";
+export declare function readCodexEntry(root: string): unknown;
+/** A client hint only when the complete file and our exact fenced table agree. */
+export declare function hasManagedCodexEntry(root: string, controlPlane: string): boolean;
+/** Only our fenced table is replaced; every unrelated byte and parsed setting survives. */
+export declare function mergeCodexConfig(root: string, entry: StdioMcpEntry, controlPlane: string): MergeResult;