balladeer 1.0.1 → 1.0.2

package/README.md

@@ -23,8 +23,8 @@ 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.
 
 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,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
@@ -58,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.
@@ -108,22 +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 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 +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
@@ -161,7 +168,8 @@ 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
 

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

@@ -8,6 +8,8 @@ type Parsed = Readonly<{
     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

package/dist/cli.js

@@ -18,11 +18,12 @@ 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>]
+  ${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
@@ -31,6 +32,9 @@ 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, its Balladeer instructions
       block and its Claude desktop chat entry to the current form, leaves every
@@ -45,15 +49,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 +66,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 +83,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 +97,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 +118,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
@@ -148,6 +152,7 @@ export function parseArguments(argv) {
     let wait = false;
     let refresh = false;
     let force = false;
+    let existingOnly = false;
     let claudeDesktop;
     let installHook = false;
     let fresh = false;
@@ -204,6 +209,8 @@ export function parseArguments(argv) {
             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")
@@ -241,7 +248,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" &&
@@ -258,19 +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 `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.`);
@@ -283,6 +299,7 @@ export function parseArguments(argv) {
         wait,
         refresh,
         force,
+        existingOnly,
         claudeDesktop,
         repo,
         file,
@@ -331,6 +348,7 @@ async function dispatch(parsed, write) {
                 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,
@@ -423,7 +441,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/commands/affected.js

@@ -1,7 +1,7 @@
 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 { CLI_INVOCATION } from "../wire.js";
 import { promiseRoot } from "./touch-map.js";
 /** How many promises one path lists before the report says how many more. */
 const NAMED_LIMIT = 20;
@@ -36,7 +36,7 @@ export async function runAffected(options) {
             options.write(`${text}\n`);
     };
     if (options.paths.length === 0) {
-        const message = "Name at least one path: balladeer affected src/orders/total.ts";
+        const message = `Name at least one path: ${CLI_INVOCATION} affected src/orders/total.ts`;
         if (options.json)
             emit({ step: "error", reason: "usage", message, changed: false, exitCode: 4 });
         else
@@ -55,8 +55,8 @@ export async function runAffected(options) {
     const reading = readTouchMap(root);
     if (reading.kind !== "map") {
         const message = reading.kind === "absent"
-            ? `There is no touch map in this checkout yet. Build one with: balladeer touch-map`
-            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: balladeer touch-map`;
+            ? `There is no touch map in this checkout yet. Build one with: ${CLI_INVOCATION} touch-map`
+            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: ${CLI_INVOCATION} touch-map`;
         emit({ step: "affected", mapped: false, paths: [], changed: false });
         say(message);
         // Zero, because having no map is not a fault in the change somebody is
@@ -115,8 +115,8 @@ export async function runAffected(options) {
     say("");
     if (stale > 0) {
         say(stale === 1
-            ? "One answer above is stale. Run balladeer touch-map to measure it again."
-            : `${stale} of those answers are stale. Run balladeer touch-map to measure them again.`);
+            ? `One answer above is stale. Run ${CLI_INVOCATION} touch-map to measure it again.`
+            : `${stale} of those answers are stale. Run ${CLI_INVOCATION} touch-map to measure them again.`);
     }
     say("This came from your own checkout. Balladeer was not asked, and was told nothing.");
     return 0;

package/dist/commands/check-seals.js

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import { runCommand } from "../gh.js";
 import { repositoryRoot } from "../git.js";
 import { promiseForPath, sealedPromises } from "../seals.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 /**
  * Where the pinned runner sits once setup's instructions have been followed.
  *
@@ -258,17 +258,17 @@ function installPrePushHook(root, options, emit, say) {
     const hookPath = join(root, ".git", "hooks", "pre-push");
     if (existsSync(hookPath)) {
         const message = `${hookPath} already exists, so nothing was written. Add this line to it yourself if you ` +
-            "want the check: balladeer check-seals";
+            `want the check: ${CLI_INVOCATION} check-seals`;
         emit({ step: "error", reason: "hook_exists", message, changed: false, exitCode: 4 });
         say(message);
         return 4;
     }
     const script = [
         "#!/bin/sh",
-        "# Installed by: balladeer check-seals --install-hook",
+        `# Installed by: ${CLI_INVOCATION} check-seals --install-hook`,
         "# It stops a push that would break a promise's seal, and says nothing otherwise.",
         "# Delete this file to remove it.",
-        "balladeer check-seals || exit 1",
+        `${CLI_INVOCATION} check-seals || exit 1`,
         "",
     ].join("\n");
     try {

package/dist/commands/discover.js

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs";
-import { callAgentTool, selectAgent, structuredString } from "../agent.js";
+import { callAgentTool, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
 import { batchProposalReviewLink, proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 import { readTeachBackFile } from "./propose.js";
 /**
  * Ten promises at 64 KiB each, which is the per-promise cap `propose` already
@@ -197,7 +197,7 @@ export async function runDiscover(options) {
         return exitCode;
     };
     if (!options.file) {
-        return fail("usage", "Give a catalog file: balladeer discover --file <path>.", 4);
+        return fail("usage", `Give a catalog file: ${CLI_INVOCATION} discover --file <path>.`, 4);
     }
     let raw;
     try {
@@ -232,6 +232,7 @@ export async function runDiscover(options) {
             `Run \`${commandLine(null, "setup")}\` here again to pair this machine, which records who you are, or name the owner yourself with --owner <membership id> from the members list on the Balladeer MCP server's setup tool.`, 4);
     }
     const setup = await callAgentTool(agent, "get_promise_setup", {});
+    reportAgentEnforcementWarning(setup, options);
     if (setup.kind !== "result") {
         return fail("owner_unverified", `${memberListRefusal(setup.kind, options.controlPlane)} Nothing was sent.`, 5);
     }
@@ -254,7 +255,7 @@ export async function runDiscover(options) {
                 index: index + 1,
                 title,
                 candidateId: outcome.candidateId,
-                reviewUrl: proposalReviewLink(options.controlPlane, outcome.candidateId),
+                reviewUrl: proposalReviewLink(options.controlPlane, outcome.candidateId, agent.workspaceId),
             };
             filed.push(entry);
             emit({

package/dist/commands/prepare.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { callAgentTool, noAgentCredentialSentence, selectAgent } from "../agent.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, } from "../agent.js";
 import { inReadersZone } from "../local-time.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
@@ -150,6 +150,7 @@ export async function runPrepare(options) {
         promiseId: options.promiseId,
         again: options.again,
     });
+    reportAgentEnforcementWarning(call, options);
     switch (call.kind) {
         case "endpoint_refused":
             return fail("agent_endpoint_unsafe", `${call.reason} Nothing was prepared.`, 4);

package/dist/commands/propose.js

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs";
-import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
+import { callAgentTool, noAgentCredentialSentence, reportAgentEnforcementWarning, selectAgent, structuredString, } from "../agent.js";
 import { proposalReviewLink } from "../client.js";
 import { commandLine } from "../release.js";
 import { repositoryHint } from "../repository.js";
 import { StoreError, readCredentials } from "../store.js";
-import {} from "../wire.js";
+import { CLI_INVOCATION } from "../wire.js";
 const MAX_FILE_BYTES = 64 * 1024;
 /**
  * Every field the server's schema requires with no default. It is every
@@ -190,7 +190,7 @@ export async function runPropose(options) {
         return exitCode;
     };
     if (!options.file) {
-        return fail("usage", "Give a proposal file: balladeer propose --file <path>.", 4);
+        return fail("usage", `Give a proposal file: ${CLI_INVOCATION} propose --file <path>.`, 4);
     }
     let raw;
     try {
@@ -240,6 +240,7 @@ export async function runPropose(options) {
             ? {}
             : { leastSure: parsed.value.teachBack.leastSure }),
     });
+    reportAgentEnforcementWarning(call, options);
     switch (call.kind) {
         case "endpoint_refused":
             return fail("agent_endpoint_unsafe", `${call.reason} Nothing was sent.`, 4);
@@ -273,7 +274,7 @@ export async function runPropose(options) {
     // The review link is built from the address this copy paired with. The tool
     // answers with an id and no link at all, so there is nothing here a
     // misconfigured public base URL could redirect.
-    const review = proposalReviewLink(options.controlPlane, candidateId);
+    const review = proposalReviewLink(options.controlPlane, candidateId, agent.workspaceId);
     emit({ step: "promise", status: "proposed", candidateId, reviewUrl: review });
     if (!options.json) {
         options.write("Proposed. You will own it unless you named someone else; the owner reads it and clicks Agree, and nothing else can.\n");

package/dist/commands/repositories.js

@@ -94,6 +94,7 @@ function report(options, rows, workspaceKnown) {
     say(options, workspaceKnown
         ? "Repositories your GitHub account can see. Ones already in Balladeer are marked."
         : "Repositories your GitHub account can see. Nothing is stored for this Balladeer, so which of them are already added is unknown.");
+    say(options, "These are GitHub repositories, not local directories or git worktrees.");
     say(options, "");
     for (const row of rows) {
         const marks = [