balladeer 1.0.3 → 1.0.5

package/README.md

@@ -22,10 +22,36 @@ do. To run it yourself instead:
 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 `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`.
+Starting with CLI 1.0.5 on supported macOS/Linux hosts, setup installs the `balladeer` executable
+before pairing. After setup, use `balladeer status`, `balladeer session` and other everyday
+commands. To install or repair only the executable, without pairing or changing a repository:
+
+```sh
+npx -y balladeer@latest install
+```
+
+That bootstrap selects the latest published release. `balladeer install` repairs the running
+release. If your shell cannot find `balladeer` after installation, reopen the terminal or coding
+agent so it sees the current PATH, then check `balladeer --version`. A running child command cannot
+change its parent's environment. Older setups without the executable can still use
+`npx -y balladeer@latest <command>`; the new install command requires 1.0.5 or newer.
+
+To upgrade the executable and refresh in one command, run `npx -y balladeer@latest setup --refresh`
+(add `--client codex` for Codex). This bootstrap selects the published update.
+
+Run `balladeer setup --refresh` to refresh repository instructions without replacing other tools'
+settings. For Codex, keep `--client codex`: `balladeer setup --client codex --refresh`. Existing
+instructions are not refreshed just because a package was installed. Refresh can contact npm and
+write the local toolchain when ensuring the executable is installed; it does not perform a Balladeer
+authority action. The repository MCP entry continues to use `npx -y balladeer@latest mcp` so native
+tools can pick up published updates.
+
+Automatic installation supports macOS/Linux with zsh, bash or sh. It uses the active npm global
+prefix or a writable personal prefix; when needed, it adds a bounded PATH block to your shell
+startup files while preserving unrelated content. An unfamiliar shell receives an explicit manual
+PATH step. Windows automatic installation is not qualified: use the reported manual
+`npm install --global balladeer@latest` instruction and verify the executable separately. Setup can
+continue with a truthful partial installation state; that does not mean the CLI is ready on PATH.
 
 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.
@@ -41,6 +67,41 @@ already enrolled it connects this machine and writes its MCP configuration; when
 leaves the checkout unchanged and Balladeer shows that enforcement tracking is unavailable until an
 administrator connects a repository.
 
+## Know what is ready
+
+The CLI being on PATH, an MCP entry being configured, native tools loading in your coding host, and
+an authenticated repository read succeeding are separate observations. Check the executable in the
+shell you use, then load the host's real tools in a fresh session. A configuration file alone does
+not prove native tool loading or server access.
+
+`balladeer session` saves an optional local stamp for retrieval evidence. If only that stamp write
+is refused, authorized MCP reads, coding and explicitly requested capture may continue without a
+session ID. Do not invent an ID or trailer. This does not fix missing credentials, installation or
+authorization failures, and does not guarantee every CLI command works in every sandbox.
+
+## If npm cannot start the bootstrap
+
+An EPERM or EACCES error naming npm's cache happens before Balladeer starts. Use an allowed writable
+cache for the same command, or request normal host permission. If `/tmp` is allowed, for example:
+
+```sh
+balladeer_npm_cache=$(mktemp -d /tmp/balladeer-npm-cache.XXXXXX)
+npm_config_cache="$balladeer_npm_cache" npx -y balladeer@latest setup
+```
+
+Do not infer root ownership from a permission error, use `sudo`, change ownership or delete saved
+credentials. A writable npm cache grants neither network access nor access to the installation
+prefix or credential folder. Follow the specific refusal; preserve a denied permission request.
+
+## If setup cannot save its local connection
+
+Setup needs access to its private credential folder, normally `~/.config/balladeer`. If your
+terminal or coding agent blocks that access, allow the command to access the private folder named in
+the error, then repeat the same setup command with the same flags. Keep your existing saved
+credentials; do not delete the store or move it into your repository. Setup checks local write
+access before requesting a new browser pairing and reports a credential-store error separately from
+a connection failure.
+
 ## Requirements
 
 - Node 22 or newer. The command uses Node builtins and the pinned `@iarna/toml` parser to preserve

package/dist/cli.js

@@ -16,11 +16,17 @@ 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 { runInstall } from "./install.js";
 import { updateNotice } from "./currency.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
 import { CLI_INVOCATION, CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
 const USAGE = `balladeer ${CLI_VERSION}
 
+  ${CLI_INVOCATION} install [--json]
+      Install this exact release as the durable balladeer command, without pairing
+      or changing any workspace, repository, or CI configuration. Use the latest
+      npx bootstrap to upgrade an older global command.
+
   ${CLI_INVOCATION} setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
                   [--create-workspace <name>] [--choose-workspace] [--refresh] [--force]
                   [--client codex|claude]
@@ -46,10 +52,11 @@ const USAGE = `balladeer ${CLI_VERSION}
       --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
+      --refresh repairs the durable command if needed, then rewrites this
       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
+      other entry in those files alone, and prints what it changed. Installing
+      the command may contact npm; refresh never contacts Balladeer. 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
@@ -60,6 +67,10 @@ 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.
 
+      If setup cannot access its private credential folder, allow this command
+      to access the folder named in the error, then repeat the same setup command.
+      Keep existing saved credentials; do not delete the store to retry.
+
   ${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.
@@ -375,8 +386,19 @@ async function dispatch(parsed, write) {
     switch (parsed.command) {
         case "explain":
             return runExplain(write, parsed.controlPlane);
+        case "install":
+            return runInstall({ environment: process.env, json: parsed.json, write });
         case "setup":
             return runSetup({
+                installCommand: () => {
+                    const result = runInstall({
+                        environment: process.env,
+                        json: parsed.json,
+                        write,
+                        allowPartial: true,
+                    });
+                    return process.platform === "win32" ? 0 : result;
+                },
                 controlPlane: parsed.controlPlane,
                 json: parsed.json,
                 wait: parsed.wait,

package/dist/commands/setup.d.ts

@@ -24,9 +24,9 @@ export type SetupOptions = Readonly<{
     existingOnly?: boolean;
     /**
      * Repair the two files a previous setup wrote in this repository, and do
-     * nothing else. No pairing, no enrollment, no credential, no network: a
-     * stale install is repaired where it is, which may be a laptop that cannot
-     * reach the control plane at that moment.
+     * nothing else in the workspace. No pairing, enrollment, or credential: a
+     * stale install is repaired without the control plane. The real CLI also
+     * ensures its durable command is installed and may contact npm.
      */
     refresh?: boolean;
     /**
@@ -55,6 +55,8 @@ export type SetupOptions = Readonly<{
     environment: NodeJS.ProcessEnv;
     cwd: string;
     write: (text: string) => void;
+    /** Real CLI installer; tests of pairing can inject a no-write observer. */
+    installCommand?: () => number;
     sleep?: (ms: number) => Promise<void>;
     now?: () => Date;
 }>;

package/dist/commands/setup.js

@@ -15,7 +15,7 @@ import { findLegacyInstall, legacyMessage } from "../legacy.js";
 import { formatInstant } from "../local-time.js";
 import { checkoutEntryPath, commandLine, runningFromRegistryInstall } from "../release.js";
 import { hostHint, repositoryHint } from "../repository.js";
-import { StoreError, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
+import { StoreError, assertStoreWritable, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
 import { CLI_VERSION, DELEGATED_SCOPES, } from "../wire.js";
 import { explainText } from "./explain.js";
 import { probeAgentConnection } from "./mcp.js";
@@ -168,10 +168,11 @@ function pendingLines(pending, repository, host, waiting, approvalUri) {
         ...JOIN_OR_CREATE.split("\n").map((line) => (line.length === 0 ? "" : `  ${line}`)),
     ];
 }
-function storeSession(credentials, controlPlane, token, session) {
+function storeSession(credentials, controlPlane, token, session, workspaceChoice) {
     return putSession(dropPendingPairing(credentials, controlPlane), {
         controlPlane,
         sessionId: session.sessionId,
+        ...(workspaceChoice?.startsWith("create:") ? { workspaceChoice } : {}),
         token,
         workspaceId: session.workspaceId,
         workspaceName: session.workspaceName,
@@ -290,23 +291,31 @@ export async function runSetup(options) {
     catch (error) {
         return storeFailure(options, error);
     }
-    // Workspace choice is explicit. Preserve all agent connections and other
-    // origins; persist the session replacement only when a new pairing starts.
+    if (options.installCommand && options.installCommand() !== 0)
+        return 4;
+    // A completed create intent resumes only its own authenticated session. The
+    // name is local intent, never a lookup or grant of workspace authority. An
+    // explicit chooser always starts a switch. Keep the old session until the
+    // new pairing is claimed, so a failed start or claim loses no credentials.
     const workspaceChoice = options.createWorkspace !== undefined
         ? `create:${carriedName}`
         : options.chooseWorkspace === true
             ? "choose"
             : undefined;
+    const previousSession = findSession(credentials, controlPlane);
+    const freshChoice = workspaceChoice !== undefined &&
+        (options.chooseWorkspace === true || previousSession?.workspaceChoice !== workspaceChoice);
     if (workspaceChoice !== undefined) {
         credentials = {
             ...credentials,
-            sessions: credentials.sessions.filter((entry) => entry.controlPlane !== controlPlane),
             pendingPairings: credentials.pendingPairings.filter((entry) => entry.controlPlane !== controlPlane || entry.workspaceChoice === workspaceChoice),
         };
+    }
+    if (freshChoice) {
         say(options, "Choose the workspace in the new browser pairing. Existing agent connections remain saved.");
     }
     // A still-valid session carries straight on to the steps that need it.
-    const stored = findSession(credentials, controlPlane);
+    const stored = freshChoice ? undefined : previousSession;
     if (stored && Date.parse(stored.expiresAt) > now().getTime()) {
         try {
             const answer = await request(controlPlane, {
@@ -378,6 +387,9 @@ export async function runSetup(options) {
     }
     let started;
     try {
+        // An unsaved claim secret cannot be recovered by retrying the browser link.
+        // Check local access before creating an unapproved remote pairing.
+        assertStoreWritable(options.environment);
         const { verifier, digest } = newVerifier();
         started = await request(controlPlane, {
             method: "POST",
@@ -450,7 +462,7 @@ async function claimOnce(options, credentials, pending) {
         if (answer.status === "pending") {
             return { kind: "pending", pollIntervalSeconds: answer.pollIntervalSeconds };
         }
-        const updated = storeSession(credentials, options.controlPlane, answer.token, answer.session);
+        const updated = storeSession(credentials, options.controlPlane, answer.token, answer.session, pending.workspaceChoice);
         writeCredentials(updated, options.environment);
         reportPaired(options, answer.session);
         const session = findSession(updated, options.controlPlane);
@@ -1020,9 +1032,7 @@ function reportAgentHost(options, configured, published) {
         say(options, line);
     for (const line of hostNextSteps(options))
         say(options, line);
-    say(options, published === null
-        ? `  Setup does not install a global balladeer executable. This checkout's CLI runs as \`${commandLine(null, "<command>")}\` after it is built.`
-        : `  Setup does not install a global balladeer executable. Run the CLI as \`${commandLine(published, "<command>")}\`; ${hostConfigFile(options)} invokes that same package automatically.`);
+    say(options, "  Use `balladeer <command>` for everyday CLI calls. If installation or PATH still needs attention, use `npx -y balladeer@latest <command>` until it is repaired. The MCP launcher remains independently configured.");
     if (configured.files.length > 0) {
         say(options, `  ${configured.files.join(" and ")} ${configured.files.length === 1 ? "is an uncommitted change" : "are uncommitted changes"} in your working tree. Commit ${configured.files.length === 1 ? "it" : "them"} when you are ready; they carry no secret.`);
     }
@@ -1661,6 +1671,8 @@ async function runRefresh(input) {
     if (repositoryId === undefined) {
         return failRefresh(options, "not_connected", `Nothing here names a repository to refresh: this machine holds no Balladeer credential for it and ${hostConfigFile(options)} has no balladeer entry. Run \`${commandLine(null, "setup")}\` to connect it.`);
     }
+    if (options.installCommand && options.installCommand() !== 0)
+        return 4;
     const merged = mergeHostConfig(options, root, repositoryId, refreshPublishedForm(existing));
     if (merged.kind === "refused") {
         say(options, merged.reason);

package/dist/commands/status.js

@@ -48,7 +48,7 @@ const POSTURE_REASONS = {
 /** What a posture this copy does not recognise says, rather than a green word. */
 const UNREPORTED_POSTURE = "Balladeer is not reporting this behavior as holding, and this copy of the command does not recognise the state it is in.";
 function noSessionSentence(controlPlane) {
-    return `Every repository in the workspace is read over a setup session, and none is stored for ${controlPlane}. Run \`${commandLine(null, "setup")}\` to read the whole workspace.`;
+    return `Every repository in the workspace is read over a setup session, and none is stored for ${controlPlane}. Run \`${commandLine(null, "setup --existing --choose-workspace")}\` to choose the existing workspace and read its optional workspace view.`;
 }
 /**
  * What Balladeer looks like right now, read from the server and never from
@@ -476,7 +476,7 @@ async function reportWorkspace(options, session, here, emit, say, alreadyReporte
             // This repository has already been reported over its own connection, so
             // the workspace-wide half is a view this run could not read rather than a
             // command that failed.
-            sayWorkspaceUnavailable(emit, say, code, `Every repository in the workspace is read over a setup session, and the stored one could not be used (${code}). Run \`${commandLine(null, "setup")}\` to read the whole workspace.`);
+            sayWorkspaceUnavailable(emit, say, code, `Every repository in the workspace is read over a setup session, and the stored one could not be used (${code}). Run \`${commandLine(null, "setup --existing --choose-workspace")}\` to choose the existing workspace and read its optional workspace view.`);
             return 0;
         }
         if (error instanceof ClientTooOldError) {

package/dist/conventions.d.ts

@@ -27,7 +27,7 @@ export declare const CONVENTIONS_END = "<!-- balladeer:conventions:end -->";
  * instructions marker instead. A bump here with no change to the block would
  * rewrite twelve repositories to say exactly what they already said.
  */
-export declare const CONVENTIONS_VERSION = 17;
+export declare const CONVENTIONS_VERSION = 18;
 export declare function managedByLine(version: number): string;
 /**
  * Which version of the block a file already carries, or nothing when it carries

package/dist/conventions.js

@@ -31,7 +31,7 @@ export const CONVENTIONS_END = "<!-- balladeer:conventions:end -->";
  * instructions marker instead. A bump here with no change to the block would
  * rewrite twelve repositories to say exactly what they already said.
  */
-export const CONVENTIONS_VERSION = 17;
+export const CONVENTIONS_VERSION = 18;
 /** Both spellings: the stable marker, and the versioned one version 1 wrote. */
 const START_MARKER = /<!-- balladeer:conventions:start(?: v(\d{1,4}))? -->/g;
 const END_MARKER = /<!-- balladeer:conventions:end -->/g;

package/dist/copy.d.ts

@@ -69,7 +69,7 @@ export declare const RETRIEVAL_SCOPE = "### Reading what is already agreed\n\nRe
  * plane's `/agent` page carries the same bytes under its own constant, and a
  * packaging test compares them.
  */
-export declare const SESSION_BEHAVIORS = "### Three things to offer without being asked\n\nAt the start of any session in this repository, before you plan anything, ask list_promises for the\npromises nothing is checking yet that belong to the person you are working with: `unverified` true\nand `mine` true, which is one bounded read rather than the catalog. If it returns any, say so in one\nline and offer to build their verifiers now. Name each one by its one-sentence claim rather than by\nan id, so the person can see which behavior is unguarded. Ask the same tool for\n`brokenSinceLastSeen` true as well, and where that returns any, say in one line that those promises\nbroke since they last looked, name each by its claim, and offer to fix them. Then wait for their\nanswer. The offer is the whole of it, and never start building or repairing one because nobody said\nno.\n\nTheirs, and nobody else's. `mine` keeps the promises this person owns or agreed to, and a teammate's\nunguarded promise is that teammate's to hear about: a session that opens by reading out other\npeople's unfinished work reads as an audit of them. `brokenSinceLastSeen` is that person's own by\nconstruction and needs no `mine` beside it. Drop `mine` when this person asks what the rest of the\nteam has promised, and say whose promises you are showing them when you do.\n\nWhen you have proposed promises, show them here as well as there. Put each proposal in the\nconversation in full: its one-sentence claim, who it is for, when it applies and what must then be\ntrue, the numbered cases that must keep working and the ones that must be caught, and every question\nyou left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them\nthe page it returns and taking the one-time code that page shows them, so the browser is needed only\nfor signing. Give them the review link in the same message too, because some people would rather\nread it there and edit it before they agree.\nA promise whose meaning is agreed and which nothing is checking yet is one you can finish. When\nsomebody gives you a promise id, run `npx -y balladeer@latest status <promise id>`, or expand it with get_promise.\nIf it comes back agreed with nothing checking it, say so in one line and offer to prepare and build\nits verifier now. Only if they say yes: `prepare_qualification` mints the one-time setup, or\n`npx -y balladeer@latest prepare <promise id>` mints it and writes it where the sealed run reads it. You need no\nsign-off for that and there is no code to ask anybody for, because agreeing the meaning was their\nact and building the check that proves it is yours. Then build the verifier, seal it, push, and tell\nthem protection starts by itself when that run qualifies. The offer is the whole of it: never\nprepare one because nobody said no.";
+export declare const SESSION_BEHAVIORS = "### Three things to offer without being asked\n\nAt the start of any session in this repository, before you plan anything, ask list_promises for the\npromises nothing is checking yet that belong to the person you are working with: `unverified` true\nand `mine` true, which is one bounded read rather than the catalog. If it returns any, say so in one\nline and offer to build their verifiers now. Name each one by its one-sentence claim rather than by\nan id, so the person can see which behavior is unguarded. Ask the same tool for\n`brokenSinceLastSeen` true as well, and where that returns any, say in one line that those promises\nbroke since they last looked, name each by its claim, and offer to fix them. Then wait for their\nanswer. The offer is the whole of it, and never start building or repairing one because nobody said\nno.\n\nTheirs, and nobody else's. `mine` keeps the promises this person owns or agreed to, and a teammate's\nunguarded promise is that teammate's to hear about: a session that opens by reading out other\npeople's unfinished work reads as an audit of them. `brokenSinceLastSeen` is that person's own by\nconstruction and needs no `mine` beside it. Drop `mine` when this person asks what the rest of the\nteam has promised, and say whose promises you are showing them when you do.\n\nWhen you have proposed promises, show them here as well as there. Put each proposal in the\nconversation in full: its one-sentence claim, who it is for, when it applies and what must then be\ntrue, the numbered cases that must keep working and the ones that must be caught, and every question\nyou left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them\nthe page it returns and taking the one-time code that page shows them, so the browser is needed only\nfor signing. Give them the review link in the same message too, because some people would rather\nread it there and edit it before they agree.\nA promise whose meaning is agreed and which nothing is checking yet is one you can finish. When\nsomebody gives you a promise id, run `balladeer status <promise id>`, or expand it with get_promise.\nIf it comes back agreed with nothing checking it, say so in one line and offer to prepare and build\nits verifier now. Only if they say yes: `prepare_qualification` mints the one-time setup, or\n`balladeer prepare <promise id>` mints it and writes it where the sealed run reads it. You need no\nsign-off for that and there is no code to ask anybody for, because agreeing the meaning was their\nact and building the check that proves it is yours. Then build the verifier, seal it, push, and tell\nthem protection starts by itself when that run qualifies. The offer is the whole of it: never\nprepare one because nobody said no.";
 /**
  * The capture rules that do not change: when to say nothing, what a yes is
  * worth, and the two promises Balladeer refuses.
@@ -150,7 +150,7 @@ export declare const FETCH_BUDGET = "Fetch by id, and only for an id the person
  * tool guidance and the control plane's `/agent` page carry the same bytes
  * under their own constants, and a packaging test compares all three.
  */
-export declare const SEALED_FILES = "### Files that are sealed, and the one reason to edit one\n\nEvery file under .continuity/promises/ is sealed. The promise that owns that directory records the\nexact bytes of each file in it, so editing one, adding one there, renaming one or deleting one\nbreaks the seal. A promise whose seal is broken stops being checked, and it stays that way until a\nnamed person qualifies it again, which is their afternoon rather than your commit. Nothing in there\nis ordinary source: keep it out of refactors, formatting runs and dependency upgrades.\n\nFind out which directories are sealed before you plan an edit, not after. npx -y balladeer@latest status lists\nthem, and list_promises names a promise's sealed directory on its row once a verifier is bound to\nit. Then, before you push, run npx -y balladeer@latest check-seals. It prints nothing and exits zero when your\nchange touches no seal, and names the promise, its owner and its page when your change would break\none.\n\nThe one reason to edit a sealed file is to repair a verifier that can no longer run: something it\nimports moved, or the language it is written in changed under it. Never edit one to make a failing\ncheck pass. A check going red is the promise doing its job, and the repair for that belongs in the\nbehavior it protects. A repair is not finished until the promise is sealed again with the runner\nthis repository is pinned to. get_promise_setup carries that exact seal command, and\nnpx -y balladeer@latest check-seals prints it beside any promise it names.";
+export declare const SEALED_FILES = "### Files that are sealed, and the one reason to edit one\n\nEvery file under .continuity/promises/ is sealed. The promise that owns that directory records the\nexact bytes of each file in it, so editing one, adding one there, renaming one or deleting one\nbreaks the seal. A promise whose seal is broken stops being checked, and it stays that way until a\nnamed person qualifies it again, which is their afternoon rather than your commit. Nothing in there\nis ordinary source: keep it out of refactors, formatting runs and dependency upgrades.\n\nFind out which directories are sealed before you plan an edit, not after. balladeer status lists\nthem, and list_promises names a promise's sealed directory on its row once a verifier is bound to\nit. Then, before you push, run balladeer check-seals. It prints nothing and exits zero when your\nchange touches no seal, and names the promise, its owner and its page when your change would break\none.\n\nThe one reason to edit a sealed file is to repair a verifier that can no longer run: something it\nimports moved, or the language it is written in changed under it. Never edit one to make a failing\ncheck pass. A check going red is the promise doing its job, and the repair for that belongs in the\nbehavior it protects. A repair is not finished until the promise is sealed again with the runner\nthis repository is pinned to. get_promise_setup carries that exact seal command, and\nballadeer check-seals prints it beside any promise it names.";
 /**
  * Which promises a change touches, measured rather than guessed.
  *
@@ -167,7 +167,7 @@ export declare const SEALED_FILES = "### Files that are sealed, and the one reas
  * Three carriers say it, byte for byte, and a packaging test holds them
  * together.
  */
-export declare const TOUCH_MAP_GUIDANCE = "Prefer the measurement over the markers. Where this repository has a touch map, `npx -y balladeer@latest affected\n<paths...>` answers which promises ran the files in front of you, out of what each verifier actually\nexecuted the last time `npx -y balladeer@latest touch-map` measured it. Both commands run on this machine and\nsend Balladeer nothing, so you may name any path in the change.\n\nAn answer marked stale was measured against a verifier that has changed since, so read it as the\nlast thing anybody measured rather than as fact, and offer to run `npx -y balladeer@latest touch-map` again.\nWhere there is no map, where it does not name your paths, or where it reports a promise it could not\nmeasure, fall back to the paths on the index rows. The map narrows which promises are worth\nfetching. It never widens what you may read: the catalog is still never enumerated, and the fetch\nbudget is unchanged.\n\nWhen a retrieval receipt asks why you read a row, the answer for one the map named is `touch`.";
+export declare const TOUCH_MAP_GUIDANCE = "Prefer the measurement over the markers. Where this repository has a touch map, `balladeer affected\n<paths...>` answers which promises ran the files in front of you, out of what each verifier actually\nexecuted the last time `balladeer touch-map` measured it. Both commands run on this machine and\nsend Balladeer nothing, so you may name any path in the change.\n\nAn answer marked stale was measured against a verifier that has changed since, so read it as the\nlast thing anybody measured rather than as fact, and offer to run `balladeer touch-map` again.\nWhere there is no map, where it does not name your paths, or where it reports a promise it could not\nmeasure, fall back to the paths on the index rows. The map narrows which promises are worth\nfetching. It never widens what you may read: the catalog is still never enumerated, and the fetch\nbudget is unchanged.\n\nWhen a retrieval receipt asks why you read a row, the answer for one the map named is `touch`.";
 /**
  * The one paragraph that turns retrieval from a thing we argue about into a
  * thing we measure.
@@ -186,14 +186,14 @@ export declare const TOUCH_MAP_GUIDANCE = "Prefer the measurement over the marke
  * Three carriers say it, byte for byte, and a packaging test holds them
  * together.
  */
-export declare const SESSION_STAMP = "Run `npx -y balladeer@latest session` when you start work here and pass the id it prints to every promise read\nyou make, as `session`. It is the same id for the whole of one piece of work, and it costs nothing:\na read without it is answered exactly the same way.\n\nIf local file permissions refuse that session write, no session stamp was saved. Your saved\nconnection is unchanged; this does not prove its current server authorization. Continue\nalready-authorized MCP reads, coding and explicitly requested capture without the optional\n`session` field. Do not invent an ID, add a session trailer, or record an unsaved stamp. Do not\nbroaden filesystem access or move credentials to retry this write. A missing credential or server\nauthorization refusal is different: follow that refusal. Capture still needs the person's request\nor accepted offer, and human meaning approval is unchanged.\n\nIf a session ID was saved, near the end of the work call `mark_promise_used` with the ids you actually cited\nor acted on. Naming none is a fine answer. It is the only way anybody finds out which rows were\nworth sending you, because reading a promise and then ignoring it is not the same as using it.\n\nIf a session ID was saved, write `Balladeer-Session: <the id>` into the commit message or pull-request body you produce,\nand run `npx -y balladeer@latest session --record` once the commit exists. That is what lets a check that goes red\nnext week be read back against what Balladeer told you before you started. Your commit message never\nleaves your machine: only the session id and the commit SHA are sent.";
+export declare const SESSION_STAMP = "Use the installed `balladeer` command after setup reports CLI readiness. If it is missing from\nPATH (including an older 1.0.4 setup), use `npx -y balladeer@latest <command>` for that invocation\nand read the current /agent instructions for installation or repair. Do not claim that an older\nrepository's instructions were refreshed. CLI availability does not prove that this coding host\nloaded the native MCP tools or that a credential is authorized. The optional session stamp below\nis separate from all three.\n\nRun `balladeer session` when you start work here and pass the id it prints to every promise read\nyou make, as `session`. It is the same id for the whole of one piece of work, and it costs nothing:\na read without it is answered exactly the same way.\n\nIf local file permissions refuse that session write, no session stamp was saved. Your saved\nconnection is unchanged; this does not prove its current server authorization. Continue\nalready-authorized MCP reads, coding and explicitly requested capture without the optional\n`session` field. Do not invent an ID, add a session trailer, or record an unsaved stamp. Do not\nbroaden filesystem access or move credentials to retry this write. A missing credential or server\nauthorization refusal is different: follow that refusal. Capture still needs the person's request\nor accepted offer, and human meaning approval is unchanged.\n\nIf a session ID was saved, near the end of the work call `mark_promise_used` with the ids you actually cited\nor acted on. Naming none is a fine answer. It is the only way anybody finds out which rows were\nworth sending you, because reading a promise and then ignoring it is not the same as using it.\n\nIf a session ID was saved, write `Balladeer-Session: <the id>` into the commit message or pull-request body you produce,\nand run `balladeer session --record` once the commit exists. That is what lets a check that goes red\nnext week be read back against what Balladeer told you before you started. Your commit message never\nleaves your machine: only the session id and the commit SHA are sent.";
 /**
  * The conventions block written between markers into this repository's agent
  * instructions file. Fixed text, compared byte for byte by a test, because a
  * block that drifts per run would rewrite a customer's committed file on every
  * setup and the diff would say nothing.
  */
-export declare const CONVENTIONS_BLOCK = "## Balladeer promises\n\nBefore planning work in this repository, read the promises this team has already approved through\nthe Balladeer MCP server. They are the behaviors a named person has agreed the software keeps, so\nyour plan has to hold them, not just read them.\n\n### Reading what is already agreed\n\nRetrieve by promise, and only when this session has a reason to. One repository here can hold a\nthousand agreed promises, and a plan built from whatever survived a truncated catalog read is worse\nthan a plan built from none of it, because nothing tells you which half went missing.\n\nWhen a person gives you a promise id, expand exactly that one with get_promise and stop there. Every\npromise page carries a control that copies its id, so an id is what a person hands you when they\nmean a particular promise. Ask for one rather than searching for what they meant.\n\nConsult list_promises in two situations and no others. The person asks what this repository has\npromised, in which case page the index they asked for. Or the change you are about to make touches\npaths that carry promises, in which case give those paths to list_promises: it answers with the\npromises whose scope overlaps them, closest first, and with the few that name no path and so cover\nthe whole repository. That answer is a selection rather than a page and does not continue with a\ncursor, so when the total beside it is larger than what you were handed, narrow the paths rather\nthan asking for more.\n\nWhen you do not yet know which paths you are about to touch, do not call the index at all. Work from\nids until you do, because a page you did not ask a question of is not about your change, and reading\none as though it were is how a plan quietly misses the promise it breaks.\n\nTo learn which paths those are, read `paths` on a list_promises answer you asked for\nwithout paths of your own. It is the set of\nrepository paths this repository's promises are scoped to, deduplicated and bounded, with\n`pathsTruncated` saying whether there were more than the answer carries. Compare the files you are\nabout to change against it. Nothing matching means there is nothing here to read, and saying so is a\nbetter answer than a page of promises about somewhere else.\n\nNever call get_promise_context at the start of a session. It answers the markers you give it, and\nbefore you know what you are changing there are no markers to give: what comes back is a slice of\nthe catalog chosen by nothing. Call it once the work is in front of you, with that work's markers.\n\nEvery one of these reads is bounded and none of them returns the whole catalog. Read the total\nbeside the rows and the sentence in `scope` that says what the total is a total of, and when the\ntotal is larger than what you were handed, page or narrow rather than planning as though you had\nseen everything.\n\nEach index row carries what it takes to rule that promise out without fetching it: the repository,\nthe paths it covers, its one-sentence claim, what protects it and why, and when anything last\nchecked it.\n\nPrefer the measurement over the markers. Where this repository has a touch map, `npx -y balladeer@latest affected\n<paths...>` answers which promises ran the files in front of you, out of what each verifier actually\nexecuted the last time `npx -y balladeer@latest touch-map` measured it. Both commands run on this machine and\nsend Balladeer nothing, so you may name any path in the change.\n\nAn answer marked stale was measured against a verifier that has changed since, so read it as the\nlast thing anybody measured rather than as fact, and offer to run `npx -y balladeer@latest touch-map` again.\nWhere there is no map, where it does not name your paths, or where it reports a promise it could not\nmeasure, fall back to the paths on the index rows. The map narrows which promises are worth\nfetching. It never widens what you may read: the catalog is still never enumerated, and the fetch\nbudget is unchanged.\n\nWhen a retrieval receipt asks why you read a row, the answer for one the map named is `touch`.\n\nFetch by id, and only for an id the person gave you or an index row whose paths match the change in\nfront of you. Never enumerate the catalog. Never chain one fetch into the next to see the whole of\nsomething: when the rows do not settle it, narrow the filter rather than expanding another promise.\n\n### When to say nothing, and what a yes is worth\n\nMost rules are said in passing, in the middle of something else. Somebody saying one has not asked\nyou to record anything, so propose nothing and start no interview. When you do ask, it is one line\nappended to the end of the reply you were already going to give, never a message of its own, never\nasked twice about the same rule, and nothing is proposed until they say yes. A no ends it, and that\nrule is not raised again for the rest of the conversation.\n\nSilence is per conversation rather than per message. Once a conversation is one of these, you ask\nnothing for the rest of it, however good the rule sounds:\n\n- A question, or working out how something already behaves. Nothing is filed and nothing is offered.\n- A refactor. Nobody predicts a promise from a rewrite. Offer the promises this area already carries\n  that nothing is checking yet, once, and then wait. Ask nothing about new ones.\n- A change to wording alone. Wording somebody may change again tomorrow is not a rule.\n- An incident, while it is still being fixed. Ask nothing at all until the fix is merged or they say\n  it is done, however good tonight's failing case would be.\n- Somebody still weighing options. A decision nobody has made yet is not a rule.\n- An exploration or spike. It ends in nothing or in a plan, and its sentences sound like rules and\n  are not.\n- Reading somebody else's change, while you are still reading it. Nothing is offered until they\n  give a verdict.\n\nThe words to ask in, the moment to offer, and the shape a proposal takes are not in this file. The\nBalladeer server sends them at the start of every session, and its copy is the current one: read\nwhat it sent this session rather than what this file remembers.\n\n### Two promises Balladeer cannot keep\n\nA promise about speed needs three things before it is a promise at all: a number, a percentile, and\nwhere it is measured. \"The quote page answers in under one second at p95, measured in production at\npeak load\" is one Balladeer can keep. \"The quote page has to be fast\" is not. Say this, and ask for\nthe part that is missing rather than filing it:\n\n\"I can keep that once it has a number, a percentile, and a place it is measured. Without those it is\na wish, not a promise.\"\n\nBalladeer refuses one without all three and names which of them is missing. When all three are\nthere, write the measurement method into the promise, and tell them plainly that it reads agreed and\nunprotected until a test that actually measures it exists.\n\nA promise about how the team works is not something the software does, so no check can ever catch\nit. \"We must provide a low-friction capture experience\" is one of these. File nothing and say:\n\n\"That is a promise about how we work, not something the software does that a check can fail.\nBalladeer only keeps promises a check can catch. If a customer would notice something when this\nslips, say that and I will keep that instead.\"\n\nThen take the customer-visible half if they give you one, and file that instead.\n\nRun `npx -y balladeer@latest session` when you start work here and pass the id it prints to every promise read\nyou make, as `session`. It is the same id for the whole of one piece of work, and it costs nothing:\na read without it is answered exactly the same way.\n\nIf local file permissions refuse that session write, no session stamp was saved. Your saved\nconnection is unchanged; this does not prove its current server authorization. Continue\nalready-authorized MCP reads, coding and explicitly requested capture without the optional\n`session` field. Do not invent an ID, add a session trailer, or record an unsaved stamp. Do not\nbroaden filesystem access or move credentials to retry this write. A missing credential or server\nauthorization refusal is different: follow that refusal. Capture still needs the person's request\nor accepted offer, and human meaning approval is unchanged.\n\nIf a session ID was saved, near the end of the work call `mark_promise_used` with the ids you actually cited\nor acted on. Naming none is a fine answer. It is the only way anybody finds out which rows were\nworth sending you, because reading a promise and then ignoring it is not the same as using it.\n\nIf a session ID was saved, write `Balladeer-Session: <the id>` into the commit message or pull-request body you produce,\nand run `npx -y balladeer@latest session --record` once the commit exists. That is what lets a check that goes red\nnext week be read back against what Balladeer told you before you started. Your commit message never\nleaves your machine: only the session id and the commit SHA are sent.\n\n### When somebody asks you to protect a behavior\n\nSomebody has asked you to protect a behavior when they say what the software must do, or must never\ndo again, and mean it as a rule rather than as this one bug. That is one promise, for the behavior\nthey named, and nothing else: if you notice others worth protecting, say so in a sentence and let\nthem choose, and file none of them. Never propose from a conversation that did not ask you to. A\nquestion about how something works and a plan you were asked to sketch are not requests to record\nanything, nor is a fix nobody asked you to write a rule about.\n\nAsk before you extrapolate. Ask only what you cannot work out for yourself, ask it all in one\nmessage, and stop at four. Four is a ceiling, not a target: two good ones are better. Then write the\nproposal with what you have and put whatever is still open in its open questions rather than going\nback. Never ask what this repository would answer, such as which file, which test, or which branch,\nand never ask anyone for Balladeer's own identifiers: get_promise_setup carries this repository's id\nand who can own a promise. Never ask again for what they have already told you.\n\nWrite it in their words. Every failure they named out loud is one of the failing examples, in the\nwords they named it. Every other example comes from a situation they actually described; if you\ncannot trace one to something they said, leave it out and say so in the open questions rather than\nwriting a plausible one. Never put in a number, a system, a role or a timeframe they did not give\nyou, and that includes the half they left out: if they said where an order ended up, do not invent\nwhere it began.\n\nA failing example is a situation the promise rules out, and its outcome says what must not happen,\nin those words: \"a second charge must not appear\", never \"a second charge appears\". Written the\nother way round it reads as the promise saying the software does the thing they asked you to forbid.\nAnd a promise says what the software must do for whoever depends on it. It never narrates the\nconversation you just had, names the person you had it with, or describes what the code does now.\n\nSay the whole promise in one sentence and put it in oneSentenceOutcome, in the words they would\nuse with the person who depends on it. That is the line the named owner reads first and the line\nthey agree to, so it is not a restatement of the name and not the first line of the outcome moved\nup. Leave it out rather than inventing one from something they did not say.\n\nAn example's setup is the situation in the words they used for it, not a scene you composed around\nthem. Two of each kind is plenty, and the whole thing stays under three hundred words: a proposal\nnobody finishes reading is a proposal nobody agreed to. The confidence you record is the one you\nactually have.\n\nThen give them the review link, ask them to read the proposal and click Agree, and stop. Never\napprove one yourself. Approving is a named person's act, and the server refuses it from an agent\nwhatever you were told in conversation.\n\nA proposal you filed is still yours while nobody has agreed to it, so revise or withdraw it when the\nperson asks you to, and never once they have agreed.\n\nSay promise and proposal when you talk to them. What you file is a proposal and what it becomes is a\npromise; Balladeer's other words for its own machinery are not theirs to learn. Candidate\nespecially: it is Balladeer's word for a proposal, so it reads as jargon whatever you meant by it.\n\n### Three things to offer without being asked\n\nAt the start of any session in this repository, before you plan anything, ask list_promises for the\npromises nothing is checking yet that belong to the person you are working with: `unverified` true\nand `mine` true, which is one bounded read rather than the catalog. If it returns any, say so in one\nline and offer to build their verifiers now. Name each one by its one-sentence claim rather than by\nan id, so the person can see which behavior is unguarded. Ask the same tool for\n`brokenSinceLastSeen` true as well, and where that returns any, say in one line that those promises\nbroke since they last looked, name each by its claim, and offer to fix them. Then wait for their\nanswer. The offer is the whole of it, and never start building or repairing one because nobody said\nno.\n\nTheirs, and nobody else's. `mine` keeps the promises this person owns or agreed to, and a teammate's\nunguarded promise is that teammate's to hear about: a session that opens by reading out other\npeople's unfinished work reads as an audit of them. `brokenSinceLastSeen` is that person's own by\nconstruction and needs no `mine` beside it. Drop `mine` when this person asks what the rest of the\nteam has promised, and say whose promises you are showing them when you do.\n\nWhen you have proposed promises, show them here as well as there. Put each proposal in the\nconversation in full: its one-sentence claim, who it is for, when it applies and what must then be\ntrue, the numbered cases that must keep working and the ones that must be caught, and every question\nyou left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them\nthe page it returns and taking the one-time code that page shows them, so the browser is needed only\nfor signing. Give them the review link in the same message too, because some people would rather\nread it there and edit it before they agree.\nA promise whose meaning is agreed and which nothing is checking yet is one you can finish. When\nsomebody gives you a promise id, run `npx -y balladeer@latest status <promise id>`, or expand it with get_promise.\nIf it comes back agreed with nothing checking it, say so in one line and offer to prepare and build\nits verifier now. Only if they say yes: `prepare_qualification` mints the one-time setup, or\n`npx -y balladeer@latest prepare <promise id>` mints it and writes it where the sealed run reads it. You need no\nsign-off for that and there is no code to ask anybody for, because agreeing the meaning was their\nact and building the check that proves it is yours. Then build the verifier, seal it, push, and tell\nthem protection starts by itself when that run qualifies. The offer is the whole of it: never\nprepare one because nobody said no.\n\n### When somebody says \"tell me about\" one\n\nAn id is how a person points at something here, and every promise page and every proposal page\ncarries one. A promise id starts with prom_ and a proposal id starts with cand_: expand a promise\nwith get_promise and a proposal with get_proposal, and read neither of them out as a list of fields.\nSay in four or five sentences what it is for, who it is for, when it applies and what must then be\ntrue. Then say where it stands: a promise is agreed, and either protected or not yet checked by\nanything; a proposal is agreed by nobody and waiting on the person it names.\n\nClarify ambiguity that materially changes the behavior during capture, within the existing\nquestion budget; never invent an answer.\n\nOrdinary open questions record uncertainty; they do not prevent the named owner from agreeing to\nthe behavior as written. Agreement does not answer them or add an unstated guarantee. Separate\ncatalog-conflict questions can hold agreement until the owner rules on the stated conflict. Do not\ncall a proposal unready just because it has ordinary open questions. Offer to discuss them if\nuseful; if the person wants to, take them one at a time in the order they come back. For each ordinary question,\nsay what it decides in their words rather than in the question's; give your\nrecommendation and the reason you hold it, drawn from this repository and from the promise itself; and stop there. When\nthey answer, record what they said with resolve_question, in their own words where they gave you\nany, and where their answer changes the promise, follow it with update_proposal, add_case or\nremove_case and tell them what you changed. Never invent an answer or clear uncertainty because\nthey chose to agree. None of that agrees to anything: the named owner agrees, in their own browser\nor through a sign-off you carry, and the questions they answered stay on the proposal in their name.\n\nThe same rule governs every question you leave open in the first place. A question that names a gap\nand stops is a note, and nobody can answer a note. Say what answering it decides, in the words a\ncustomer would use, and carry your own best guess with the reason behind it, so that the shortest\ntrue answer is yes. For example: \"Decides: whether a worker that is running but reconciling nothing\ncounts as an outage this promise covers. Best guess: yes, because the promise is about somebody\nhearing before a customer does, and a wedged worker is invisible to every check this repository has.\nSay yes, or tell me otherwise.\" Balladeer refuses a question filed without both halves and says\nwhich one is missing.\n\n### Files that are sealed, and the one reason to edit one\n\nEvery file under .continuity/promises/ is sealed. The promise that owns that directory records the\nexact bytes of each file in it, so editing one, adding one there, renaming one or deleting one\nbreaks the seal. A promise whose seal is broken stops being checked, and it stays that way until a\nnamed person qualifies it again, which is their afternoon rather than your commit. Nothing in there\nis ordinary source: keep it out of refactors, formatting runs and dependency upgrades.\n\nFind out which directories are sealed before you plan an edit, not after. npx -y balladeer@latest status lists\nthem, and list_promises names a promise's sealed directory on its row once a verifier is bound to\nit. Then, before you push, run npx -y balladeer@latest check-seals. It prints nothing and exits zero when your\nchange touches no seal, and names the promise, its owner and its page when your change would break\none.\n\nThe one reason to edit a sealed file is to repair a verifier that can no longer run: something it\nimports moved, or the language it is written in changed under it. Never edit one to make a failing\ncheck pass. A check going red is the promise doing its job, and the repair for that belongs in the\nbehavior it protects. A repair is not finished until the promise is sealed again with the runner\nthis repository is pinned to. get_promise_setup carries that exact seal command, and\nnpx -y balladeer@latest check-seals prints it beside any promise it names.\n\n### The rest of a promise's life\nWhen a promise is obsolete, finished, deliberately off for a while, or owned by the wrong person,\npropose the change and hand them the promise page. Deciding is theirs.\n\nYou can finish one of those acts here, and only one way. Ask for a sign-off with\nrequest_owner_signoff, give them the page it returns, and ask for the one-time code that page shows\nthem. Then call the act's own tool with that code and their own words. Never call one on your own\ninitiative, never on a general approval of some earlier act, and never ask for a code you were not\ngiven: a refusal is the person's to resolve, not yours to retry. Balladeer records them as the\nperson who acted and you as the messenger.\n\nReport the promise's state exactly as Balladeer reported it: proposed, agreed, or protected, never\none in place of another.\n\n### Where your team watches this\n\nBalladeer is a web app as well as these tools, at the address setup printed. Its catalog lists every\npromise with who owns it and whether anything is checking it, and each promise has a page of its own\nshowing what this team agreed the software must do and then every run that has checked it since,\nnewest first, with the commit each one checked. Whenever there is a link to give, give the link\nrather than a summary of it: the page says what you would have said, and it stays true after this\nconversation has ended.\n\nBalladeer also has a Slack app, which a workspace administrator installs from workspace settings.\nOnce it is installed, whoever owns a promise gets a direct message when theirs goes live and when a\nrun on the default branch breaks it. Until somebody installs it, nothing is sent anywhere, so say it\nis available rather than saying they will be told.\n\n### Questions people ask\n\nAnswer these when they come up. Where you do not know, say so and point at the address setup\nprinted: a confident wrong answer about what a vendor can see is worse than no answer.\n\nWhat it does: it holds the behaviors this team has agreed the software must keep, and reports\nwhether each one is still being kept, from this repository's own tests running in its own CI.\n\nWhat it sees: the text of each promise somebody approves, this repository's numeric ids and the name\nof its default branch, and from CI the pass or fail outcome, the commit checked, and content hashes.\nNever the code, the tests, the fixtures, the logs, the prompts, or the transcripts.\n\nWhat stopping costs: nothing that matters to their tests. The verifier package, its fixtures and the\nworkflow file are theirs, in their repository, running in their CI, and disconnecting changes none\nof them. An administrator can download everything Balladeer holds at any time from workspace\nsettings, and disconnecting hands them that same download in the response that ends access.\n\nWho can approve one: the named person who owns it, in their own browser. Not an administrator on\ntheir behalf, and never you.\n\nWhether it blocks a merge: no. The check is advisory on Balladeer's side, and their own branch\nprotection is what decides whether a failing check stops anything.\n\nWho can invite people and change setup: a workspace administrator. A contributor can read the\nworkspace and propose promises, and a viewer can read it. If somebody asks you to add a teammate,\ninvite_teammate returns the page an administrator sends the invitation from, with the address filled\nin for them to read. The tool sends nothing itself: an administrator presses Send.";
+export declare const CONVENTIONS_BLOCK = "## Balladeer promises\n\nBefore planning work in this repository, read the promises this team has already approved through\nthe Balladeer MCP server. They are the behaviors a named person has agreed the software keeps, so\nyour plan has to hold them, not just read them.\n\n### Reading what is already agreed\n\nRetrieve by promise, and only when this session has a reason to. One repository here can hold a\nthousand agreed promises, and a plan built from whatever survived a truncated catalog read is worse\nthan a plan built from none of it, because nothing tells you which half went missing.\n\nWhen a person gives you a promise id, expand exactly that one with get_promise and stop there. Every\npromise page carries a control that copies its id, so an id is what a person hands you when they\nmean a particular promise. Ask for one rather than searching for what they meant.\n\nConsult list_promises in two situations and no others. The person asks what this repository has\npromised, in which case page the index they asked for. Or the change you are about to make touches\npaths that carry promises, in which case give those paths to list_promises: it answers with the\npromises whose scope overlaps them, closest first, and with the few that name no path and so cover\nthe whole repository. That answer is a selection rather than a page and does not continue with a\ncursor, so when the total beside it is larger than what you were handed, narrow the paths rather\nthan asking for more.\n\nWhen you do not yet know which paths you are about to touch, do not call the index at all. Work from\nids until you do, because a page you did not ask a question of is not about your change, and reading\none as though it were is how a plan quietly misses the promise it breaks.\n\nTo learn which paths those are, read `paths` on a list_promises answer you asked for\nwithout paths of your own. It is the set of\nrepository paths this repository's promises are scoped to, deduplicated and bounded, with\n`pathsTruncated` saying whether there were more than the answer carries. Compare the files you are\nabout to change against it. Nothing matching means there is nothing here to read, and saying so is a\nbetter answer than a page of promises about somewhere else.\n\nNever call get_promise_context at the start of a session. It answers the markers you give it, and\nbefore you know what you are changing there are no markers to give: what comes back is a slice of\nthe catalog chosen by nothing. Call it once the work is in front of you, with that work's markers.\n\nEvery one of these reads is bounded and none of them returns the whole catalog. Read the total\nbeside the rows and the sentence in `scope` that says what the total is a total of, and when the\ntotal is larger than what you were handed, page or narrow rather than planning as though you had\nseen everything.\n\nEach index row carries what it takes to rule that promise out without fetching it: the repository,\nthe paths it covers, its one-sentence claim, what protects it and why, and when anything last\nchecked it.\n\nPrefer the measurement over the markers. Where this repository has a touch map, `balladeer affected\n<paths...>` answers which promises ran the files in front of you, out of what each verifier actually\nexecuted the last time `balladeer touch-map` measured it. Both commands run on this machine and\nsend Balladeer nothing, so you may name any path in the change.\n\nAn answer marked stale was measured against a verifier that has changed since, so read it as the\nlast thing anybody measured rather than as fact, and offer to run `balladeer touch-map` again.\nWhere there is no map, where it does not name your paths, or where it reports a promise it could not\nmeasure, fall back to the paths on the index rows. The map narrows which promises are worth\nfetching. It never widens what you may read: the catalog is still never enumerated, and the fetch\nbudget is unchanged.\n\nWhen a retrieval receipt asks why you read a row, the answer for one the map named is `touch`.\n\nFetch by id, and only for an id the person gave you or an index row whose paths match the change in\nfront of you. Never enumerate the catalog. Never chain one fetch into the next to see the whole of\nsomething: when the rows do not settle it, narrow the filter rather than expanding another promise.\n\n### When to say nothing, and what a yes is worth\n\nMost rules are said in passing, in the middle of something else. Somebody saying one has not asked\nyou to record anything, so propose nothing and start no interview. When you do ask, it is one line\nappended to the end of the reply you were already going to give, never a message of its own, never\nasked twice about the same rule, and nothing is proposed until they say yes. A no ends it, and that\nrule is not raised again for the rest of the conversation.\n\nSilence is per conversation rather than per message. Once a conversation is one of these, you ask\nnothing for the rest of it, however good the rule sounds:\n\n- A question, or working out how something already behaves. Nothing is filed and nothing is offered.\n- A refactor. Nobody predicts a promise from a rewrite. Offer the promises this area already carries\n  that nothing is checking yet, once, and then wait. Ask nothing about new ones.\n- A change to wording alone. Wording somebody may change again tomorrow is not a rule.\n- An incident, while it is still being fixed. Ask nothing at all until the fix is merged or they say\n  it is done, however good tonight's failing case would be.\n- Somebody still weighing options. A decision nobody has made yet is not a rule.\n- An exploration or spike. It ends in nothing or in a plan, and its sentences sound like rules and\n  are not.\n- Reading somebody else's change, while you are still reading it. Nothing is offered until they\n  give a verdict.\n\nThe words to ask in, the moment to offer, and the shape a proposal takes are not in this file. The\nBalladeer server sends them at the start of every session, and its copy is the current one: read\nwhat it sent this session rather than what this file remembers.\n\n### Two promises Balladeer cannot keep\n\nA promise about speed needs three things before it is a promise at all: a number, a percentile, and\nwhere it is measured. \"The quote page answers in under one second at p95, measured in production at\npeak load\" is one Balladeer can keep. \"The quote page has to be fast\" is not. Say this, and ask for\nthe part that is missing rather than filing it:\n\n\"I can keep that once it has a number, a percentile, and a place it is measured. Without those it is\na wish, not a promise.\"\n\nBalladeer refuses one without all three and names which of them is missing. When all three are\nthere, write the measurement method into the promise, and tell them plainly that it reads agreed and\nunprotected until a test that actually measures it exists.\n\nA promise about how the team works is not something the software does, so no check can ever catch\nit. \"We must provide a low-friction capture experience\" is one of these. File nothing and say:\n\n\"That is a promise about how we work, not something the software does that a check can fail.\nBalladeer only keeps promises a check can catch. If a customer would notice something when this\nslips, say that and I will keep that instead.\"\n\nThen take the customer-visible half if they give you one, and file that instead.\n\nUse the installed `balladeer` command after setup reports CLI readiness. If it is missing from\nPATH (including an older 1.0.4 setup), use `npx -y balladeer@latest <command>` for that invocation\nand read the current /agent instructions for installation or repair. Do not claim that an older\nrepository's instructions were refreshed. CLI availability does not prove that this coding host\nloaded the native MCP tools or that a credential is authorized. The optional session stamp below\nis separate from all three.\n\nRun `balladeer session` when you start work here and pass the id it prints to every promise read\nyou make, as `session`. It is the same id for the whole of one piece of work, and it costs nothing:\na read without it is answered exactly the same way.\n\nIf local file permissions refuse that session write, no session stamp was saved. Your saved\nconnection is unchanged; this does not prove its current server authorization. Continue\nalready-authorized MCP reads, coding and explicitly requested capture without the optional\n`session` field. Do not invent an ID, add a session trailer, or record an unsaved stamp. Do not\nbroaden filesystem access or move credentials to retry this write. A missing credential or server\nauthorization refusal is different: follow that refusal. Capture still needs the person's request\nor accepted offer, and human meaning approval is unchanged.\n\nIf a session ID was saved, near the end of the work call `mark_promise_used` with the ids you actually cited\nor acted on. Naming none is a fine answer. It is the only way anybody finds out which rows were\nworth sending you, because reading a promise and then ignoring it is not the same as using it.\n\nIf a session ID was saved, write `Balladeer-Session: <the id>` into the commit message or pull-request body you produce,\nand run `balladeer session --record` once the commit exists. That is what lets a check that goes red\nnext week be read back against what Balladeer told you before you started. Your commit message never\nleaves your machine: only the session id and the commit SHA are sent.\n\n### When somebody asks you to protect a behavior\n\nSomebody has asked you to protect a behavior when they say what the software must do, or must never\ndo again, and mean it as a rule rather than as this one bug. That is one promise, for the behavior\nthey named, and nothing else: if you notice others worth protecting, say so in a sentence and let\nthem choose, and file none of them. Never propose from a conversation that did not ask you to. A\nquestion about how something works and a plan you were asked to sketch are not requests to record\nanything, nor is a fix nobody asked you to write a rule about.\n\nAsk before you extrapolate. Ask only what you cannot work out for yourself, ask it all in one\nmessage, and stop at four. Four is a ceiling, not a target: two good ones are better. Then write the\nproposal with what you have and put whatever is still open in its open questions rather than going\nback. Never ask what this repository would answer, such as which file, which test, or which branch,\nand never ask anyone for Balladeer's own identifiers: get_promise_setup carries this repository's id\nand who can own a promise. Never ask again for what they have already told you.\n\nWrite it in their words. Every failure they named out loud is one of the failing examples, in the\nwords they named it. Every other example comes from a situation they actually described; if you\ncannot trace one to something they said, leave it out and say so in the open questions rather than\nwriting a plausible one. Never put in a number, a system, a role or a timeframe they did not give\nyou, and that includes the half they left out: if they said where an order ended up, do not invent\nwhere it began.\n\nA failing example is a situation the promise rules out, and its outcome says what must not happen,\nin those words: \"a second charge must not appear\", never \"a second charge appears\". Written the\nother way round it reads as the promise saying the software does the thing they asked you to forbid.\nAnd a promise says what the software must do for whoever depends on it. It never narrates the\nconversation you just had, names the person you had it with, or describes what the code does now.\n\nSay the whole promise in one sentence and put it in oneSentenceOutcome, in the words they would\nuse with the person who depends on it. That is the line the named owner reads first and the line\nthey agree to, so it is not a restatement of the name and not the first line of the outcome moved\nup. Leave it out rather than inventing one from something they did not say.\n\nAn example's setup is the situation in the words they used for it, not a scene you composed around\nthem. Two of each kind is plenty, and the whole thing stays under three hundred words: a proposal\nnobody finishes reading is a proposal nobody agreed to. The confidence you record is the one you\nactually have.\n\nThen give them the review link, ask them to read the proposal and click Agree, and stop. Never\napprove one yourself. Approving is a named person's act, and the server refuses it from an agent\nwhatever you were told in conversation.\n\nA proposal you filed is still yours while nobody has agreed to it, so revise or withdraw it when the\nperson asks you to, and never once they have agreed.\n\nSay promise and proposal when you talk to them. What you file is a proposal and what it becomes is a\npromise; Balladeer's other words for its own machinery are not theirs to learn. Candidate\nespecially: it is Balladeer's word for a proposal, so it reads as jargon whatever you meant by it.\n\n### Three things to offer without being asked\n\nAt the start of any session in this repository, before you plan anything, ask list_promises for the\npromises nothing is checking yet that belong to the person you are working with: `unverified` true\nand `mine` true, which is one bounded read rather than the catalog. If it returns any, say so in one\nline and offer to build their verifiers now. Name each one by its one-sentence claim rather than by\nan id, so the person can see which behavior is unguarded. Ask the same tool for\n`brokenSinceLastSeen` true as well, and where that returns any, say in one line that those promises\nbroke since they last looked, name each by its claim, and offer to fix them. Then wait for their\nanswer. The offer is the whole of it, and never start building or repairing one because nobody said\nno.\n\nTheirs, and nobody else's. `mine` keeps the promises this person owns or agreed to, and a teammate's\nunguarded promise is that teammate's to hear about: a session that opens by reading out other\npeople's unfinished work reads as an audit of them. `brokenSinceLastSeen` is that person's own by\nconstruction and needs no `mine` beside it. Drop `mine` when this person asks what the rest of the\nteam has promised, and say whose promises you are showing them when you do.\n\nWhen you have proposed promises, show them here as well as there. Put each proposal in the\nconversation in full: its one-sentence claim, who it is for, when it applies and what must then be\ntrue, the numbered cases that must keep working and the ones that must be caught, and every question\nyou left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them\nthe page it returns and taking the one-time code that page shows them, so the browser is needed only\nfor signing. Give them the review link in the same message too, because some people would rather\nread it there and edit it before they agree.\nA promise whose meaning is agreed and which nothing is checking yet is one you can finish. When\nsomebody gives you a promise id, run `balladeer status <promise id>`, or expand it with get_promise.\nIf it comes back agreed with nothing checking it, say so in one line and offer to prepare and build\nits verifier now. Only if they say yes: `prepare_qualification` mints the one-time setup, or\n`balladeer prepare <promise id>` mints it and writes it where the sealed run reads it. You need no\nsign-off for that and there is no code to ask anybody for, because agreeing the meaning was their\nact and building the check that proves it is yours. Then build the verifier, seal it, push, and tell\nthem protection starts by itself when that run qualifies. The offer is the whole of it: never\nprepare one because nobody said no.\n\n### When somebody says \"tell me about\" one\n\nAn id is how a person points at something here, and every promise page and every proposal page\ncarries one. A promise id starts with prom_ and a proposal id starts with cand_: expand a promise\nwith get_promise and a proposal with get_proposal, and read neither of them out as a list of fields.\nSay in four or five sentences what it is for, who it is for, when it applies and what must then be\ntrue. Then say where it stands: a promise is agreed, and either protected or not yet checked by\nanything; a proposal is agreed by nobody and waiting on the person it names.\n\nClarify ambiguity that materially changes the behavior during capture, within the existing\nquestion budget; never invent an answer.\n\nOrdinary open questions record uncertainty; they do not prevent the named owner from agreeing to\nthe behavior as written. Agreement does not answer them or add an unstated guarantee. Separate\ncatalog-conflict questions can hold agreement until the owner rules on the stated conflict. Do not\ncall a proposal unready just because it has ordinary open questions. Offer to discuss them if\nuseful; if the person wants to, take them one at a time in the order they come back. For each ordinary question,\nsay what it decides in their words rather than in the question's; give your\nrecommendation and the reason you hold it, drawn from this repository and from the promise itself; and stop there. When\nthey answer, record what they said with resolve_question, in their own words where they gave you\nany, and where their answer changes the promise, follow it with update_proposal, add_case or\nremove_case and tell them what you changed. Never invent an answer or clear uncertainty because\nthey chose to agree. None of that agrees to anything: the named owner agrees, in their own browser\nor through a sign-off you carry, and the questions they answered stay on the proposal in their name.\n\nThe same rule governs every question you leave open in the first place. A question that names a gap\nand stops is a note, and nobody can answer a note. Say what answering it decides, in the words a\ncustomer would use, and carry your own best guess with the reason behind it, so that the shortest\ntrue answer is yes. For example: \"Decides: whether a worker that is running but reconciling nothing\ncounts as an outage this promise covers. Best guess: yes, because the promise is about somebody\nhearing before a customer does, and a wedged worker is invisible to every check this repository has.\nSay yes, or tell me otherwise.\" Balladeer refuses a question filed without both halves and says\nwhich one is missing.\n\n### Files that are sealed, and the one reason to edit one\n\nEvery file under .continuity/promises/ is sealed. The promise that owns that directory records the\nexact bytes of each file in it, so editing one, adding one there, renaming one or deleting one\nbreaks the seal. A promise whose seal is broken stops being checked, and it stays that way until a\nnamed person qualifies it again, which is their afternoon rather than your commit. Nothing in there\nis ordinary source: keep it out of refactors, formatting runs and dependency upgrades.\n\nFind out which directories are sealed before you plan an edit, not after. balladeer status lists\nthem, and list_promises names a promise's sealed directory on its row once a verifier is bound to\nit. Then, before you push, run balladeer check-seals. It prints nothing and exits zero when your\nchange touches no seal, and names the promise, its owner and its page when your change would break\none.\n\nThe one reason to edit a sealed file is to repair a verifier that can no longer run: something it\nimports moved, or the language it is written in changed under it. Never edit one to make a failing\ncheck pass. A check going red is the promise doing its job, and the repair for that belongs in the\nbehavior it protects. A repair is not finished until the promise is sealed again with the runner\nthis repository is pinned to. get_promise_setup carries that exact seal command, and\nballadeer check-seals prints it beside any promise it names.\n\n### The rest of a promise's life\nWhen a promise is obsolete, finished, deliberately off for a while, or owned by the wrong person,\npropose the change and hand them the promise page. Deciding is theirs.\n\nYou can finish one of those acts here, and only one way. Ask for a sign-off with\nrequest_owner_signoff, give them the page it returns, and ask for the one-time code that page shows\nthem. Then call the act's own tool with that code and their own words. Never call one on your own\ninitiative, never on a general approval of some earlier act, and never ask for a code you were not\ngiven: a refusal is the person's to resolve, not yours to retry. Balladeer records them as the\nperson who acted and you as the messenger.\n\nReport the promise's state exactly as Balladeer reported it: proposed, agreed, or protected, never\none in place of another.\n\n### Where your team watches this\n\nBalladeer is a web app as well as these tools, at the address setup printed. Its catalog lists every\npromise with who owns it and whether anything is checking it, and each promise has a page of its own\nshowing what this team agreed the software must do and then every run that has checked it since,\nnewest first, with the commit each one checked. Whenever there is a link to give, give the link\nrather than a summary of it: the page says what you would have said, and it stays true after this\nconversation has ended.\n\nBalladeer also has a Slack app, which a workspace administrator installs from workspace settings.\nOnce it is installed, whoever owns a promise gets a direct message when theirs goes live and when a\nrun on the default branch breaks it. Until somebody installs it, nothing is sent anywhere, so say it\nis available rather than saying they will be told.\n\n### Questions people ask\n\nAnswer these when they come up. Where you do not know, say so and point at the address setup\nprinted: a confident wrong answer about what a vendor can see is worse than no answer.\n\nWhat it does: it holds the behaviors this team has agreed the software must keep, and reports\nwhether each one is still being kept, from this repository's own tests running in its own CI.\n\nWhat it sees: the text of each promise somebody approves, this repository's numeric ids and the name\nof its default branch, and from CI the pass or fail outcome, the commit checked, and content hashes.\nNever the code, the tests, the fixtures, the logs, the prompts, or the transcripts.\n\nWhat stopping costs: nothing that matters to their tests. The verifier package, its fixtures and the\nworkflow file are theirs, in their repository, running in their CI, and disconnecting changes none\nof them. An administrator can download everything Balladeer holds at any time from workspace\nsettings, and disconnecting hands them that same download in the response that ends access.\n\nWho can approve one: the named person who owns it, in their own browser. Not an administrator on\ntheir behalf, and never you.\n\nWhether it blocks a merge: no. The check is advisory on Balladeer's side, and their own branch\nprotection is what decides whether a failing check stops anything.\n\nWho can invite people and change setup: a workspace administrator. A contributor can read the\nworkspace and propose promises, and a viewer can read it. If somebody asks you to add a teammate,\ninvite_teammate returns the page an administrator sends the invitation from, with the address filled\nin for them to read. The tool sends nothing itself: an administrator presses Send.";
 /**
  * How an agent turns a repository that has just been connected into a catalog a
  * person can read. Setup's last step prints it, and the control plane's `/agent`

package/dist/copy.js

@@ -179,10 +179,10 @@ the page it returns and taking the one-time code that page shows them, so the br
 for signing. Give them the review link in the same message too, because some people would rather
 read it there and edit it before they agree.
 A promise whose meaning is agreed and which nothing is checking yet is one you can finish. When
-somebody gives you a promise id, run \`npx -y balladeer@latest status <promise id>\`, or expand it with get_promise.
+somebody gives you a promise id, run \`balladeer status <promise id>\`, or expand it with get_promise.
 If it comes back agreed with nothing checking it, say so in one line and offer to prepare and build
 its verifier now. Only if they say yes: \`prepare_qualification\` mints the one-time setup, or
-\`npx -y balladeer@latest prepare <promise id>\` mints it and writes it where the sealed run reads it. You need no
+\`balladeer prepare <promise id>\` mints it and writes it where the sealed run reads it. You need no
 sign-off for that and there is no code to ask anybody for, because agreeing the meaning was their
 act and building the check that proves it is yours. Then build the verifier, seal it, push, and tell
 them protection starts by itself when that run qualifies. The offer is the whole of it: never
@@ -357,9 +357,9 @@ breaks the seal. A promise whose seal is broken stops being checked, and it stay
 named person qualifies it again, which is their afternoon rather than your commit. Nothing in there
 is ordinary source: keep it out of refactors, formatting runs and dependency upgrades.
 
-Find out which directories are sealed before you plan an edit, not after. npx -y balladeer@latest status lists
+Find out which directories are sealed before you plan an edit, not after. balladeer status lists
 them, and list_promises names a promise's sealed directory on its row once a verifier is bound to
-it. Then, before you push, run npx -y balladeer@latest check-seals. It prints nothing and exits zero when your
+it. Then, before you push, run balladeer check-seals. It prints nothing and exits zero when your
 change touches no seal, and names the promise, its owner and its page when your change would break
 one.
 
@@ -368,7 +368,7 @@ imports moved, or the language it is written in changed under it. Never edit one
 check pass. A check going red is the promise doing its job, and the repair for that belongs in the
 behavior it protects. A repair is not finished until the promise is sealed again with the runner
 this repository is pinned to. get_promise_setup carries that exact seal command, and
-npx -y balladeer@latest check-seals prints it beside any promise it names.`;
+balladeer check-seals prints it beside any promise it names.`;
 /**
  * Which promises a change touches, measured rather than guessed.
  *
@@ -385,13 +385,13 @@ npx -y balladeer@latest check-seals prints it beside any promise it names.`;
  * Three carriers say it, byte for byte, and a packaging test holds them
  * together.
  */
-export const TOUCH_MAP_GUIDANCE = `Prefer the measurement over the markers. Where this repository has a touch map, \`npx -y balladeer@latest affected
+export const TOUCH_MAP_GUIDANCE = `Prefer the measurement over the markers. Where this repository has a touch map, \`balladeer affected
 <paths...>\` answers which promises ran the files in front of you, out of what each verifier actually
-executed the last time \`npx -y balladeer@latest touch-map\` measured it. Both commands run on this machine and
+executed the last time \`balladeer touch-map\` measured it. Both commands run on this machine and
 send Balladeer nothing, so you may name any path in the change.
 
 An answer marked stale was measured against a verifier that has changed since, so read it as the
-last thing anybody measured rather than as fact, and offer to run \`npx -y balladeer@latest touch-map\` again.
+last thing anybody measured rather than as fact, and offer to run \`balladeer touch-map\` again.
 Where there is no map, where it does not name your paths, or where it reports a promise it could not
 measure, fall back to the paths on the index rows. The map narrows which promises are worth
 fetching. It never widens what you may read: the catalog is still never enumerated, and the fetch
@@ -416,7 +416,14 @@ When a retrieval receipt asks why you read a row, the answer for one the map nam
  * Three carriers say it, byte for byte, and a packaging test holds them
  * together.
  */
-export const SESSION_STAMP = `Run \`npx -y balladeer@latest session\` when you start work here and pass the id it prints to every promise read
+export const SESSION_STAMP = `Use the installed \`balladeer\` command after setup reports CLI readiness. If it is missing from
+PATH (including an older 1.0.4 setup), use \`npx -y balladeer@latest <command>\` for that invocation
+and read the current /agent instructions for installation or repair. Do not claim that an older
+repository's instructions were refreshed. CLI availability does not prove that this coding host
+loaded the native MCP tools or that a credential is authorized. The optional session stamp below
+is separate from all three.
+
+Run \`balladeer session\` when you start work here and pass the id it prints to every promise read
 you make, as \`session\`. It is the same id for the whole of one piece of work, and it costs nothing:
 a read without it is answered exactly the same way.
 
@@ -433,7 +440,7 @@ or acted on. Naming none is a fine answer. It is the only way anybody finds out
 worth sending you, because reading a promise and then ignoring it is not the same as using it.
 
 If a session ID was saved, write \`Balladeer-Session: <the id>\` into the commit message or pull-request body you produce,
-and run \`npx -y balladeer@latest session --record\` once the commit exists. That is what lets a check that goes red
+and run \`balladeer session --record\` once the commit exists. That is what lets a check that goes red
 next week be read back against what Balladeer told you before you started. Your commit message never
 leaves your machine: only the session id and the commit SHA are sent.`;
 /**

package/dist/currency.js

@@ -59,7 +59,7 @@ export function noteServerVersion(headers) {
     const line = advice === null ? "" : bounded(advice);
     notice =
         line === ""
-            ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run setup --refresh, or restart this session, before continuing.`
+            ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.`
             : line;
 }
 /** The one line this run prints about itself, or nothing when it is current. */

package/dist/install.d.ts

@@ -0,0 +1,23 @@
+type Environment = NodeJS.ProcessEnv;
+export type InstallOptions = {
+    environment: Environment;
+    /** An exact archive is injected only by installed-package tests, never a CLI flag. */
+    packageSpec?: string;
+    platform?: NodeJS.Platform;
+};
+export type InstallResult = {
+    status: "current" | "installed";
+    command: string;
+    restartRequired: boolean;
+    manualPathRequired?: boolean;
+    version: string;
+};
+export declare class InstallError extends Error {
+}
+export declare function ensureInstalled(options: InstallOptions): InstallResult;
+export declare function runInstall(options: InstallOptions & {
+    json: boolean;
+    write: (text: string) => void;
+    allowPartial?: boolean;
+}): number;
+export {};

package/dist/install.js

@@ -0,0 +1,270 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { CLI_VERSION } from "./wire.js";
+export class InstallError extends Error {
+}
+function commandOnPath(name, env) {
+    for (const directory of (env.PATH ?? "").split(delimiter)) {
+        // Match the shell: empty and relative PATH entries refer to this cwd.
+        const resolvedDirectory = resolve(directory || ".");
+        const path = join(resolvedDirectory, name);
+        // npm exec prepends transient package bins. They are not a durable install.
+        if (name.startsWith("balladeer") && resolvedDirectory.split(/[\\/]/).includes("node_modules"))
+            continue;
+        try {
+            accessSync(path, constants.X_OK);
+            return path;
+        }
+        catch {
+            /* next directory */
+        }
+    }
+    return undefined;
+}
+function execute(command, args, env) {
+    return execFileSync(command, args, {
+        env,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 120_000,
+        maxBuffer: 2 * 1024 * 1024,
+    }).trim();
+}
+/** Inspect package ownership before executing a command from PATH. */
+function packageVersion(command, env) {
+    let entry = realpathSync(command);
+    if (basename(entry) === "volta-shim") {
+        const volta = commandOnPath("volta", env);
+        if (!volta)
+            return undefined;
+        try {
+            entry = realpathSync(execute(volta, ["which", "balladeer"], env));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const root = dirname(dirname(entry));
+    try {
+        const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        if (manifest.name !== "balladeer" ||
+            manifest.bin?.balladeer !== "dist/cli.js" ||
+            realpathSync(join(root, "dist/cli.js")) !== entry)
+            return undefined;
+        return manifest.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownedWritable(path) {
+    let ancestor = path;
+    while (!existsSync(ancestor) && dirname(ancestor) !== ancestor)
+        ancestor = dirname(ancestor);
+    try {
+        const info = statSync(ancestor);
+        if (process.getuid && info.uid !== process.getuid())
+            return false;
+        accessSync(ancestor, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function refuseSymlinkPath(path, home) {
+    let part = resolve(path);
+    while (part !== resolve(home) && dirname(part) !== part) {
+        if (existsSync(part) && lstatSync(part).isSymbolicLink())
+            throw new InstallError("The personal install location contains a symbolic link. Choose a normal writable home directory before installing.");
+        part = dirname(part);
+    }
+}
+const START = "# >>> Balladeer command PATH >>>";
+const END = "# <<< Balladeer command PATH <<<";
+function shellProfiles(env, bin) {
+    const home = env.HOME;
+    if (!home || !isAbsolute(home))
+        throw new InstallError("A writable absolute HOME is required for personal installation.");
+    const shell = basename(env.SHELL ?? "");
+    const loginBash = [".bash_profile", ".bash_login", ".profile"].find((name) => existsSync(join(home, name))) ??
+        ".profile";
+    const filenames = shell === "zsh"
+        ? [".zshrc", ".zprofile"]
+        : shell === "bash"
+            ? [".bashrc", loginBash]
+            : shell === "sh"
+                ? [".profile"]
+                : undefined;
+    if (!filenames)
+        return [];
+    return filenames.map((filename) => {
+        const path = join(home, filename);
+        refuseSymlinkPath(path, home);
+        if (!ownedWritable(path))
+            throw new InstallError(`Cannot update ${path}. Allow access to this file, then repeat the install command. No pairing has started.`);
+        const old = existsSync(path) ? readFileSync(path, "utf8") : "";
+        const start = old.indexOf(START), end = old.indexOf(END);
+        if (start < 0 !== end < 0 ||
+            (start >= 0 &&
+                (end < start ||
+                    old.indexOf(START, start + START.length) >= 0 ||
+                    old.indexOf(END, end + END.length) >= 0)))
+            throw new InstallError("The Balladeer PATH block is incomplete or duplicated. Repair that block before repeating install.");
+        const quoted = `'${bin.replaceAll("'", "'\\''")}'`;
+        const block = `${START}\nexport PATH=${quoted}:"$PATH"\n${END}`;
+        const text = start >= 0
+            ? old.slice(0, start) + block + old.slice(end + END.length)
+            : old + (old.endsWith("\n") || !old ? "" : "\n") + block + "\n";
+        return { path, text, previous: old };
+    });
+}
+export function ensureInstalled(options) {
+    const env = options.environment;
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32")
+        throw new InstallError("Automatic command installation currently supports macOS and Linux. On Windows, use npm install --global balladeer@latest, then verify balladeer --version. No files or pairing were changed.");
+    const current = commandOnPath("balladeer", env);
+    if (current) {
+        const version = packageVersion(current, env);
+        if (version === undefined)
+            throw new InstallError(`Another command already owns ${current}. Keep it intact and resolve that command conflict before installing Balladeer.`);
+        const newer = /^\d+\.\d+\.\d+$/.test(version) &&
+            version
+                .split(".")
+                .map(Number)
+                .some((part, index, parts) => part > Number(CLI_VERSION.split(".")[index]) &&
+                parts
+                    .slice(0, index)
+                    .every((value, before) => value === Number(CLI_VERSION.split(".")[before])));
+        if (version === CLI_VERSION || newer) {
+            if (execute(current, ["--version"], env) !== version)
+                throw new InstallError("The installed Balladeer command does not run the expected version. Repair the installation before pairing.");
+            return { status: "current", command: current, restartRequired: false, version };
+        }
+    }
+    const npm = commandOnPath("npm", env);
+    if (!npm)
+        throw new InstallError("npm is required to install the Balladeer command. Install Node 22 with npm, then repeat setup.");
+    const cache = mkdtempSync(join(tmpdir(), "balladeer-install-cache-"));
+    const installEnv = { ...env, npm_config_cache: cache };
+    try {
+        let prefix;
+        try {
+            prefix = execute(npm, ["prefix", "--global"], installEnv);
+        }
+        catch {
+            throw new InstallError("Cannot read npm's global install location. Check npm permissions and repeat install; no pairing has started.");
+        }
+        if (!isAbsolute(prefix))
+            throw new InstallError("npm returned an invalid global install location.");
+        let fallback = false;
+        let profiles;
+        if (![prefix, join(prefix, "bin"), join(prefix, "lib/node_modules")].every(ownedWritable)) {
+            if (!env.HOME || !isAbsolute(env.HOME))
+                throw new InstallError("npm's global location is not writable. Choose a writable npm prefix on PATH, then repeat install.");
+            prefix = join(env.HOME, ".local", "share", "balladeer", "npm");
+            refuseSymlinkPath(prefix, env.HOME);
+            if (!ownedWritable(prefix))
+                throw new InstallError("The personal Balladeer install location is not writable. Allow access and repeat install; no pairing has started.");
+            profiles = shellProfiles(env, join(prefix, "bin"));
+            fallback = true;
+        }
+        const bin = join(prefix, "bin");
+        const target = join(bin, "balladeer");
+        if (existsSync(target) && packageVersion(target, env) === undefined)
+            throw new InstallError("The npm destination already contains another command named balladeer. Nothing was overwritten.");
+        const packageRoot = join(prefix, "lib/node_modules/balladeer");
+        if (existsSync(packageRoot) && !existsSync(target))
+            throw new InstallError("The npm destination contains an incomplete Balladeer package. Repair it explicitly before setup; nothing was overwritten.");
+        const args = [
+            "install",
+            "--global",
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            ...(fallback ? ["--prefix", prefix] : []),
+            options.packageSpec ?? `balladeer@${CLI_VERSION}`,
+        ];
+        try {
+            execute(npm, args, installEnv);
+        }
+        catch {
+            throw new InstallError("Balladeer could not be installed. Check network and write access to npm's install location, then repeat `npx -y balladeer@latest install`. No pairing has started.");
+        }
+        // Resolve the version-manager's command first, or the conventional prefix bin.
+        let installed = commandOnPath("balladeer", env);
+        if (!installed || packageVersion(installed, env) !== CLI_VERSION)
+            installed = existsSync(target) ? target : undefined;
+        if (!installed ||
+            packageVersion(installed, env) !== CLI_VERSION ||
+            execute(installed, ["--version"], env) !== CLI_VERSION)
+            throw new InstallError("npm finished, but the exact Balladeer command could not be verified. No pairing has started.");
+        let restartRequired = commandOnPath("balladeer", env) !== installed;
+        if (restartRequired && !profiles)
+            profiles = shellProfiles(env, dirname(installed));
+        if (profiles) {
+            for (const profile of profiles) {
+                const temporary = `${profile.path}.balladeer-${process.pid}.tmp`;
+                try {
+                    refuseSymlinkPath(profile.path, env.HOME);
+                    const currentText = existsSync(profile.path) ? readFileSync(profile.path, "utf8") : "";
+                    if (currentText !== profile.previous)
+                        throw new InstallError("Your shell configuration changed during installation. The command is installed, but PATH was not updated; repeat install after reviewing that file.");
+                    mkdirSync(dirname(profile.path), { recursive: true });
+                    writeFileSync(temporary, profile.text, {
+                        mode: existsSync(profile.path) ? statSync(profile.path).mode & 0o777 : 0o600,
+                        flag: "wx",
+                    });
+                    renameSync(temporary, profile.path);
+                }
+                finally {
+                    rmSync(temporary, { force: true });
+                }
+            }
+            restartRequired = true;
+        }
+        if (restartRequired)
+            env.PATH = `${dirname(installed)}${delimiter}${env.PATH ?? ""}`;
+        return {
+            status: "installed",
+            command: installed,
+            restartRequired,
+            manualPathRequired: profiles?.length === 0,
+            version: CLI_VERSION,
+        };
+    }
+    finally {
+        rmSync(cache, { recursive: true, force: true });
+    }
+}
+export function runInstall(options) {
+    try {
+        const result = ensureInstalled(options);
+        const message = result.manualPathRequired
+            ? `Balladeer is installed at ${result.command}. Add ${dirname(result.command)} to your shell PATH and reopen the terminal/coding agent. Automatic PATH editing is unavailable for this shell; this setup process can use the command now.`
+            : result.restartRequired
+                ? "Balladeer is installed for this user. Reopen your terminal and coding agent to load the new PATH. This setup process can use the command now."
+                : `Balladeer ${result.version} is available as the bare balladeer command.`;
+        options.write(options.json
+            ? JSON.stringify({
+                step: "install",
+                ...result,
+                status: result.manualPathRequired ? "path_pending" : result.status,
+                message,
+            }) + "\n"
+            : message + "\n");
+        return result.manualPathRequired && !options.allowPartial ? 4 : 0;
+    }
+    catch (error) {
+        const message = error instanceof InstallError
+            ? error.message
+            : "Installation could not access a required local file or command. Allow the reported installer operation and retry; no pairing has started.";
+        options.write(options.json
+            ? JSON.stringify({ step: "install", status: "blocked", message }) + "\n"
+            : message + "\n");
+        return 4;
+    }
+}

package/dist/release.d.ts

@@ -1,20 +1,8 @@
 /**
- * How to say "run this command again", in a way that actually runs it.
- *
- * The package name `balladeer` is taken on npm by an unrelated 0.0.x package
- * that installs a different program, and until the publish happens the version
- * this repository builds is not on the registry at all. So this command never
- * writes a registry invocation as a literal. It asks the server, which reads
- * the publication from one setting, and falls back to the checkout form
- * whenever it has not been told otherwise. A sentence that names a command a
- * person cannot run is worse than no sentence at all.
- *
- * What that setting no longer decides is the specifier. Nothing this product
- * hands a customer pins a version any more: a pinned line is what left legacy
- * customers running a months-old command, because the line in their config and
- * the line on their screen both named the version that was newest the day they
- * ran setup. The tag is resolved against the registry on every invocation, so a
- * publish reaches a machine at its next session start.
+ * Installed copies can always name their own durable command even when the
+ * server omits publication metadata. A source checkout retains its explicit
+ * build path until publication is known. Bootstrap and upgrade instructions
+ * use npx @latest separately; this helper describes ordinary command use.
  */
 /** What a person runs from the root of a built checkout. */
 export declare const CHECKOUT_COMMAND = "node packages/cli/dist/cli.js";

package/dist/release.js

@@ -1,22 +1,10 @@
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /**
- * How to say "run this command again", in a way that actually runs it.
- *
- * The package name `balladeer` is taken on npm by an unrelated 0.0.x package
- * that installs a different program, and until the publish happens the version
- * this repository builds is not on the registry at all. So this command never
- * writes a registry invocation as a literal. It asks the server, which reads
- * the publication from one setting, and falls back to the checkout form
- * whenever it has not been told otherwise. A sentence that names a command a
- * person cannot run is worse than no sentence at all.
- *
- * What that setting no longer decides is the specifier. Nothing this product
- * hands a customer pins a version any more: a pinned line is what left legacy
- * customers running a months-old command, because the line in their config and
- * the line on their screen both named the version that was newest the day they
- * ran setup. The tag is resolved against the registry on every invocation, so a
- * publish reaches a machine at its next session start.
+ * Installed copies can always name their own durable command even when the
+ * server omits publication metadata. A source checkout retains its explicit
+ * build path until publication is known. Bootstrap and upgrade instructions
+ * use npx @latest separately; this helper describes ordinary command use.
  */
 /** What a person runs from the root of a built checkout. */
 export const CHECKOUT_COMMAND = "node packages/cli/dist/cli.js";
@@ -30,6 +18,8 @@ export const PUBLISHED_SPECIFIER = "balladeer@latest";
  * version to name.
  */
 export function commandPrefix(publishedVersion) {
+    if (runningFromRegistryInstall())
+        return "balladeer";
     return publishedVersion === null || publishedVersion === undefined
         ? CHECKOUT_COMMAND
         : `npx -y ${PUBLISHED_SPECIFIER}`;

package/dist/store.d.ts

@@ -15,6 +15,8 @@ export type PendingPairing = Readonly<{
     workspaceChoice?: string;
 }>;
 export type StoredSession = Readonly<{
+    /** Claimed local create intent, not workspace identity or server authority. */
+    workspaceChoice?: string;
     controlPlane: string;
     sessionId: string;
     token: string;
@@ -76,6 +78,8 @@ export declare function credentialsPath(environment?: NodeJS.ProcessEnv): string
  */
 export declare function assertSafeStoreLocation(directory: string, environment?: NodeJS.ProcessEnv, cwd?: string): void;
 export declare function ensureStoreDirectory(environment?: NodeJS.ProcessEnv): string;
+/** Check actual write permission before requesting a pairing whose secret must be saved. */
+export declare function assertStoreWritable(environment?: NodeJS.ProcessEnv): void;
 export declare function readCredentials(environment?: NodeJS.ProcessEnv): Credentials;
 /**
  * Atomic, and never through a path an attacker could have pre-planted: the

package/dist/store.js

@@ -86,12 +86,38 @@ function assertPrivate(path, kind) {
         throw new StoreError("credential_store_unsafe", `${path} is readable by other users. Run: chmod ${kind === "directory" ? "700" : "600"} ${path}`);
     }
 }
+function storeAccessError(error, path, operation) {
+    if (error instanceof StoreError)
+        return error;
+    const code = error?.code;
+    const permissionDenied = code === "EACCES" || code === "EPERM";
+    return new StoreError(operation === "read" ? "credential_store_unreadable" : "credential_store_unwritable", permissionDenied
+        ? `Balladeer cannot ${operation} its local credential store at ${path}. Allow this command to access that private folder in your terminal or coding agent, then rerun the same command. Existing saved credentials were not replaced.`
+        : `Balladeer could not ${operation} its local credential store at ${path} (${code ?? "filesystem error"}). Check that this location is a private, accessible directory, then retry. Existing saved credentials were not replaced.`, { cause: error });
+}
 export function ensureStoreDirectory(environment = process.env) {
     const directory = configHome(environment);
-    assertSafeStoreLocation(directory, environment);
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    assertPrivate(directory, "directory");
-    return directory;
+    try {
+        assertSafeStoreLocation(directory, environment);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        assertPrivate(directory, "directory");
+        return directory;
+    }
+    catch (error) {
+        throw storeAccessError(error, directory, "write");
+    }
+}
+/** Check actual write permission before requesting a pairing whose secret must be saved. */
+export function assertStoreWritable(environment = process.env) {
+    const probe = `.write-check-${randomBytes(8).toString("hex")}`;
+    const path = join(configHome(environment), probe);
+    try {
+        writeStoreFile(probe, "", environment);
+        unlinkSync(path);
+    }
+    catch (error) {
+        throw storeAccessError(error, configHome(environment), "write");
+    }
 }
 export function readCredentials(environment = process.env) {
     const path = credentialsPath(environment);
@@ -101,9 +127,10 @@ export function readCredentials(environment = process.env) {
         raw = readFileSync(path, "utf8");
     }
     catch (error) {
-        if (error instanceof StoreError)
-            throw error;
-        return { ...EMPTY, pendingPairings: [], sessions: [], agents: [] };
+        if (error?.code === "ENOENT") {
+            return { ...EMPTY, pendingPairings: [], sessions: [], agents: [] };
+        }
+        throw storeAccessError(error, path, "read");
     }
     try {
         const parsed = JSON.parse(raw);
@@ -164,9 +191,7 @@ export function writeStoreFile(fileName, contents, environment = process.env) {
         catch {
             // The temporary file may never have been created.
         }
-        if (error instanceof StoreError)
-            throw error;
-        throw new StoreError("credential_store_unwritable", `Balladeer could not write ${path}: ${error instanceof Error ? error.message : "unknown reason"}`, { cause: error });
+        throw storeAccessError(error, path, "write");
     }
 }
 /** Origins, not URL strings, so `https://host/../` cannot alias a stored entry. */

package/dist/wire.d.ts

@@ -5,10 +5,10 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.3";
+export declare const CLI_VERSION = "1.0.5";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.3";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.5";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.3";
+export const CLI_VERSION = "1.0.5";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,