@agentcomms/whatsapp 0.13.0 → 0.13.1

package/dist/{sync-fzUQKMxy.mjs → sync-DrWJVoXp.mjs}

@@ -1,19 +1,34 @@
 import { C as unknown, S as union, b as strictObject, c as boolean, h as number, i as _enum, m as looseObject, n as datetime, p as literal, s as array, x as string, y as record } from "./iso-USuVU_sk.mjs";
 import { access, chmod, constants, link, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, utimes } from "node:fs/promises";
-import path, { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import path, { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { domainToASCII, fileURLToPath, pathToFileURL } from "node:url";
 import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { styleText } from "node:util";
 import { homedir, platform, userInfo } from "node:os";
-import { constants as constants$1 } from "node:fs";
+import { styleText } from "node:util";
+import { accessSync, constants as constants$1, readFileSync, realpathSync, statSync } from "node:fs";
 import { execFile, spawn } from "node:child_process";
 //#endregion
 //#region src/version.ts
 /** The package version, read from package.json at build time. */
-const VERSION$1 = "0.13.0";
+const VERSION$1 = "0.13.1";
+//#endregion
+//#region src/caller.ts
+/** This package's name, as its manifest has it. */
+const PACKAGE_NAME = "@agentcomms/whatsapp";
+/**
+* This package as core locates its commands from (CONTRIBUTING.md, "Telling a person what to run"; design 2026-10-04,
+* D1): a module of its own, whose nearest manifest is this package's. Run from a checkout's source it is this file, and
+* a command runs `src/cli.ts`; built, it is a file of `dist`, and a command runs the manifest's bin. Either way the
+* program is this process's Node, which has to be in this package's own `engines.node` range — narrower than core's —
+* or there is no command, and the reason names the range.
+*/
+const CALLER = Object.freeze({
+	url: import.meta.url,
+	packageName: PACKAGE_NAME
+});
 //#endregion
-//#region ../core/dist/update-check-C8sNjCez.mjs
+//#region ../core/dist/update-check-BPwwmUCi.mjs
 /**
 * Every failure a user or an agent can act on carries a specific, stable code from this registry, a message, an
 * optional one-line hint and structured `details`. The code decides the process exit status; agents and skills branch
@@ -804,7 +819,7 @@ const CHANNEL_SNAPSHOT = [
 				guarantee: {
 					ceiling: "code",
 					floor: "code",
-					why: "Resend has no read-only key, and a full-access key can also manage domains and keys: read mode, and send mode's limit to sending, are enforced by agent-resend's own code. A sending-access key can only send, and Resend enforces that."
+					why: "Resend has no read-only key, and a full-access key can also manage domains and keys: read mode, and send mode's limit to sending, are enforced by this package's own code. A sending-access key can only send, and Resend enforces that."
 				}
 			},
 			narrowing: [{
@@ -924,25 +939,6 @@ function manifestOf(channel) {
 function accountChannels() {
 	return MANIFESTS.filter((manifest) => manifest.accounts !== void 0);
 }
-/**
-* Words as a list a person reads: `a`, `a or b`, `a, b or c` — with `oxford`, `a, b, or c` once there are three.
-*/
-function listed(words, conjunction, options = {}) {
-	if (words.length <= 1) return words.join("");
-	const last = words.at(-1);
-	const rest = words.slice(0, -1);
-	return `${rest.join(", ")}${options.oxford && rest.length > 1 ? "," : ""} ${conjunction} ${last}`;
-}
-/**
-* Every channel's own approve command, quoted: "`agent-gmail approve` or `agent-slack approve`".
-*
-* `sending` keeps only the channels whose accounts can be in `send`: the commands that can have prepared a send. A
-* channel that never sends — WhatsApp — has an approve command for the changes its `mcp install` and `mcp prune`
-* make, and naming it where the approval in hand is a send would send a person to a command that never prepared one.
-*/
-function channelApproveCommands(options = {}) {
-	return listed(accountChannels().filter((manifest) => options.sending !== true || manifest.accounts?.modes.includes("send") === true).flatMap((manifest) => manifest.approve ? [`\`${manifest.approve}\``] : []), "or");
-}
 /** The noun for one account on `channel` — `mailbox`, `workspace` — or `account` for a channel that names none. */
 function accountNoun(channel) {
 	return manifestOf(channel)?.accounts?.noun ?? "account";
@@ -960,106 +956,20 @@ function narrowingOwner(option) {
 	return MANIFESTS.find((manifest) => manifest.narrowing?.some((narrowing) => narrowing.option === option));
 }
 /**
-* The command that connects a mailbox, for a hint about there being none: the `inbox add` of the channel whose
-* accounts are mailboxes, in the `inboxes` map.
+* How a mailbox is connected, for a hint about there being none: the `inbox add` of the channel whose accounts are
+* mailboxes, in the `inboxes` map — named in words, "Gmail's inbox add", never as a command. Core does not have that
+* channel's CLI, and finds it only among this machine's registrations (CUE-403); a hint made where none were read must
+* not invent the command from the manifest's binary.
 */
-function connectMailboxCommand() {
+function connectMailboxWords() {
 	const mail = accountChannels().find((manifest) => manifest.accounts?.map === "inboxes");
-	return mail ? `${mail.binary} inbox add` : void 0;
-}
-/** Crockford-style alphabet without I, L, O and U, so ids and challenges survive being read aloud or retyped. */
-const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-function randomString(length) {
-	const bytes = randomBytes(length);
-	let out = "";
-	for (let i = 0; i < length; i += 1) out += ALPHABET[(bytes[i] ?? 0) & 31];
-	return out;
-}
-/** `ap_` + 26 characters: 130 random bits. Validated before an id ever names a file. */
-const APPROVAL_ID_PATTERN = /^ap_[0-9A-HJKMNP-TV-Z]{26}$/;
-const PLAN_TOKEN_PATTERN = /^pl_[0-9A-HJKMNP-TV-Z]{26}$/;
-function newApprovalId() {
-	return `ap_${randomString(26)}`;
-}
-function newPlanToken() {
-	return `pl_${randomString(26)}`;
-}
-const CHALLENGE_LETTERS = "ABCDEFGHJKMNPQRSTVWXYZ";
-/** A short challenge a human types back to approve: letters only, no look-alikes. */
-function newChallenge(length = 4) {
-	let out = "";
-	for (let i = 0; i < length; i += 1) out += CHALLENGE_LETTERS[randomInt(22)];
-	return out;
-}
-/** Challenges are stored only as hashes, so no listing or tool result can reveal one. */
-function hashChallenge(challenge) {
-	return createHash("sha256").update(challenge.trim().toUpperCase()).digest("hex");
-}
-/** Case-insensitive, constant-time comparison of an answer with a stored challenge hash. */
-function challengeMatches(answer, storedHash) {
-	const a = Buffer.from(hashChallenge(answer), "hex");
-	const b = Buffer.from(storedHash, "hex");
-	return a.length === b.length && timingSafeEqual(a, b);
-}
-function okEnvelope(data) {
-	return {
-		ok: true,
-		schemaVersion: 1,
-		data
-	};
-}
-function errorEnvelope(error) {
-	const body = {
-		code: error.code,
-		message: error.message
-	};
-	if (error.hint !== void 0) body.hint = error.hint;
-	if (error.details !== void 0) body.details = error.details;
-	return {
-		ok: false,
-		schemaVersion: 1,
-		error: body
-	};
-}
-const defaultStreams = {
-	stdout: process.stdout,
-	stderr: process.stderr,
-	stdin: process.stdin
-};
-function colorEnabled(env, stream, flag) {
-	if (flag === false) return false;
-	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
-	if (env.TERM === "dumb") return false;
-	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "0") return true;
-	return Boolean(stream.isTTY);
-}
-/** True when a human could answer a prompt: both ends are terminals, no --json/--no-input, not CI. */
-function canPrompt(env, streams, options) {
-	if (options.json || options.noInput) return false;
-	if (env.CI && env.CI !== "0" && env.CI !== "false") return false;
-	return Boolean(streams.stdin?.isTTY && streams.stdout.isTTY);
-}
-/** Environment variables well-known coding agents set. Used only as a speed bump, never as a security boundary. */
-const AGENT_MARKERS = [
-	"CLAUDECODE",
-	"CLAUDE_CODE_ENTRYPOINT",
-	"CODEX_SANDBOX",
-	"CODEX_HOME",
-	"CURSOR_AGENT",
-	"GEMINI_CLI",
-	"AGENT_COMMS_AGENT"
-];
-function agentMarker(env) {
-	for (const name of AGENT_MARKERS) if (env[name] !== void 0 && env[name] !== "") return name;
-	return null;
-}
-function paint(color, format, text) {
-	return color ? styleText(format, text, { validateStream: false }) : text;
+	return mail ? `${mail.label}'s inbox add` : void 0;
 }
 /**
 * A command line for a person to copy and run, each word quoted only where the shell it is pasted into would need it.
-* Every command this package prints to be run — a change to run again with its approval, a folder to take out, an
-* entry to register again or remove — is quoted here, so no printer quotes for a shell of its own.
+* Every command this suite prints to be run — a change to run again with its approval, a folder to take out, an entry
+* to register again or remove — is quoted here, when the locator or `externalCommand` makes it, so no printer quotes
+* for a shell of its own.
 *
 * Everywhere but Windows that shell is a POSIX one, and a word goes in single quotes, inside which nothing is special
 * but the quote itself. Windows has two shells, and neither reads single quotes that way: cmd.exe does not take them
@@ -1098,31 +1008,58 @@ function paint(color, format, text) {
 *   hint's `--force` replaced it — and before that, a word quoted for PowerShell's single quotes, which cmd.exe reads
 *   as characters, ran `whoami` from a server named `$x&whoami&`. See `commandAsJson` for why the JSON runs nothing.
 *
+* - The program itself has to be left as it is. Quoted, it is a string to PowerShell rather than a command — PowerShell
+*   runs a quoted program only after `&`, which cmd.exe reads as the end of a command — so a program whose path needs
+*   quotes, as `C:\Program Files\nodejs\node.exe` does, leaves the command with no line either (CUE-403).
+*
 * Everywhere else there is always a line: single quotes make any word safe.
+*
+* Not a way to make a command for a person: what it returns is not one, and nothing that shows a command takes it. One
+* of this suite's own commands comes from `locateCliCommand`, any other program's from `externalCommand`, and each of
+* them quotes its words here.
 */
-function shellCommand(words, platform = process.platform) {
+function quoteCommand(words, platform) {
 	if (platform !== "win32") return {
 		words,
 		line: words.map(posixShellWord).join(" "),
 		platform
 	};
 	const printed = words.map(windowsShellWord);
+	const programBare = words.length === 0 || printed[0] === words[0];
 	return {
 		words,
-		line: printed.includes(null) ? null : printed.join(" "),
+		line: printed.includes(null) || !programBare ? null : printed.join(" "),
 		platform
 	};
 }
-/** The same command with more words at its end — the approval it is to be run again with — for the same shell. */
-function withWords(command, ...more) {
-	return shellCommand([...command.words, ...more], command.platform);
+/**
+* A printed command's line with words the agent is to fill in — a placeholder such as `<folder>`, printed as written,
+* never quoted as a word — before the command's first `--`, where the CLI still reads them as options. Null when the
+* command has no line.
+*/
+function quotedLineWithWordsToFill(command, ...toFill) {
+	if (command.line === null) return null;
+	const sentinel = command.words.indexOf("--");
+	if (sentinel < 0) return [command.line, ...toFill].join(" ");
+	const word = command.platform === "win32" ? windowsShellWord : posixShellWord;
+	const printed = command.words.map((each) => word(each));
+	return [
+		...printed.slice(0, sentinel),
+		...toFill,
+		...printed.slice(sentinel)
+	].join(" ");
+}
+/** Whether a Windows command has no line because its program's path needs quotes, which PowerShell would not run. */
+function programNeedsQuotes(command) {
+	const [program] = command.words;
+	return command.platform === "win32" && program !== void 0 && windowsShellWord(program) !== program;
 }
 function posixShellWord(word) {
 	return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
 }
 /**
 * The word as cmd.exe, Windows PowerShell and PowerShell 7 all hand it to a program, or null when no printing of it
-* does (see `shellCommand`). Bare: a plain option, or ordinary characters that do not start like a number.
+* does (see `quoteCommand`). Bare: a plain option, or ordinary characters that do not start like a number.
 */
 function windowsShellWord(word) {
 	if (/^(?:--?[A-Za-z][A-Za-z0-9-]*|(?!\+?\.?\d)[\w+=:./\\][\w@+=:./\\-]*)$/.test(word)) return word;
@@ -1160,140 +1097,189 @@ function commandAsJson(words) {
 }
 /** What is said beside a command shown as JSON. */
 const TO_TYPE = "the command's words, written as JSON: one of them cannot be quoted the same way for cmd.exe and for PowerShell, so type the command yourself, with that word quoted for the shell you use";
-/** A command in backticks, for a sentence — as its words in JSON, saying it has to be typed, when it has no line. */
-function inlineCommand(command) {
-	return command.line === null ? `\`${commandAsJson(command.words)}\` (${TO_TYPE})` : `\`${command.line}\``;
-}
-/** A command as text of its own — a list's line, a field's value — or its words in JSON, saying it has to be typed. */
-function commandText(command) {
-	return command.line === null ? `${commandAsJson(command.words)} (${TO_TYPE})` : command.line;
+/** What is said beside a command shown as JSON because its program's path needs quotes. */
+const TO_TYPE_PROGRAM = "the command's words, written as JSON: the program's path needs quotes, and PowerShell runs a quoted program only after `&`, which cmd.exe does not accept, so type the command yourself, with each word quoted for the shell you use and, in PowerShell, `&` before the program";
+function toType(command) {
+	return programNeedsQuotes(command) ? TO_TYPE_PROGRAM : TO_TYPE;
 }
-/** Writes a successful result: the envelope with --json, otherwise the human rendering. */
-function writeResult(data, options, human, streams = defaultStreams) {
-	if (options.json) {
-		streams.stdout.write(`${JSON.stringify(okEnvelope(data))}\n`);
-		return;
-	}
-	const text = human(data);
-	if (text) streams.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
-}
-/** Writes an error and returns the exit code to use. */
-function writeError(error, options, streams = defaultStreams) {
-	const commsError = toCommsError(error);
-	if (options.json) streams.stdout.write(`${JSON.stringify(errorEnvelope(commsError))}\n`);
-	else {
-		streams.stderr.write(`${paint(options.color, "red", "error")}: ${commsError.message}\n`);
-		if (commsError.hint) streams.stderr.write(`${paint(options.color, "dim", "hint")}: ${commsError.hint}\n`);
-	}
-	return commsError.exitCode;
+/** Quoted words in backticks, for a sentence — as words in JSON, saying it has to be typed, when there is no line. */
+function inlineQuoted(command) {
+	return command.line === null ? `\`${commandAsJson(command.words)}\` (${toType(command)})` : `\`${command.line}\``;
 }
-/** Runs a command body and exits with the documented code. Unexpected errors keep only their message. */
-async function runCommand(options, body, streams = defaultStreams) {
-	try {
-		await body();
-		return EXIT_CODES.OK;
-	} catch (error) {
-		return writeError(error, options, streams);
-	}
+/** Quoted words as text of their own — a list's line, a field's value — or as words in JSON, saying to type them. */
+function quotedText(command) {
+	return command.line === null ? `${commandAsJson(command.words)} (${toType(command)})` : command.line;
 }
 /**
-* The first two steps of `requirePerson` — an agent is refused, then anything without a terminal — for a command
-* whose code is not its own to make up.
-*
-* `agentcomms approve` asks for a code the approval store issued and will check, so it cannot use `askChallenge`;
-* but it refuses in exactly the same order and words, because it is the same gate.
+* The same command with words the agent is to fill in — a placeholder such as `<folder>` — before its first `--`: for
+* showing as words in JSON when the command has no line. With a line, `quotedLineWithWordsToFill` prints them as they
+* are written instead, never quoted as a word.
 */
-function refuseUnlessPerson(env, streams, gate) {
-	const marker = agentMarker(env);
-	if (marker) throw new CommsError("LOOSENING_REFUSED", gate.refusedToAgent, {
-		hint: `Ask the user to run \`${gate.command}\` in their own terminal.`,
-		details: { marker }
-	});
-	const prompting = {};
-	if (gate.json !== void 0) prompting.json = gate.json;
-	if (gate.noInput !== void 0) prompting.noInput = gate.noInput;
-	if (!canPrompt(env, streams, prompting)) throw new CommsError("LOOSENING_REFUSED", gate.refusedWithoutTerminal, { hint: `Run \`${gate.command}\` directly in a terminal.` });
+function quotedWithWordsToFill(command, toFill) {
+	const sentinel = command.words.indexOf("--");
+	const at = sentinel < 0 ? command.words.length : sentinel;
+	return quoteCommand([
+		...command.words.slice(0, at),
+		...toFill,
+		...command.words.slice(at)
+	], command.platform);
 }
-/**
-* One table of dangerous characters, shared by the inbound sanitiser (which strips them from sender-controlled text)
-* and the preview renderer (which makes them visible), so the two can never disagree.
-*/
-/** Zero-width and formatting characters, bidi controls, variation selectors and Unicode tag characters. */
-const INVISIBLE_RANGES = [
-	[173, 173],
-	[847, 847],
-	[1564, 1564],
-	[4447, 4448],
-	[6068, 6069],
-	[6155, 6159],
-	[8203, 8207],
-	[8232, 8233],
-	[8234, 8238],
-	[8288, 8292],
-	[8294, 8303],
-	[12644, 12644],
-	[65024, 65039],
-	[65279, 65279],
-	[65440, 65440],
-	[917504, 917631]
-];
-function isInvisible(codePoint) {
-	for (const [from, to] of INVISIBLE_RANGES) if (codePoint >= from && codePoint <= to) return true;
-	return false;
+/** Crockford-style alphabet without I, L, O and U, so ids and challenges survive being read aloud or retyped. */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function randomString(length) {
+	const bytes = randomBytes(length);
+	let out = "";
+	for (let i = 0; i < length; i += 1) out += ALPHABET[(bytes[i] ?? 0) & 31];
+	return out;
 }
-/**
-* C0 controls except tab and newline (ESC, and so every ANSI/OSC sequence, starts here), DEL, and C1 controls (CSI
-* among them). A lone carriage return counts: it moves a terminal cursor back over text already printed.
-*/
-function isControl(codePoint) {
-	if (codePoint === 9 || codePoint === 10) return false;
-	return codePoint < 32 || codePoint === 127 || codePoint >= 128 && codePoint <= 159;
+/** `ap_` + 26 characters: 130 random bits. Validated before an id ever names a file. */
+const APPROVAL_ID_PATTERN = /^ap_[0-9A-HJKMNP-TV-Z]{26}$/;
+const PLAN_TOKEN_PATTERN = /^pl_[0-9A-HJKMNP-TV-Z]{26}$/;
+function newApprovalId() {
+	return `ap_${randomString(26)}`;
 }
-function isDangerous(codePoint) {
-	return isControl(codePoint) || isInvisible(codePoint);
+function newPlanToken() {
+	return `pl_${randomString(26)}`;
 }
-/**
-* Strips control characters (ESC, CSI, OSC and the rest), DEL, lone carriage returns, zero-width, bidi-control and tag
-* characters from sender-controlled text; returns the text and how many were removed. CRLF becomes LF first.
-*
-* This lives beside the table rather than in the sanitiser because `neutralise` needs it too, and the two must not
-* drift: a pattern that looks for `</untrusted-content` cannot see it through a zero-width space, so stripping
-* has to happen before any such pattern runs, on every path, not only on the ones that render a body.
-*/
-function stripInvisible(text) {
-	let removed = 0;
+const CHALLENGE_LETTERS = "ABCDEFGHJKMNPQRSTVWXYZ";
+/** A short challenge a human types back to approve: letters only, no look-alikes. */
+function newChallenge(length = 4) {
 	let out = "";
-	for (const char of text.replace(/\r\n/g, "\n")) if (isDangerous(char.codePointAt(0) ?? 0)) removed += 1;
-	else out += char;
+	for (let i = 0; i < length; i += 1) out += CHALLENGE_LETTERS[randomInt(22)];
+	return out;
+}
+/** Challenges are stored only as hashes, so no listing or tool result can reveal one. */
+function hashChallenge(challenge) {
+	return createHash("sha256").update(challenge.trim().toUpperCase()).digest("hex");
+}
+/** Case-insensitive, constant-time comparison of an answer with a stored challenge hash. */
+function challengeMatches(answer, storedHash) {
+	const a = Buffer.from(hashChallenge(answer), "hex");
+	const b = Buffer.from(storedHash, "hex");
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+function okEnvelope(data) {
 	return {
-		text: out,
-		removed
+		ok: true,
+		schemaVersion: 1,
+		data
+	};
+}
+function errorEnvelope(error) {
+	const body = {
+		code: error.code,
+		message: error.message
+	};
+	if (error.hint !== void 0) body.hint = error.hint;
+	if (error.details !== void 0) body.details = error.details;
+	return {
+		ok: false,
+		schemaVersion: 1,
+		error: body
 	};
 }
 const APP_DIR_NAME = "agent-communications";
-/**
-* Where everything lives. `AGENT_COMMS_CONFIG_DIR` wins; then `XDG_CONFIG_HOME` (honoured on macOS too, because that is
-* where agents and people look first); then `~/.config` on macOS and Linux, `%APPDATA%` on Windows.
-*
-* On Windows, state and the file secret store go under `%LOCALAPPDATA%` rather than beside the config: `%APPDATA%` is
-* the roaming profile, which a domain copies between machines — and refresh tokens, approvals and audit records are
-* exactly what should not travel that way. An explicit `AGENT_COMMS_CONFIG_DIR` keeps everything together, because
-* someone who names a directory means that directory.
-*/
+/** The five suite directories a CLI can pin independently. */
+const PATH_OPTIONS = [
+	{
+		key: "configDir",
+		option: "config-dir",
+		flag: "--config-dir"
+	},
+	{
+		key: "stateDir",
+		option: "state-dir",
+		flag: "--state-dir"
+	},
+	{
+		key: "dataDir",
+		option: "data-dir",
+		flag: "--data-dir"
+	},
+	{
+		key: "secretsDir",
+		option: "secrets-dir",
+		flag: "--secrets-dir"
+	},
+	{
+		key: "downloadsDir",
+		option: "downloads-dir",
+		flag: "--downloads-dir"
+	}
+];
+/**
+* Words with the five path options and their values taken out where an option parser would read them — before the
+* first `--`, in both the `--x value` and `--x=value` forms — and every word from `--` on kept as it is.
+*
+* What a registered entry is recognised by. A pinned folder is a folder: `/tmp/@agentcomms/slack`, or one ending in
+* `packages/slack/src/cli.ts`, read as a package or an entry, made a Gmail registration Slack's. `dangling` says a
+* spaced option had no value before `--` or the end, which is a broken entry rather than one to guess about.
+*/
+function withoutPathOptions(words) {
+	const flags = PATH_OPTIONS.map(({ flag }) => flag);
+	const kept = [];
+	let dangling = false;
+	for (let index = 0; index < words.length; index += 1) {
+		const word = words[index];
+		if (word === "--") {
+			kept.push(...words.slice(index));
+			break;
+		}
+		if (flags.includes(word)) {
+			const value = words[index + 1];
+			if (value === void 0 || value === "--") dangling = true;
+			else index += 1;
+			continue;
+		}
+		if (flags.some((flag) => word.startsWith(`${flag}=`))) continue;
+		kept.push(word);
+	}
+	return {
+		words: kept,
+		dangling
+	};
+}
+/**
+* Where everything lives. `AGENT_COMMS_CONFIG_DIR` wins; then `XDG_CONFIG_HOME` (honoured on macOS too, because that is
+* where agents and people look first); then `~/.config` on macOS and Linux, `%APPDATA%` on Windows.
+*
+* On Windows, state and the file secret store go under `%LOCALAPPDATA%` rather than beside the config: `%APPDATA%` is
+* the roaming profile, which a domain copies between machines — and refresh tokens, approvals and audit records are
+* exactly what should not travel that way. An explicit `AGENT_COMMS_CONFIG_DIR` keeps everything together, because
+* someone who names a directory means that directory.
+*/
 function resolvePaths(options = {}) {
+	return resolvePathIdentity(options).paths;
+}
+/** Resolves the environment/default identity, then overlays each explicit pin without re-deriving any sibling. */
+function resolvePathIdentity(options = {}) {
 	const env = options.env ?? process.env;
 	const platform = options.platform ?? process.platform;
 	const home = options.home ?? homeOf(env, platform);
 	const configDir = resolve(env.AGENT_COMMS_CONFIG_DIR || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, "agent-communications") : platform === "win32" ? join(env.APPDATA || join(home, "AppData", "Roaming"), "agent-communications") : join(home, ".config", "agent-communications")));
 	const explicitConfigDir = Boolean(env.AGENT_COMMS_CONFIG_DIR);
 	const localRoot = platform === "win32" && !explicitConfigDir ? join(env.LOCALAPPDATA || join(home, "AppData", "Local"), APP_DIR_NAME) : configDir;
-	return {
+	const derived = {
 		configDir,
 		stateDir: resolve(env.AGENT_COMMS_STATE_DIR || join(localRoot, "state")),
 		secretsDir: resolve(join(localRoot, "secrets")),
 		dataDir: resolve(env.AGENT_COMMS_DATA_DIR || (platform === "win32" ? join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "agent-communications") : env.XDG_DATA_HOME ? join(env.XDG_DATA_HOME, "agent-communications") : join(home, ".local", "share", "agent-communications"))),
 		downloadsDir: resolve(join(home, "Downloads", APP_DIR_NAME))
 	};
+	const pathOverrides = {};
+	for (const { key } of PATH_OPTIONS) {
+		const value = options.pathOverrides?.[key];
+		if (value === void 0) continue;
+		if (value.length === 0) throw new TypeError(`${key} cannot be empty`);
+		pathOverrides[key] = resolve(value);
+	}
+	return {
+		paths: {
+			...derived,
+			...pathOverrides
+		},
+		pathOverrides: Object.freeze(pathOverrides)
+	};
 }
 /**
 * The home the environment names, which is where Node's own `homedir()` looks for the running process — `HOME`, or
@@ -1363,6 +1349,294 @@ function shortenHome(path, home, platform = process.platform) {
 function homeDirectory(env = process.env) {
 	return env.HOME || env.USERPROFILE || homedir();
 }
+const defaultStreams = {
+	stdout: process.stdout,
+	stderr: process.stderr,
+	stdin: process.stdin
+};
+/** Converts the shared parser's five global option values into independently applied core path pins. */
+function pathOverridesFromCliOptions(values) {
+	const overrides = {};
+	for (const { key, option, flag } of PATH_OPTIONS) {
+		const value = values[option];
+		if (value === void 0) continue;
+		if (value.length === 0) throw new CommsError("USAGE", `${flag} needs a non-empty directory`);
+		overrides[key] = value;
+	}
+	return overrides;
+}
+/** Inserts generated option words immediately before the first end-of-options sentinel. */
+function insertWordsBeforeSentinel(words, ...inserted) {
+	const sentinel = words.indexOf("--");
+	const at = sentinel < 0 ? words.length : sentinel;
+	return [
+		...words.slice(0, at),
+		...inserted,
+		...words.slice(at)
+	];
+}
+/**
+* Removes the named options only where the CLI parser can see them: before the first `--`. Both `--x value` and
+* `--x=value` are removed. The sentinel and every positional word after it are byte-for-byte data.
+*/
+function withoutOptionsBeforeSentinel(words, flags) {
+	const kept = [];
+	for (let index = 0; index < words.length; index += 1) {
+		const word = words[index];
+		if (word === "--") {
+			kept.push(...words.slice(index));
+			break;
+		}
+		const spaced = flags.find((flag) => word === flag);
+		if (spaced !== void 0) {
+			const value = words[index + 1];
+			if (value === void 0 || value === "--") throw new CommsError("USAGE", `${spaced} needs a value before --`);
+			index += 1;
+			continue;
+		}
+		if (flags.some((flag) => word.startsWith(`${flag}=`))) continue;
+		kept.push(word);
+	}
+	return kept;
+}
+/**
+* Replaces every pre-sentinel suite path option with one canonical pin per supplied directory. `insertAt` counts
+* words after the old pins are removed: zero puts global options after the executable held elsewhere, one puts them
+* after an entry/package word. Downloads are included only when the caller supplies that pin.
+*/
+function normalizePathOptionWords(words, pins, insertAt) {
+	const stripped = withoutOptionsBeforeSentinel(words, PATH_OPTIONS.map(({ flag }) => flag));
+	const sentinel = stripped.indexOf("--");
+	const optionsEnd = sentinel < 0 ? stripped.length : sentinel;
+	if (!Number.isSafeInteger(insertAt) || insertAt < 0 || insertAt > optionsEnd) throw new TypeError(`path-option insertion point ${insertAt} is outside the option words`);
+	const pathWords = PATH_OPTIONS.flatMap(({ key, flag }) => {
+		const value = pins[key];
+		if (value === void 0) return [];
+		if (value.length === 0) throw new CommsError("USAGE", `${flag} needs a non-empty directory`);
+		return [flag, resolve(value)];
+	});
+	return [
+		...stripped.slice(0, insertAt),
+		...pathWords,
+		...stripped.slice(insertAt)
+	];
+}
+function colorEnabled(env, stream, flag) {
+	if (flag === false) return false;
+	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+	if (env.TERM === "dumb") return false;
+	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "0") return true;
+	return Boolean(stream.isTTY);
+}
+/** True when a human could answer a prompt: both ends are terminals, no --json/--no-input, not CI. */
+function canPrompt(env, streams, options) {
+	if (options.json || options.noInput) return false;
+	if (env.CI && env.CI !== "0" && env.CI !== "false") return false;
+	return Boolean(streams.stdin?.isTTY && streams.stdout.isTTY);
+}
+/** Environment variables well-known coding agents set. Used only as a speed bump, never as a security boundary. */
+const AGENT_MARKERS = [
+	"CLAUDECODE",
+	"CLAUDE_CODE_ENTRYPOINT",
+	"CODEX_SANDBOX",
+	"CODEX_HOME",
+	"CURSOR_AGENT",
+	"GEMINI_CLI",
+	"AGENT_COMMS_AGENT"
+];
+function agentMarker(env) {
+	for (const name of AGENT_MARKERS) if (env[name] !== void 0 && env[name] !== "") return name;
+	return null;
+}
+function paint(color, format, text) {
+	return color ? styleText(format, text, { validateStream: false }) : text;
+}
+/** A command in backticks, for a sentence — as its words in JSON, saying it has to be typed, when it has no line. */
+function inlineCommand(command) {
+	return inlineQuoted(command);
+}
+/** A command as text of its own — a list's line, a field's value — or its words in JSON, saying it has to be typed. */
+function commandText(command) {
+	return quotedText(command);
+}
+/**
+* A command's line with words the agent is to fill in — a placeholder such as `<folder>`, printed as written, never
+* quoted as a word — before the command's first `--`, where the CLI still reads them as options. Null when the
+* command has no line.
+*/
+function lineWithWordsToFill(command, ...toFill) {
+	return quotedLineWithWordsToFill(command, ...toFill);
+}
+/** Writes a successful result: the envelope with --json, otherwise the human rendering. */
+function writeResult(data, options, human, streams = defaultStreams) {
+	if (options.json) {
+		streams.stdout.write(`${JSON.stringify(okEnvelope(data))}\n`);
+		return;
+	}
+	const text = human(data);
+	if (text) streams.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+/** Writes an error and returns the exit code to use. */
+function writeError(error, options, streams = defaultStreams) {
+	const commsError = toCommsError(error);
+	if (options.json) streams.stdout.write(`${JSON.stringify(errorEnvelope(commsError))}\n`);
+	else {
+		streams.stderr.write(`${paint(options.color, "red", "error")}: ${commsError.message}\n`);
+		if (commsError.hint) streams.stderr.write(`${paint(options.color, "dim", "hint")}: ${commsError.hint}\n`);
+	}
+	return commsError.exitCode;
+}
+/** Runs a command body and exits with the documented code. Unexpected errors keep only their message. */
+async function runCommand(options, body, streams = defaultStreams) {
+	try {
+		await body();
+		return EXIT_CODES.OK;
+	} catch (error) {
+		return writeError(error, options, streams);
+	}
+}
+/**
+* The first two steps of `requirePerson` — an agent is refused, then anything without a terminal — for a command
+* whose code is not its own to make up.
+*
+* `agentcomms approve` asks for a code the approval store issued and will check, so it cannot use `askChallenge`;
+* but it refuses in exactly the same order and words, because it is the same gate.
+*/
+function refuseUnlessPerson(env, streams, gate) {
+	const marker = agentMarker(env);
+	if (marker) throw new CommsError("LOOSENING_REFUSED", gate.refusedToAgent, {
+		hint: gateSentence(gate.command, (command) => `Ask the user to run ${command} in their own terminal.`),
+		details: { marker }
+	});
+	const prompting = {};
+	if (gate.json !== void 0) prompting.json = gate.json;
+	if (gate.noInput !== void 0) prompting.noInput = gate.noInput;
+	if (!canPrompt(env, streams, prompting)) throw new CommsError("LOOSENING_REFUSED", gate.refusedWithoutTerminal, { hint: gateSentence(gate.command, (command) => `Run ${command} directly in a terminal.`) });
+}
+/** A gate's command in a sentence: in backticks, or the sentence saying why there is none in its place. */
+function gateSentence(command, say) {
+	return "message" in command ? command.message : say(inlineCommand(command));
+}
+/**
+* The handoffs a store or a deep function was given (`core.handoffs`, handed on by `openCore`), for the command one of
+* its refusals names. A programming error when there are none: the package that opened core did not give it its
+* caller (`openCore({ caller })`), and there is no command to print in its place — not a bare name, not a guess.
+*/
+function requiredHandoffs(handoffs) {
+	if (handoffs === void 0) throw new TypeError("core was opened without its caller, so it cannot locate a command: pass openCore({ caller })");
+	return handoffs;
+}
+/** Whether a handoff is a command to run, rather than the sentence saying why there is none. */
+function isCommand(handoff) {
+	return !("message" in handoff);
+}
+/**
+* A handoff as a value of its own — a list's line, a field's value: the command's line, or its words as JSON with what
+* to do when no line is safe in every Windows shell; or, with no command, the sentence saying why.
+*/
+function handoffText(handoff) {
+	return isCommand(handoff) ? commandText(handoff) : handoff.message;
+}
+/**
+* A remedy, a line per argument: one part, or the parts of one line in order — `[remove, ', then add it again']`.
+* A command is shown as `handoffText` shows it: its line, its words as JSON with what to do when no Windows line is
+* safe, or why there is none here.
+*/
+function remedy(...lines) {
+	const part = (each) => typeof each === "string" ? each : handoffText(each);
+	return lines.map((line) => Array.isArray(line) ? line.map(part).join("") : part(line)).join("\n");
+}
+/** The sentence saying why there is no command, after another way when there is one. */
+function noCommand(handoff, options) {
+	return options.instead === void 0 ? handoff.message : `${options.instead} ${handoff.message}`;
+}
+/**
+* A sentence that gives the command, in backticks, made by `say`; or, with no command, the sentence saying why there is
+* none — after `instead`, when given — never `say` with something else in the command's place.
+*/
+function handoffSentence(handoff, say, options = {}) {
+	return isCommand(handoff) ? say(inlineCommand(handoff)) : noCommand(handoff, options);
+}
+/**
+* As `handoffSentence`, for a command with words the agent is to fill in — a placeholder such as `<folder>`, printed as
+* written — before its first `--`. With no line to show them in, the command is shown as its words, placeholders among
+* them, saying it has to be typed.
+*/
+function handoffSentenceToFill(handoff, toFill, say, options = {}) {
+	if (!isCommand(handoff)) return noCommand(handoff, options);
+	const line = lineWithWordsToFill(handoff, ...toFill);
+	if (line !== null) return say(`\`${line}\``);
+	return say(inlineQuoted(quotedWithWordsToFill(handoff, toFill)));
+}
+/**
+* Commands that each could do it — one per channel, say — as one phrase: the commands joined by "or", then, for each
+* that has none here, the sentence saying why. `none` is said when not one of them is a command.
+*/
+function handoffChoices(handoffs, none, options = {}) {
+	const commands = handoffs.filter((handoff) => isCommand(handoff)).map((handoff) => inlineCommand(handoff));
+	const missing = handoffs.filter((handoff) => !isCommand(handoff));
+	const reasons = [...new Set(missing.map((handoff) => handoff.message))].join(" ");
+	if (commands.length === 0) return `${none} ${reasons}`.trim();
+	const conjunction = options.conjunction ?? "or";
+	const joined = commands.length === 1 ? commands[0] : `${commands.slice(0, -1).join(", ")} ${conjunction} ${commands.at(-1)}`;
+	return reasons === "" ? joined : `${joined} (${reasons.replace(/\.$/, "")})`;
+}
+/**
+* One table of dangerous characters, shared by the inbound sanitiser (which strips them from sender-controlled text)
+* and the preview renderer (which makes them visible), so the two can never disagree.
+*/
+/** Zero-width and formatting characters, bidi controls, variation selectors and Unicode tag characters. */
+const INVISIBLE_RANGES = [
+	[173, 173],
+	[847, 847],
+	[1564, 1564],
+	[4447, 4448],
+	[6068, 6069],
+	[6155, 6159],
+	[8203, 8207],
+	[8232, 8233],
+	[8234, 8238],
+	[8288, 8292],
+	[8294, 8303],
+	[12644, 12644],
+	[65024, 65039],
+	[65279, 65279],
+	[65440, 65440],
+	[917504, 917631]
+];
+function isInvisible(codePoint) {
+	for (const [from, to] of INVISIBLE_RANGES) if (codePoint >= from && codePoint <= to) return true;
+	return false;
+}
+/**
+* C0 controls except tab and newline (ESC, and so every ANSI/OSC sequence, starts here), DEL, and C1 controls (CSI
+* among them). A lone carriage return counts: it moves a terminal cursor back over text already printed.
+*/
+function isControl(codePoint) {
+	if (codePoint === 9 || codePoint === 10) return false;
+	return codePoint < 32 || codePoint === 127 || codePoint >= 128 && codePoint <= 159;
+}
+function isDangerous(codePoint) {
+	return isControl(codePoint) || isInvisible(codePoint);
+}
+/**
+* Strips control characters (ESC, CSI, OSC and the rest), DEL, lone carriage returns, zero-width, bidi-control and tag
+* characters from sender-controlled text; returns the text and how many were removed. CRLF becomes LF first.
+*
+* This lives beside the table rather than in the sanitiser because `neutralise` needs it too, and the two must not
+* drift: a pattern that looks for `</untrusted-content` cannot see it through a zero-width space, so stripping
+* has to happen before any such pattern runs, on every path, not only on the ones that render a body.
+*/
+function stripInvisible(text) {
+	let removed = 0;
+	let out = "";
+	for (const char of text.replace(/\r\n/g, "\n")) if (isDangerous(char.codePointAt(0) ?? 0)) removed += 1;
+	else out += char;
+	return {
+		text: out,
+		removed
+	};
+}
 /**
 * Whether a folder, as written, says where it is on its own: from the home (`~`), or absolute — and on Windows with its
 * drive (`C:\…`) or share (`\\server\share\…`). Windows calls `\outgoing` absolute, but it is on whichever drive is
@@ -1833,10 +2107,20 @@ function parseConfig$1(text, source = "config.json") {
 var ConfigStore = class {
 	path;
 	#lockPath;
+	#handoffs;
 	#cache = null;
-	constructor(configDir) {
+	/**
+	* @param options.handoffs the printing package's handoffs (`core.handoffs`, CUE-403), for the command a refusal
+	*   names; left out, a refusal that has to name one is a programming error (`requiredHandoffs`).
+	*/
+	constructor(configDir, options = {}) {
 		this.path = join(configDir, "config.json");
 		this.#lockPath = join(configDir, ".config.lock");
+		this.#handoffs = options.handoffs;
+	}
+	/** "Run the names migration again", as core's command — located from whatever is printing — or the tool. */
+	#namesMigrateAgain(why) {
+		return handoffSentence(requiredHandoffs(this.#handoffs).core(["names", "migrate"]), (command) => `Run ${command} again ${why}.`, { instead: `Call comms_names_migrate again ${why}.` });
 	}
 	/** The current config; an empty one when the file does not exist yet. */
 	async load() {
@@ -1869,7 +2153,7 @@ var ConfigStore = class {
 				this.#cache = null;
 				const current = structuredClone(await this.load());
 				const next = await mutator(structuredClone(current));
-				if (next.version !== current.version) throw new CommsError("CONFIG", `refusing to change the config version from ${current.version} to ${String(next.version)}`, { hint: "Only `agentcomms names migrate` changes the version. This is a bug — please report it." });
+				if (next.version !== current.version) throw new CommsError("CONFIG", `refusing to change the config version from ${current.version} to ${String(next.version)}`, { hint: "Only the names migration changes the version. This is a bug — please report it." });
 				const parsed = schemaFor(current.version).safeParse(next);
 				if (!parsed.success) throw new CommsError("CONFIG", `refusing to write invalid config: ${describeIssues(parsed.error, current.version)}`);
 				if (current.version === 2 && parsed.data.version === 2) {
@@ -1880,7 +2164,7 @@ var ConfigStore = class {
 				const allowed = new Set(options.consent?.paths ?? []);
 				const unconsented = loosened.filter((path) => !allowed.has(path));
 				if (unconsented.length > 0) throw new CommsError("LOOSENING_REFUSED", `this change loosens a safety setting: ${unconsented.join(", ")}`, {
-					hint: "A person approves a loosening, from a chat or at a terminal. From a chat, the tool that makes the change returns a preview and an approval id: the person says yes in the chat (change policy `chat`) or runs `agentcomms approve <id>` at their own terminal (`confirm`), and the tool is called again with the id. At a terminal, run the matching command and approve the change it shows.",
+					hint: "A person approves a loosening, from a chat or at a terminal. From a chat, the tool that makes the change returns a preview and an approval id: the person says yes in the chat (change policy `chat`) or runs the approve command the result gives at their own terminal (`confirm`), and the tool is called again with the id. At a terminal, run the matching command and approve the change it shows.",
 					details: { paths: unconsented }
 				});
 				const approved = options.consent?.changes;
@@ -1940,13 +2224,13 @@ var ConfigStore = class {
 			const raw = await readFileIfExists(this.path);
 			const current = raw === null ? emptyConfig() : parseConfig$1(raw, this.path);
 			if (current.version === 2) {
-				if (!migrationApplied(current, rows)) throw new CommsError("TRANSIENT", "the names were migrated while this ran, and not to these names", { hint: "Run `agentcomms names migrate` again to see what they are called now." });
+				if (!migrationApplied(current, rows)) throw new CommsError("TRANSIENT", "the names were migrated while this ran, and not to these names", { hint: this.#namesMigrateAgain("to see what they are called now") });
 				return {
 					status: "already-migrated",
 					config: current
 				};
 			}
-			if (configFingerprint(current) !== expected) throw new CommsError("TRANSIENT", "the configuration changed after the preview was made", { hint: "Run `agentcomms names migrate` again to see the mapping for the configuration as it is now." });
+			if (configFingerprint(current) !== expected) throw new CommsError("TRANSIENT", "the configuration changed after the preview was made", { hint: this.#namesMigrateAgain("to see the mapping for the configuration as it is now") });
 			const parsed = configV2Schema.safeParse(build(structuredClone(current)));
 			if (!parsed.success) throw new CommsError("CONFIG", `refusing to write invalid config: ${describeIssues(parsed.error, 2)}`);
 			const unchanged = onlyKeysRenamed(current, parsed.data);
@@ -2504,13 +2788,40 @@ function cancelledClaim(record) {
 		}
 	});
 }
+/**
+* The refusals of a send's approval offered to a change. They name each sending channel's `approve`; another product's
+* is found only among the registrations read for it, which the store does not read under its lock — so a caller that
+* can read them says it again with them (`sendApprovesHint`).
+*/
+const MISDIRECTED_SENDS = /* @__PURE__ */ new WeakSet();
+/**
+* What an agent is told when a change waits for a person at a terminal: the printing package's own `approve` with this
+* id, located, or why there is none here.
+*/
+function approvePendingHint(handoffs, approvalId, platform) {
+	const located = requiredHandoffs(handoffs);
+	return handoffSentence(located.on(platform ?? located.platform).own(["approve", approvalId]), (command) => `Ask the user to run ${command} in their own terminal, then try again with the same approval.`);
+}
+/** Whether `error` is the refusal of a send's approval offered as a change's. */
+function isMisdirectedSend(error) {
+	return error instanceof CommsError && MISDIRECTED_SENDS.has(error);
+}
+/**
+* What approves the send `approvalId`: the `approve` of every channel that sends, one of which prepared it — a send
+* record does not say which (D1). Each is a located command, or why it has none here.
+*/
+function sendApprovesHint(maker, approvalId) {
+	return `It is approved with the command that prepared it — ${handoffChoices(accountChannels().filter((manifest) => manifest.accounts?.modes.includes("send") === true).map((manifest) => maker.of(manifest.channel, ["approve", approvalId])), "and none is locatable here:")} — and permits only that send.`;
+}
 var ApprovalStore = class {
 	directory;
 	#now;
 	#ttlMs;
 	#downloadTtlMs;
+	#handoffs;
 	constructor(stateDir, options = {}) {
 		this.directory = join(stateDir, "approvals");
+		this.#handoffs = options.handoffs;
 		this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
 		this.#ttlMs = options.ttlMs ?? 6e5;
 		this.#downloadTtlMs = options.downloadTtlMs ?? 18e5;
@@ -2616,17 +2927,17 @@ var ApprovalStore = class {
 	* Nothing written, because the caller made a mistake about an approval that may be perfectly good: voiding a post
 	* somebody is about to approve, because an agent passed its id to a change, would punish the wrong party.
 	*/
-	#requireKind(record, kind, platform) {
+	#requireKind(record, kind, platform, handoffs = this.#handoffs) {
+		const maker = () => requiredHandoffs(handoffs).on(platform);
 		const actual = approvalKind(record);
 		if (actual === kind) return;
 		const id = record.approvalId;
 		if (actual === "download") throw (kind === "change" ? refuseChange : refuse)("USAGE", `${id} is a question about where to save files, not ${kind === "send" ? "a send" : "a configuration change"}`, record, DOWNLOAD_ANSWER_HINT);
 		if (kind === "download") throw refuseDownload("USAGE", `${id} is ${actual === "change" ? "a configuration change" : "a send"}, not a question about where to save files`, record, "Pass the choice id the download’s question came with, and the person’s answer beside it.");
-		throw kind === "send" ? refuse("USAGE", `approval ${id} is for a configuration change, not a send`, record, `A person approves it with ${inlineCommand(shellCommand([
-			"agentcomms",
-			"approve",
-			id
-		], platform))} — or ${channelApproveCommands()}, whichever is installed — and it permits only the change it was prepared for.`) : refuseChange("USAGE", `approval ${id} is for a send, not a configuration change`, record, `It is approved with the command that prepared it — ${channelApproveCommands({ sending: true })} — and permits only that send.`);
+		if (kind === "send") throw refuse("USAGE", `approval ${id} is for a configuration change, not a send`, record, handoffSentence(maker().own(["approve", id]), (command) => `A person approves it with ${command}, and it permits only the change it was prepared for.`));
+		const misdirected = refuseChange("USAGE", `approval ${id} is for a send, not a configuration change`, record, sendApprovesHint(maker(), id));
+		MISDIRECTED_SENDS.add(misdirected);
+		throw misdirected;
 	}
 	/** Issues a new challenge to show a human; only its hash is kept. */
 	async issueChallenge(approvalId, kind = "send", platform = process.platform) {
@@ -2709,7 +3020,7 @@ var ApprovalStore = class {
 	async claimForSend(approvalId, live, options = {}) {
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "send", options.platform ?? process.platform);
+			this.#requireKind(current, "send", options.platform ?? process.platform, options.handoffs ?? this.#handoffs);
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
 			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (code, reason) => {
@@ -2821,7 +3132,7 @@ var ApprovalStore = class {
 		const digest = changeDigest(live.change);
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "change", options.platform ?? process.platform);
+			this.#requireKind(current, "change", options.platform ?? process.platform, options.handoffs ?? this.#handoffs);
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
 			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (reason) => {
@@ -2837,11 +3148,7 @@ var ApprovalStore = class {
 			};
 			if (digest !== current.digest) return voidWith(current.change ? changeDrift(current.change, live.change) : "the change is not the one that was approved");
 			if (stricterPolicy(live.policy, current.requiredPolicy) !== "chat") {
-				if (current.state !== "approved") throw refuseChange("APPROVAL_PENDING", "this change needs a person to approve it at a terminal first", current, options.pendingHint ?? `Ask the user to run ${inlineCommand(shellCommand([
-					"agentcomms",
-					"approve",
-					approvalId
-				], options.platform ?? process.platform))} in their own terminal, then try again with the same approval.`);
+				if (current.state !== "approved") throw refuseChange("APPROVAL_PENDING", "this change needs a person to approve it at a terminal first", current, options.pendingHint ?? approvePendingHint(options.handoffs ?? this.#handoffs, approvalId, options.platform));
 				if (current.approvedVia !== "terminal") return voidWith("the change policy is confirm, and this was not approved at a terminal");
 			}
 			return {
@@ -2963,7 +3270,7 @@ var ApprovalStore = class {
 		const digest = downloadDigest(live);
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "download", options.platform ?? process.platform);
+			this.#requireKind(current, "download", options.platform ?? process.platform, options.handoffs ?? this.#handoffs);
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
 			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (reason) => {
@@ -3114,125 +3421,99 @@ var AuditLog = class {
 		return out.reverse();
 	}
 };
-const MAP = {
-	inbox: "inboxes",
-	account: "accounts"
-};
+/** Every command a manifest declares — each channel's `binary` and its server's other `bins` — lowercased. */
+const SUITE_COMMANDS = new Set(CHANNEL_SNAPSHOT.flatMap(({ manifest }) => [manifest.binary, ...manifest.server.bins ?? []]).map((name) => name.toLowerCase()));
+/** The extensions Windows finds an executable by: `agent-gmail.cmd` is `agent-gmail`. */
+const EXECUTABLE_EXTENSION = /\.(?:cmd|exe|bat|ps1|com)$/i;
 /**
-* An own property only.
-*
-* A name is user input and the maps are plain objects, so `config.inboxes.constructor` is a function — and a lookup
-* of an inbox called `constructor`, which version 1 allows, found it.
+* The suite command a word names as a program — its last path part, without a Windows extension, compared without
+* case as Windows compares executable names — or null.
 */
-function own$1(map, key) {
-	return Object.hasOwn(map, key) ? map[key] : void 0;
-}
-function resolveName(config, kind, name, notFound) {
-	if (kind === "inbox") {
-		const inbox = own$1(config.inboxes, name);
-		if (inbox) return {
-			alias: name,
-			inbox
-		};
-	} else {
-		const account = own$1(config.accounts, name);
-		if (account) return {
-			alias: name,
-			account
-		};
-	}
-	const renamed = formerNameRefusal(config, kind, name);
-	if (renamed) throw renamed;
-	throw notFound?.() ?? defaultNotFound(config, kind, name);
+function suiteCommandOf(word) {
+	const name = (word.split(/[\\/]/).at(-1) ?? "").replace(EXECUTABLE_EXTENSION, "").toLowerCase();
+	return SUITE_COMMANDS.has(name) ? name : null;
 }
-/** What to say when there are no mailboxes at all: the command that connects one, from the mail channel's manifest. */
-function noInboxesHint() {
-	const connect = connectMailboxCommand();
-	return connect ? `No inboxes yet: add one with \`${connect}\`.` : "No inboxes yet.";
+/** A parsed `package.json`, as an object, or null when there is none, it cannot be read, or it is not an object. */
+function readPackageManifest(dir) {
+	const read = readPackageFile(dir);
+	return read === "absent" ? null : read;
 }
-function defaultNotFound(config, kind, name) {
-	if (kind === "inbox") {
-		const known = Object.keys(config.inboxes);
-		return new CommsError("NOT_FOUND", `no inbox called "${name}"`, { hint: known.length ? `Known inboxes: ${known.join(", ")}.` : noInboxesHint() });
+/** `absent` when the directory has no `package.json`; otherwise what it says, or null when that cannot be read. */
+function readPackageFile(dir) {
+	let text;
+	try {
+		text = readFileSync(join(dir, "package.json"), "utf8");
+	} catch (error) {
+		const code = error.code;
+		return code === "ENOENT" || code === "ENOTDIR" ? "absent" : null;
+	}
+	try {
+		const parsed = JSON.parse(text);
+		return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+	} catch {
+		return null;
 	}
-	return new CommsError("NOT_FOUND", `no account called "${name}"`);
-}
-function lookupName(config, kind, name) {
-	return kind === "inbox" ? own$1(config.inboxes, name) : own$1(config.accounts, name);
 }
-function findById(config, kind, id) {
-	if (kind === "inbox") {
-		for (const [alias, inbox] of Object.entries(config.inboxes)) if (inbox.id === id) return {
-			alias,
-			inbox
+/**
+* The nearest package at or above `start`: the first directory with a `package.json`, and what it says (null when it
+* cannot be read or parsed). Not the nearest one with a particular name — the package a module belongs to is the
+* nearest one, as Node itself decides, and a caller that names a different one has to be told so.
+*/
+function nearestPackage(start) {
+	let dir = resolve(start);
+	for (;;) {
+		const manifest = readPackageFile(dir);
+		if (manifest !== "absent") return {
+			root: dir,
+			manifest
 		};
-	} else for (const [alias, account] of Object.entries(config.accounts)) if (account.id === id) return {
-		alias,
-		account
-	};
-	return null;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
 }
 /**
-* The refusal for a former name, or null when `name` is not one.
-*
-* The replacement is looked up by id rather than read from the record, so a chain of renames ends at the name the
-* account has today — and an account removed since its rename is said to be gone, rather than pointing somebody at a
-* name that now belongs to nothing.
+* Whether `path` is `root` or inside it, by whole path segments: `/x/core-evil` is not inside `/x/core`, which a
+* comparison of strings would say it was. Both are taken as given; a caller compares real paths with real paths.
 */
-function formerNameRefusal(config, kind, name) {
-	if (config.version !== 2) return null;
-	const former = own$1(config.formerNames[MAP[kind]], name);
-	if (!former) return null;
-	const current = kind === "inbox" ? findById(config, "inbox", former.id) : findById(config, "account", former.id);
-	if (!current) return new CommsError("NOT_FOUND", `"${name}" was renamed to "${former.name}", which has since been removed`, { details: {
-		formerName: name,
-		id: former.id
-	} });
-	return new CommsError("NOT_FOUND", `"${name}" was renamed to "${current.alias}"`, {
-		hint: `Use "${current.alias}".`,
-		details: {
-			formerName: name,
-			currentName: current.alias,
-			id: former.id
-		}
-	});
+function isWithin(root, path) {
+	const between = relative(resolve(root), resolve(path));
+	return between === "" || !isAbsolute(between) && between !== ".." && !/^\.\.[\\/]/.test(between);
+}
+/** The real path of `path`, or of its deepest ancestor that exists with the rest joined on; null when none does. */
+function realpathOfExisting(path) {
+	let current = resolve(path);
+	const rest = [];
+	for (;;) try {
+		const real = realpathSync(current);
+		return rest.length === 0 ? real : join(real, ...rest.reverse());
+	} catch {
+		const parent = dirname(current);
+		if (parent === current) return null;
+		rest.push(basename(current));
+		current = parent;
+	}
 }
 /**
-* Whether `name` may be given to a new or renamed account of this kind and platform.
-*
-* Each version keeps its own rule, because version 1's differ by kind today and must not change under a file an
-* older release also writes: a mailbox name need only be free among mailboxes, a workspace name among both. Version
-* 2 is stricter and the same for both: the grammar, the platform, free in both maps, and never a former name of
-* either kind.
-*
-* A check, not a reservation. Callers repeat it inside the config write, where the schema enforces the same rules
-* again for version 2, because anything can happen between asking and writing.
+* The root of the suite package `path` is in — itself or any ancestor whose `package.json` names a package of this
+* suite — as written and after resolving links, or null. Every ancestor is looked at, not only the nearest package:
+* a file in `packages/gmail/node_modules/x` is still inside Gmail's root.
 */
-function nameAvailable(config, kind, name, platform) {
-	const refuse = (error) => ({
-		ok: false,
-		error
-	});
-	if (config.version === 1) {
-		if (RESERVED_ALIASES.has(name)) return refuse(new CommsError("USAGE", `"${name}" is reserved`, { hint: "Choose another name." }));
-		if (!isValidAlias(name)) return refuse(new CommsError("USAGE", `"${name}" is not a usable name`, { hint: "Lower-case letters, digits and dashes, up to 32 characters, not starting with a dash." }));
-		if (kind === "inbox" ? own$1(config.inboxes, name) : own$1(config.inboxes, name) ?? own$1(config.accounts, name)) return refuse(new CommsError("CONFIG", `"${name}" is already connected`, { hint: "Choose another name." }));
-		return { ok: true };
-	}
-	const problem = nameShapeProblem(name, platform);
-	if (problem) return refuse(new CommsError("USAGE", problem));
-	if (own$1(config.inboxes, name) || own$1(config.accounts, name)) return refuse(new CommsError("CONFIG", `"${name}" is already connected`, { hint: "Choose another name." }));
-	for (const map of ["inboxes", "accounts"]) {
-		const former = own$1(config.formerNames[map], name);
-		if (former) return refuse(new CommsError("CONFIG", `"${name}" was the name of another account and cannot be used again`, {
-			hint: "A former name keeps pointing people at the account that had it. Choose another name.",
-			details: {
-				formerName: name,
-				id: former.id
-			}
-		}));
+function suitePackageRootOf(path) {
+	const candidates = [resolve(path)];
+	const real = realpathOfExisting(path);
+	if (real !== null && real !== candidates[0]) candidates.push(real);
+	for (const candidate of candidates) {
+		let dir = candidate;
+		for (;;) {
+			const name = readPackageManifest(dir)?.name;
+			if (typeof name === "string" && name.startsWith("@agentcomms/")) return dir;
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
 	}
-	return { ok: true };
+	return null;
 }
 /**
 * Enough of TOML to read codex's `config.toml`, and a refusal for anything else.
@@ -3868,10 +4149,126 @@ async function scanRegisteredServers(env = process.env, platform = process.platf
 	};
 }
 function packageFrom(server) {
-	const line = [server.command, ...server.args].join(" ");
+	return commandLinePackage(server.command, server.args);
+}
+/**
+* The npm package an entry's command line launches, when one can be read from it: `@scope/name`, or a bare `…-mcp`.
+* Read from the words left once the suite's path options are taken out (`withoutPathOptions`): a pinned folder such as
+* `/tmp/@agentcomms/slack` is not a package, and read as one it made a Gmail entry Slack's.
+*/
+function commandLinePackage(command, args) {
+	const line = [command, ...withoutPathOptions(args).words].join(" ");
 	return /(@[\w.-]+\/[\w.-]+|(?<=\s)[\w.-]+-mcp)(?=@|\s|$)/.exec(line)?.[1];
 }
 /**
+* A command for a person to run that is not this suite's: `chmod`, or an MCP client's own `claude mcp …` and
+* `codex mcp …` (design 2026-10-04, D5).
+*
+* Every command printed for a person is one of two kinds. One of this suite's own CLIs is a `PrintedCommand`, which
+* only the locator makes (`cli-command.ts`): it names this Node and a checked file of the product, because a bare
+* `agent-gmail` is not on the PATH of most people it is printed for (CUE-403). Anything else is an `ExternalCommand`,
+* made here and nowhere else, with the reason that program is one a person may be told to run.
+*
+* So that this is not a way round the locator, `externalCommand` refuses words that would start one of this suite's
+* products by another route: a word containing one of the suite's commands — in any case, alone, as a path's last
+* part or inside a wrapper's payload (`sh -c "agent-gmail …"`) — a word naming a package of the suite
+* (`npx @agentcomms/gmail`), or a path inside the root of a suite package, as written or through a link
+* (`node …/packages/gmail/dist/cli.mjs`). Every word is looked at, not only the first: the program is often a wrapper.
+*
+* This module is a leaf: it reads the manifests' facts and the files a path names, and imports nothing that registers,
+* scans or locates, so nothing it refuses can be routed back through it.
+*/
+/** The gate a constructor call has to pass: only this module holds it. */
+const GATE$1 = Symbol("externalCommand");
+/**
+* One reviewed command of a program that is not this suite's. Rendered as every printed command is — a line to paste,
+* or on Windows its words as JSON when no line is safe in every shell (`inlineCommand`, `commandText`).
+*
+* A class with a private field, so the type is nominal: an object literal with the same fields is not one, and nor is
+* a spread copy of one with other words in it. Only the type is exported; the class is not.
+*/
+var ExternalCommand = class {
+	#reason;
+	/** The words, as the program is to receive them. */
+	words;
+	/** The line to paste; null when one of the words has no printing that every Windows shell passes on alike. */
+	line;
+	platform;
+	constructor(gate, words, platform, reason) {
+		if (gate !== GATE$1) throw new TypeError("an external command is made by externalCommand, and only there");
+		this.#reason = reason;
+		this.words = Object.freeze([...words]);
+		this.line = quoteCommand(this.words, platform).line;
+		this.platform = platform;
+		Object.freeze(this);
+	}
+	/** Why this program, which is not part of this suite, is one a person may be told to run. */
+	get reason() {
+		return this.#reason;
+	}
+	/** As JSON, the text it always was: its line, or its words as JSON with what to do (as a `PrintedCommand`). */
+	toJSON() {
+		return quotedText(this);
+	}
+	/** Never interpolated: rendered with `commandText` or `inlineCommand`. */
+	[Symbol.toPrimitive]() {
+		throw new TypeError("an external command is rendered with commandText or inlineCommand, never interpolated");
+	}
+};
+/** A package specifier of the suite, with either separator: `@agentcomms/gmail`, `node_modules\@agentcomms\gmail`. */
+const SUITE_PACKAGE = /@agentcomms[\\/]/i;
+/**
+* The parts of a word a shell or a wrapper could take as a command name: split wherever a character could not be part
+* of one, so `sh -c "cd x && agent-gmail approve"`, `--run=agent-gmail` and `C:\npm\agent-gmail.cmd` each yield
+* `agent-gmail`. Compared without case, as Windows compares executable names; on a case-sensitive system that refuses
+* a little more than it must, and nothing that it should not.
+*/
+function commandNames(word) {
+	return word.split(/[^A-Za-z0-9._-]+/).map((part) => part.replace(/^\.+|\.+$/g, "").replace(EXECUTABLE_EXTENSION, "").toLowerCase()).filter(Boolean);
+}
+/**
+* The paths in a word: the word itself, and each part of it between spaces, quotes, `=` and a shell's separators, that
+* is absolute, `~/…`, or a `file:` URL. A relative path is not resolved: the folder a person pastes the command in is
+* not known here, and a server called `7/gmail` is a name, not a path.
+*/
+function pathsIn(word) {
+	const paths = [];
+	for (const part of [word, ...word.split(/[\s"'`=;&|<>(),]+/)]) {
+		if (part.length === 0) continue;
+		if (/^file:/i.test(part)) try {
+			paths.push(fileURLToPath(part));
+		} catch {}
+		else if (part === "~" || /^~[\\/]/.test(part)) paths.push(join(homedir(), part.slice(2)));
+		else if (isAbsolute(part)) paths.push(part);
+	}
+	return paths;
+}
+/** Why these words must not be an external command, or null when they may be. */
+function refusal$1(words) {
+	for (const [index, word] of words.entries()) {
+		if (SUITE_PACKAGE.test(word)) return `word ${index} names a package of this suite`;
+		for (const path of pathsIn(word)) {
+			const root = suitePackageRootOf(path);
+			if (root !== null) return `word ${index} is a path inside ${root}, a package of this suite`;
+		}
+		if (commandNames(word).some((name) => SUITE_COMMANDS.has(name))) return `word ${index} names a command of this suite`;
+	}
+	return null;
+}
+/**
+* The one way to make an `ExternalCommand`: `words` for a program that is not this suite's, and `reason`, why a person
+* may be told to run it. Throws a `TypeError` for words that would start a product of this suite (see the module), so
+* a call site whose words come from somewhere else — a server's name read from a client's file, a folder — says what
+* to do in prose instead when one is refused. `platform` is the shell it is quoted for.
+*/
+function externalCommand(words, reason, platform = process.platform) {
+	if (words.length === 0 || (words[0] ?? "").length === 0) throw new TypeError("an external command needs a program");
+	if (reason.trim().length === 0) throw new TypeError("an external command needs the reason it may be run");
+	const refused = refusal$1(words);
+	if (refused !== null) throw new TypeError(`not an external command: ${refused}; a command of this suite comes from locateCliCommand`);
+	return new ExternalCommand(GATE$1, words, platform, reason);
+}
+/**
 * The programs this package starts, named so that no folder it happens to be in can stand in for them.
 *
 * A bare name is looked up, and on Windows the lookup starts in the current folder: libuv tries it before `PATH`, and
@@ -4002,24 +4399,54 @@ async function resolveNode(env) {
 	return await whichExecutable("node", env) ?? process.execPath;
 }
 function minimalEnv(context, node) {
-	const env = {
-		AGENT_COMMS_CONFIG_DIR: context.core.paths.configDir,
-		PATH: [
-			dirname(node),
-			"/usr/local/bin",
-			"/usr/bin",
-			"/bin"
-		].join(delimiter)
-	};
+	const env = { PATH: [
+		dirname(node),
+		"/usr/local/bin",
+		"/usr/bin",
+		"/bin"
+	].join(delimiter) };
 	if (process.platform === "linux") for (const key of ["DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"]) {
 		const value = context.env[key];
 		if (value) env[key] = value;
 	}
 	return env;
 }
+/** The complete suite identity every installer-written server registration carries. Downloads are operation-local. */
+function registrationPathArgs(context) {
+	const { configDir, stateDir, dataDir, secretsDir } = context.core.paths;
+	return [
+		"--config-dir",
+		configDir,
+		"--state-dir",
+		stateDir,
+		"--data-dir",
+		dataDir,
+		"--secrets-dir",
+		secretsDir
+	];
+}
 function unscoped(packageName) {
 	return packageName.split("/").at(-1) ?? packageName;
 }
+function escapeRegExp$2(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* An MCP client's own command about one of its entries — `claude mcp get <name>`, `codex mcp remove <name>` — in
+* backticks for a hint, or, when there is none to give, `instead`.
+*
+* The client's program, so an external command (`externalCommand`), and the name is whatever the entry is called. A
+* name that is also one of this suite's commands — the core server's own default, `agentcomms`, is one — is refused
+* there, because such a word is how a suite command would get round the locator; the hint then says the same thing in
+* words rather than printing a command with that name in it.
+*/
+function clientCommandHint(words, platform, instead) {
+	try {
+		return inlineCommand(externalCommand(words, "the MCP client's own command reads or removes an entry of its own configuration", platform));
+	} catch {
+		return instead;
+	}
+}
 /**
 * The directory the managed launcher installs one product's exact version into: `<data>/runtime/<version>-<name>`.
 *
@@ -4037,6 +4464,29 @@ function managedRuntimeEntry(dataDir, packageName, version) {
 	return join(managedRuntimeDir(dataDir, packageName, version), "node_modules", ...packageName.split("/"), "dist", "cli.mjs");
 }
 /**
+* The version a managed-runtime path pins, in either layout, or null when the path is not one.
+*
+* Both `runtime/0.4.0/…` (every Gmail install before the move) and `runtime/0.4.0-gmail/…` (every install
+* since) are read, and a prerelease keeps its own hyphen: `0.5.0-rc.1-gmail` is `0.5.0-rc.1`. Either separator,
+* and allowed to start the string, so a Windows or a relative path is not missed. On Windows (`platform`), whose
+* paths are not case-sensitive, the folder names are read without case; the version keeps the case it has.
+*/
+function managedRuntimeVersion(path, packageName, platform) {
+	const scope = packageName.split("/").map(escapeRegExp$2).join("[/\\\\]");
+	return new RegExp(`(?:^|[/\\\\])runtime[/\\\\]([^/\\\\]+?)(?:-${escapeRegExp$2(unscoped(packageName))})?[/\\\\]node_modules[/\\\\]${scope}[/\\\\]`, platform === "win32" ? "i" : "").exec(path)?.[1] ?? null;
+}
+/**
+* The version one argument of a registered entry pins, or null when it pins none.
+*
+* Two launchers pin, and they look nothing alike: `managed` writes a runtime path, `npx` a package spec. Reading
+* only the first reported an `npx`-pinned install as current for ever. `local` pins nothing and is ignored.
+*/
+function pinnedVersion(argument, product, platform) {
+	const names = [.../* @__PURE__ */ new Set([product.packageName, product.npxPackage])].map(escapeRegExp$2).join("|");
+	const spec = new RegExp(`^(?:${names})@(\\d[^\\s]*)$`, platform === "win32" ? "i" : "");
+	return managedRuntimeVersion(argument, product.packageName, platform) ?? spec.exec(argument)?.[1] ?? null;
+}
+/**
 * Whether a registered entry starts this product's server.
 *
 * Decides what `--force` may replace, so it errs towards "not ours". An npm package read off the command line
@@ -4044,11 +4494,20 @@ function managedRuntimeEntry(dataDir, packageName, version) {
 * by, compared as whole runs of segments — `@agentcomms/gmail-evil/dist/cli.mjs`, `@agentcomms/gmail/dist/
 * index.mjs` and `packages/gmail/src/nested/cli.ts` are all near misses, and each was once accepted by a looser
 * match somewhere in this repository.
+*
+* Only the entry's own words are read: the suite's path options and their values are taken out first, because a pinned
+* folder that ends in `packages/slack/src/cli.ts` is a folder, not Slack (`withoutPathOptions`). On Windows
+* (`platform`), whose file names are not case-sensitive, the command's name and every path segment are compared
+* without case, as Windows itself finds them; everywhere else exactly. Left out, it compares exactly.
 */
-function isProductServer(server, product) {
-	const launched = (server.command.split(/[\\/]+/).at(-1) ?? "").replace(/\.(?:cmd|exe|bat|ps1)$/i, "");
-	if (launched && [product.binary, ...product.bins ?? []].includes(launched)) return true;
-	if (server.packageName) return server.packageName === product.packageName || server.packageName === product.npxPackage;
+function isProductServer(server, product, platform) {
+	const fold = platform === "win32" ? (text) => text.toLowerCase() : (text) => text;
+	const launched = fold((server.command.split(/[\\/]+/).at(-1) ?? "").replace(/\.(?:cmd|exe|bat|ps1)$/i, ""));
+	if (launched && [product.binary, ...product.bins ?? []].map(fold).includes(launched)) return true;
+	if (server.packageName) {
+		const named = fold(server.packageName);
+		return named === fold(product.packageName) || named === fold(product.npxPackage);
+	}
 	const short = unscoped(product.packageName);
 	const entries = [
 		[
@@ -4071,9 +4530,9 @@ function isProductServer(server, product) {
 		],
 		...product.entryFiles ?? []
 	];
-	return [server.command, ...server.args].some((part) => {
-		const segments = part.split(/[\\/]+/).filter(Boolean);
-		return entries.some((entry) => segments.length >= entry.length && entry.every((wanted, index) => segments[segments.length - entry.length + index] === wanted));
+	return [server.command, ...withoutPathOptions(server.args).words].some((part) => {
+		const segments = part.split(/[\\/]+/).filter(Boolean).map(fold);
+		return entries.some((entry) => segments.length >= entry.length && entry.every((wanted, index) => segments[segments.length - entry.length + index] === fold(wanted)));
 	});
 }
 /**
@@ -4169,6 +4628,7 @@ async function buildEntry(context, product, options, apply, resolved) {
 	const launcher = options.launcher ?? "managed";
 	const { node } = resolved;
 	const env = minimalEnv(context, node);
+	const pathArgs = registrationPathArgs(context);
 	const serverArgs = product.serverArgs(options);
 	if (launcher === "npx") return {
 		entry: {
@@ -4176,6 +4636,7 @@ async function buildEntry(context, product, options, apply, resolved) {
 			args: [
 				"-y",
 				`${product.npxPackage}@${product.version}`,
+				...pathArgs,
 				...product.npxArgs ?? [],
 				...serverArgs
 			],
@@ -4192,6 +4653,7 @@ async function buildEntry(context, product, options, apply, resolved) {
 				args: [
 					...entryPath.endsWith(".ts") ? ["--experimental-strip-types", "--disable-warning=ExperimentalWarning"] : [],
 					entryPath,
+					...pathArgs,
 					"mcp",
 					...serverArgs
 				],
@@ -4209,6 +4671,7 @@ async function buildEntry(context, product, options, apply, resolved) {
 				command: node,
 				args: [
 					ready ?? managedRuntimeEntry(dataDir, product.packageName, product.version),
+					...pathArgs,
 					"mcp",
 					...serverArgs
 				],
@@ -4223,6 +4686,7 @@ async function buildEntry(context, product, options, apply, resolved) {
 			command: node,
 			args: [
 				await installManagedRuntime(context, product, product.version),
+				...pathArgs,
 				"mcp",
 				...serverArgs
 			],
@@ -4307,13 +4771,17 @@ function snippetFor(client, name, entry) {
 * Project-scoped entries are not looked at: every write here targets user scope, so they are not what would be
 * replaced.
 */
-function claimName(product, options, name, existing, platform) {
+function claimName(product, options, name, existing, _platform) {
 	const taken = existing.filter((server) => server.client === options.client && server.name === name && server.scope !== "project");
 	const foreign = taken.find((server) => !isProductServer(server, product));
 	if (foreign) {
 		const what = foreign.packageName ?? (foreign.url ? displayUrl(foreign.url) : void 0) ?? (foreign.command || "something else");
 		const other = name === product.binary ? `${product.binary}-${product.defaultServerName}` : product.binary;
-		throw new CommsError("CONFIG", `${options.client} already has an MCP server called "${name}", and it is not this one (it runs ${what})`, { hint: `Register this one under another name: ${inlineCommand(installCommand$1(product, options, other, [], platform))}. --force does not replace a server this did not install.` });
+		throw refusedWithRemedy("CONFIG", `${options.client} already has an MCP server called "${name}", and it is not this one (it runs ${what})`, {
+			binary: product.binary,
+			words: installWords(product, options, other, []),
+			say: (command) => `Register this one under another name: ${command}. --force does not replace a server this did not install.`
+		});
 	}
 	if (taken.length > 0 && !options.force) {
 		for (const pin of PIN_OPTIONS) {
@@ -4321,14 +4789,22 @@ function claimName(product, options, name, existing, platform) {
 			const served = taken.map((server) => product.narrowingOf(server.args)[pin]).find(Boolean);
 			if (!wanted || !served || served === wanted) continue;
 			const second = `${product.defaultServerName}-${wanted.split("/")[0]}`;
-			throw new CommsError("CONFIG", `${options.client} already has this server registered as "${name}"`, { hint: `That entry serves ${served}; to serve ${wanted} as well, register a second entry under its own name: ${inlineCommand(installCommand$1(product, options, second === name ? `${name}-2` : second, [], platform))}.` });
+			throw refusedWithRemedy("CONFIG", `${options.client} already has this server registered as "${name}"`, {
+				binary: product.binary,
+				words: installWords(product, options, second === name ? `${name}-2` : second, []),
+				say: (command) => `That entry serves ${served}; to serve ${wanted} as well, register a second entry under its own name: ${command}.`
+			});
 		}
 		const npx = taken.some((server) => server.args.some((argument) => argument.startsWith(`${product.npxPackage}@`)));
 		const again = {
 			...keepNarrowing(product, options, taken).options,
 			launcher: options.launcher ?? (npx ? "npx" : void 0)
 		};
-		throw new CommsError("CONFIG", `${options.client} already has this server registered as "${name}"`, { hint: `Pass --force to replace it — that is how an upgrade reaches a client: ${inlineCommand(installCommand$1(product, again, name, ["--force"], platform))}.` });
+		throw refusedWithRemedy("CONFIG", `${options.client} already has this server registered as "${name}"`, {
+			binary: product.binary,
+			words: installWords(product, again, name, ["--force"]),
+			say: (command) => `Pass --force to replace it — that is how an upgrade reaches a client: ${command}.`
+		});
 	}
 	return taken;
 }
@@ -4364,20 +4840,17 @@ function keepNarrowing(product, options, previous) {
 	};
 }
 /**
-* The `mcp install` that repeats this one under `name`, with every flag that decides what the server may reach.
+* The `mcp install` that repeats this one under `name`, with every flag that decides what the server may reach: its
+* words after the program.
 *
 * The hints used to be `mcp install --client <c> --force` whatever had been asked. Refused for `--name slack-acme
 * --workspace acme/slack`, the hint registered a second server under the default name, pinned to nothing — every
 * workspace on the machine; for Gmail it dropped `--inbox` and `--read-only` the same way. Doctor's repair already
 * rebuilds these flags for exactly that reason. The product's `serverArgs` are the install command's own flags for
 * the pin and the narrowing, so they are repeated as they are.
-*
-* A pin kept from the entry being replaced was read from the client's file, which may hold anything, so on Windows the
-* command can come back with no line to paste; every hint gives it with `inlineCommand`, which shows it as words then.
 */
-function installCommand$1(product, options, name, extra, platform) {
+function installWords(product, options, name, extra) {
 	const words = [
-		product.binary,
 		"mcp",
 		"install",
 		"--client",
@@ -4387,7 +4860,24 @@ function installCommand$1(product, options, name, extra, platform) {
 	words.push(...product.serverArgs(options));
 	if (options.launcher && options.launcher !== "managed") words.push("--launcher", options.launcher);
 	words.push(...extra);
-	return shellCommand(words, platform);
+	return words;
+}
+const REMEDIES = /* @__PURE__ */ new WeakMap();
+/** The remedy a refusal of `mcp install` carries, for the operation that called it to locate; undefined for any other. */
+function installRemedyOf(error) {
+	return typeof error === "object" && error !== null ? REMEDIES.get(error) : void 0;
+}
+/**
+* A refusal whose remedy is another install: until the caller locates it, its hint says the words in prose — never a
+* command with a bare program.
+*/
+function refusedWithRemedy(code, message, remedy, options = {}) {
+	const error = new CommsError(code, message, {
+		hint: remedy.say(`its own \`mcp install\` with ${remedy.words.slice(2).join(" ")}`),
+		...options.cause === void 0 ? {} : { cause: options.cause }
+	});
+	REMEDIES.set(error, remedy);
+	return error;
 }
 /**
 * A command's exit status and what it printed, kept here and never shown: codex prints an entry's env. Started as
@@ -4430,16 +4920,16 @@ function capture$1(env, command, args) {
 * or a failure that is not "no such server", stops the install: not knowing is not the same as nothing there.
 * Nothing codex prints is repeated, because its answer carries the entry's env.
 */
-async function codexRegistration(env, binary, name, path, platform) {
-	const unknown = () => new CommsError("CONFIG", `codex would not say what it has registered as "${name}", so nothing was written`, { hint: `Look with ${inlineCommand(shellCommand([
+async function codexRegistration(env, cliPath, name, path, platform) {
+	const unknown = () => new CommsError("CONFIG", `codex would not say what it has registered as "${name}", so nothing was written`, { hint: `Look with ${clientCommandHint([
 		"codex",
 		"mcp",
 		"get",
 		name
-	], platform))}. If it is not an older copy of this server, choose another --name; \`--print\` shows the entry to add by hand.` });
+	], platform, `codex's own \`mcp get\`, for the entry called "${name}"`)}. If it is not an older copy of this server, choose another --name; \`--print\` shows the entry to add by hand.` });
 	let answer;
 	try {
-		answer = await capture$1(env, binary, [
+		answer = await capture$1(env, cliPath, [
 			"mcp",
 			"get",
 			name,
@@ -4494,15 +4984,15 @@ async function backUp(context, client, name, previous, now) {
 async function installTarget(context, options) {
 	const apply = options.apply ?? true;
 	const cliName = options.client === "claude-code" ? "claude" : options.client === "codex" ? "codex" : null;
-	const binary = cliName ? await findClientCli(cliName, context.env) : null;
+	const cliPath = cliName ? await findClientCli(cliName, context.env) : null;
 	const own = knownClientConfigs(context.env).find((file) => file.client === options.client)?.path;
 	const configPath = options.client === "claude-code" ? void 0 : own;
 	return {
 		cliName,
-		binary,
+		cliPath,
 		own,
 		configPath,
-		writes: apply && (cliName ? binary !== null : configPath !== void 0)
+		writes: apply && (cliName ? cliPath !== null : configPath !== void 0)
 	};
 }
 /**
@@ -4534,14 +5024,14 @@ async function preflightInstall(context, product, options) {
 	const scan = await scanRegisteredServers(context.env);
 	const existing = scan.servers;
 	const target = await installTarget(context, options);
-	const { binary, own, configPath, writes } = target;
+	const { cliPath, own, configPath, writes } = target;
 	if (writes) {
 		const blind = scan.unreadable.find((file) => file.path === own);
 		if (blind) throw new CommsError("CONFIG", `${blind.path} could not be read (${blind.reason}), so what is already registered there cannot be checked; nothing was written`, { hint: "Fix the file, or add the entry by hand: `--print` shows it without writing anything." });
 	}
 	let previous = writes ? claimName(product, options, name, existing, context.platform) : [];
-	if (writes && binary && options.client === "codex") {
-		const reported = await codexRegistration(context.env, binary, name, configPath ?? "codex", context.platform);
+	if (writes && cliPath && options.client === "codex") {
+		const reported = await codexRegistration(context.env, cliPath, name, configPath ?? "codex", context.platform);
 		if (reported) previous = claimName(product, options, name, [reported], context.platform);
 	}
 	const { options: effective, kept } = keepNarrowing(product, options, previous);
@@ -4586,7 +5076,7 @@ function plannedInstall(preflight) {
 	return {
 		writes: target.writes,
 		cliName: target.cliName,
-		binary: target.binary,
+		cliPath: target.cliPath,
 		configPath: target.configPath ?? null,
 		own: target.own ?? null,
 		replaces: previous.map((server) => JSON.stringify([
@@ -4620,7 +5110,7 @@ function planDrift(product, client, name, planned, now) {
 	if (planned.writes !== now.writes) {
 		if (cli !== null) drift.push(now.writes ? `${cli} was not on PATH when this was planned, and is now, so it would register the server rather than print its entry` : `${cli} was on PATH when this was planned, and is not now, so it would only print the entry`);
 		else drift.push(now.writes ? "it would write the entry rather than print it" : "it would only print the entry");
-	} else if (planned.binary !== now.binary) drift.push(`it would register through another ${cli ?? "client CLI"} than the one planned: ${now.binary}`);
+	} else if (planned.cliPath !== now.cliPath) drift.push(`it would register through another ${cli ?? "client CLI"} than the one planned: ${now.cliPath}`);
 	if (planned.configPath !== now.configPath || planned.own !== now.own) drift.push(`${client}'s config is now ${now.own ?? now.configPath ?? "nowhere"}, not ${planned.own ?? planned.configPath ?? "nowhere"}`);
 	if (JSON.stringify(planned.replaces) !== JSON.stringify(now.replaces)) drift.push(`what is registered as "${name}" is not what it was planned to replace`);
 	if (JSON.stringify(planned.narrowing) !== JSON.stringify(now.narrowing)) {
@@ -4666,22 +5156,23 @@ async function mcpInstall(context, product, options, planned) {
 		...pinsOf(planned.narrowing)
 	};
 	const existing = scan.servers;
-	const { cliName, binary, own, configPath, writes } = target;
+	const { cliName, cliPath, own, configPath, writes } = target;
 	const warnings = (product.warnAbout?.(existing.filter((server) => server.client === options.client), context.platform) ?? []).filter(Boolean);
 	if (kept.length > 0) {
-		const removal = options.client === "claude-code" ? inlineCommand(shellCommand([
+		const byHand = `delete "${name}" from ${configPath}`;
+		const removal = options.client === "claude-code" ? clientCommandHint([
 			"claude",
 			"mcp",
 			"remove",
 			name,
 			"--scope",
 			"user"
-		], context.platform)) : options.client === "codex" ? inlineCommand(shellCommand([
+		], context.platform, byHand) : options.client === "codex" ? clientCommandHint([
 			"codex",
 			"mcp",
 			"remove",
 			name
-		], context.platform)) : `delete "${name}" from ${configPath}`;
+		], context.platform, byHand) : byHand;
 		warnings.push(`Kept ${kept.join(" ")} from the "${name}" entry this replaced, because this install did not say otherwise. To register it wider on purpose, remove that entry first (${removal}), then install without them.`);
 	}
 	if (!writes) {
@@ -4709,7 +5200,7 @@ async function mcpInstall(context, product, options, planned) {
 	let method = "printed";
 	let applied = false;
 	let notApplied;
-	if (cliName && binary && writes) {
+	if (cliName && cliPath && writes) {
 		const codexEnv = (values) => Object.entries(values ?? {}).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
 		const args = options.client === "claude-code" ? [
 			"mcp",
@@ -4741,13 +5232,13 @@ async function mcpInstall(context, product, options, planned) {
 				name
 			];
 			try {
-				await run(context.env, binary, removal);
+				await run(context.env, cliPath, removal);
 			} catch (error) {
 				const message = error instanceof CommsError ? error.message : String(error);
 				if (!/no (mcp )?server|not found|does not exist/i.test(message)) throw error;
 			}
 			try {
-				await run(context.env, binary, args);
+				await run(context.env, cliPath, args);
 			} catch (error) {
 				const restore = options.client === "claude-code" ? [
 					"mcp",
@@ -4771,31 +5262,36 @@ async function mcpInstall(context, product, options, planned) {
 				];
 				let restored = true;
 				try {
-					await run(context.env, binary, restore);
+					await run(context.env, cliPath, restore);
 				} catch {
 					restored = false;
 				}
-				throw new CommsError("CONFIG", restored ? `could not register "${name}"; the previous entry was put back` : `could not register "${name}", and the previous entry could not be put back either — ${cliName} now has no server called "${name}"`, {
-					hint: restored ? "Check the client is not running, then try again." : `Re-register it with ${inlineCommand(installCommand$1(product, effective, name, [], context.platform))}. The old entry is in ${backupPath}.`,
+				if (restored) throw new CommsError("CONFIG", `could not register "${name}"; the previous entry was put back`, {
+					hint: "Check the client is not running, then try again.",
 					cause: error
 				});
+				throw refusedWithRemedy("CONFIG", `could not register "${name}", and the previous entry could not be put back either — ${cliName} now has no server called "${name}"`, {
+					binary: product.binary,
+					words: installWords(product, effective, name, []),
+					say: (command) => `Re-register it with ${command}. The old entry is in ${backupPath}.`
+				}, { cause: error });
 			}
 		} else try {
-			await run(context.env, binary, args);
+			await run(context.env, cliPath, args);
 		} catch (error) {
 			const message = error instanceof CommsError ? error.message : String(error);
 			if (/already exists/i.test(message)) throw new CommsError("CONFIG", `${cliName} already has an MCP server called "${name}", somewhere this could not read`, {
-				hint: `Look at it with ${inlineCommand(shellCommand([
+				hint: `Look at it with ${clientCommandHint([
 					cliName,
 					"mcp",
 					"get",
 					name
-				], context.platform))}. If it is an older ${product.binary}, remove it with ${inlineCommand(shellCommand([
+				], context.platform, `${cliName}'s own \`mcp get\`, for the entry called "${name}"`)}. If it is an older copy of this server, remove it with ${clientCommandHint([
 					cliName,
 					"mcp",
 					"remove",
 					name
-				], context.platform))} and run this again; if not, choose another --name.`,
+				], context.platform, `${cliName}'s own \`mcp remove\``)} and run this again; if not, choose another --name.`,
 				cause: error
 			});
 			throw error;
@@ -5001,115 +5497,1033 @@ async function listManagedRuntimes(dataDir, packageName) {
 *    removes leaves the record with it. When the record cannot be read, nothing is removed;
 *  - never one a running process names. When the processes cannot be listed, nothing is removed at all.
 *
-* What it cannot see is an entry in a file it does not read — a workspace `.vscode/mcp.json`, a config a client
-* was pointed at on its command line — put there by hand, or pasted from a `--print` that warned its record could
-* not be written. The documents say so rather than promise more.
+* What it cannot see is an entry in a file it does not read — a workspace `.vscode/mcp.json`, a config a client
+* was pointed at on its command line — put there by hand, or pasted from a `--print` that warned its record could
+* not be written. The documents say so rather than promise more.
+*
+* `only`, when given, is the most it may remove: the runtimes a person approved removing, from a dry run shown to
+* them. Anything else it would have removed is kept, and says why. Removal is approved as a list of paths, and a
+* runtime that became unused after that list was shown is not on it.
+*/
+async function pruneManagedRuntimes(context, product, options = {}) {
+	const result = {
+		runtimeDir: join(context.core.paths.dataDir, "runtime"),
+		dryRun: options.dryRun === true,
+		removed: [],
+		kept: []
+	};
+	const candidates = [];
+	for (const { path, version } of await listManagedRuntimes(context.core.paths.dataDir, product.packageName)) {
+		const real = await realpath(path).catch(() => path);
+		candidates.push({
+			path,
+			version,
+			aliases: [.../* @__PURE__ */ new Set([path, real])]
+		});
+	}
+	if (candidates.length === 0) return result;
+	const refuse = (why) => {
+		result.refused = why;
+		result.kept = candidates.map(({ path, version }) => ({
+			path,
+			version,
+			reason: "not checked"
+		}));
+		return result;
+	};
+	const processes = await (options.processes ?? runningCommandLines)();
+	if (processes === null) return refuse("the running processes on this machine could not be listed, so none of these can be shown unused");
+	const ledger = handedOutRuntimesPath(context.core.paths.dataDir);
+	const handedOut = await readHandedOut(ledger);
+	if (handedOut === null) return refuse(`${ledger} could not be read, so none of these can be shown never to have been handed out`);
+	const recorded = handedOut.flatMap((record) => record.config ? [{
+		client: record.client,
+		path: record.config
+	}] : []);
+	const scan = await scanRegisteredServers(context.env, process.platform, recorded);
+	if (scan.unreadable.length > 0) return refuse(`${scan.unreadable.map((file) => `${file.path} (${file.reason})`).join("; ")} could not be read, so none of these can be shown unregistered`);
+	const registered = scan.servers;
+	const known = new Set(knownClientConfigs(context.env).map((file) => file.path));
+	const mentions = (aliases, text) => aliases.some((alias) => text === alias || text.includes(`${alias}${sep}`) || text.includes(`${alias}/`));
+	const current = managedRuntimeDir(context.core.paths.dataDir, product.packageName, product.version);
+	for (const { path, version, aliases } of candidates) {
+		const owner = registered.find((server) => [server.command, ...server.args].some((part) => mentions(aliases, part)));
+		const printed = options.includePrinted ? void 0 : handedOut.find((record) => !record.applied && mentions(aliases, record.runtime));
+		const reason = path === current ? "this release" : owner ? `registered with ${owner.client} as "${owner.name}"${known.has(owner.path) ? "" : ` in ${owner.path}`}` : printed ? `printed for ${printed.client} as "${printed.name}" on ${printed.at.slice(0, 10)}, and where that entry went cannot be read; once it is gone, \`mcp prune --include-printed\` removes this` : processes.some((line) => mentions(aliases, line)) ? "a running process uses it" : null;
+		if (reason) {
+			result.kept.push({
+				path,
+				version,
+				reason
+			});
+			continue;
+		}
+		if (options.only !== void 0 && !options.only.includes(path)) {
+			result.kept.push({
+				path,
+				version,
+				reason: "not in the removal that was approved; prune again to include it"
+			});
+			continue;
+		}
+		if (!result.dryRun) await rm(path, { recursive: true });
+		result.removed.push({
+			path,
+			version
+		});
+	}
+	if (options.includePrinted && !result.dryRun && result.removed.length > 0) {
+		const gone = result.removed.map((item) => item.path);
+		const left = handedOut.filter((record) => !gone.some((path) => mentions([path], record.runtime)));
+		if (left.length !== handedOut.length) await writeFileAtomic(ledger, left.map((record) => `${JSON.stringify(record)}\n`).join(""));
+	}
+	return result;
+}
+/** Every runtime the installer handed out, or null when the record is there and cannot be read. */
+async function readHandedOut(path) {
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		return error.code === "ENOENT" ? [] : null;
+	}
+	const records = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const record = JSON.parse(line);
+			if (typeof record.runtime !== "string") return null;
+			records.push({
+				at: String(record.at ?? ""),
+				client: String(record.client ?? ""),
+				name: String(record.name ?? ""),
+				runtime: record.runtime,
+				...typeof record.config === "string" ? { config: record.config } : {},
+				...record.applied === true ? { applied: true } : {}
+			});
+		} catch {
+			return null;
+		}
+	}
+	return records;
+}
+/** A channel's registration facts, from its manifest. */
+function registrationFactsOf({ packageName, manifest }) {
+	return {
+		packageName,
+		npxPackage: manifest.server.npxPackage,
+		binary: manifest.binary,
+		...manifest.server.bins === void 0 ? {} : { bins: manifest.server.bins },
+		...manifest.server.entryFiles === void 0 ? {} : { entryFiles: manifest.server.entryFiles }
+	};
+}
+/** How a registered entry starts its server: the launcher `mcp install` wrote it with, or `other` for one it did not. */
+function launcherOf(server, facts, platform) {
+	const fold = folding(platform);
+	const parts = [server.command, ...server.args];
+	if (parts.some((part) => managedRuntimeVersion(part, facts.packageName, platform) !== null)) return "managed";
+	if (server.args.some((arg) => fold(arg).startsWith(fold(`${facts.npxPackage}@`)))) return "npx";
+	const local = new RegExp("[/\\\\]packages[/\\\\][^/\\\\]+[/\\\\](?:src[/\\\\]cli\\.ts|dist[/\\\\]cli\\.mjs)$", platform === "win32" ? "i" : "");
+	if (parts.some((part) => local.test(part))) return "local";
+	return "other";
+}
+/** The version an entry pins — a managed runtime's or an npx spec's — or null for one that pins none. */
+function registrationVersion(server, facts, platform) {
+	return server.args.map((arg) => pinnedVersion(arg, facts, platform)).find((found) => found !== null) ?? null;
+}
+PATH_OPTIONS.filter(({ key }) => key !== "downloadsDir");
+/**
+* Whether an entry starts this product, judged on its own words: the suite's path options and their values are taken
+* out, and the package its command line launches is read again from what is left rather than taken from the entry.
+* A folder pinned as `/tmp/@agentcomms/slack` never makes a Gmail registration Slack's.
+*/
+function startsProduct(server, facts, platform) {
+	const { words: args } = withoutPathOptions(server.args);
+	const packageName = commandLinePackage(server.command, args);
+	return isProductServer({
+		command: server.command,
+		args,
+		...packageName === void 0 ? {} : { packageName }
+	}, facts, platform);
+}
+/**
+* A command's name as Windows finds it — its last path segment without `.cmd`, `.exe`, `.bat` or `.ps1` — without case
+* on Windows (`platform`), and exactly elsewhere.
+*/
+function commandStem(command, platform) {
+	return folding(platform)((command.split(/[\\/]+/).at(-1) ?? "").replace(/\.(?:cmd|exe|bat|ps1)$/i, ""));
+}
+/** Whether npx runs the entry: its program is npx, or it names the product's package at a version, as npx does. */
+function isNpxRegistration(server, facts, platform) {
+	return commandStem(server.command, platform) === "npx" || launcherOf(server, facts, platform) === "npx";
+}
+/**
+* The files an entry names as what it starts, as it writes them: every script among its words before `--` once the
+* path options are out (an interpreter's flags may name one too, so each is a candidate, not the answer), and its
+* program when that is one of the product's own commands — a link into the package, or a script npm wrote beside it.
+*/
+function registrationFiles(server, facts, platform) {
+	const { words } = withoutPathOptions(server.args);
+	const sentinel = words.indexOf("--");
+	const options = sentinel < 0 ? words : words.slice(0, sentinel);
+	const fold = folding(platform);
+	return {
+		scripts: options.flatMap((word) => [word, ...word.startsWith("--") && word.includes("=") ? [word.slice(word.indexOf("=") + 1)] : []]).filter((word) => !word.startsWith("-") && /\.(?:[cm]?js|[cm]?ts)$/i.test(word)),
+		command: [facts.binary, ...facts.bins ?? []].map(fold).includes(commandStem(server.command, platform)) ? server.command : null
+	};
+}
+function folding(platform) {
+	return platform === "win32" ? (text) => text.toLowerCase() : (text) => text;
+}
+/** The package version, read from package.json at build time. */
+const VERSION = "0.13.1";
+/**
+* Versions as semver writes and orders them — what an update compares, and what the daily update check's reader needs
+* to decide whether the release it last heard of is newer than the one running.
+*
+* Here rather than in `npm.ts`, which also talks to the registry: the reader of `update-check.json` is imported by
+* every server, WhatsApp's included, and must carry no network code at all (design 2026-09-28 §1). `npm.ts` re-exports
+* all of it, so nothing that imported these from there changes.
+*/
+/**
+* A version, exactly as semver writes one: `1.2.3`, `1.2.3-rc.1`, `1.2.3+build`.
+*
+* Anything the registry answers is checked against this before it is used, because a version goes into a directory
+* name (`runtime/<version>-gmail`), a sentence a person approves, and an argument to `npm install`. A registry — or a
+* mirror somebody configured — that answered `../x` or `1.0.0 && …` would otherwise put that in all three.
+*/
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+function isVersion(value) {
+	return typeof value === "string" && VERSION_PATTERN.test(value);
+}
+/** Two numeric strings with no leading zeros, compared as numbers of any size. */
+function compareNumeric(a, b) {
+	if (a.length !== b.length) return a.length < b.length ? -1 : 1;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+* Semver precedence: -1, 0 or 1, or null when either is not a version.
+*
+* Numbers compare as numbers (`0.10.0` is after `0.9.9`), a prerelease comes before its release, and build metadata
+* counts for nothing. Written out rather than taken from a dependency: it is twenty lines, and the core installs as
+* few packages as it can.
+*/
+function compareVersions(a, b) {
+	const left = VERSION_PATTERN.exec(a);
+	const right = VERSION_PATTERN.exec(b);
+	if (!left || !right) return null;
+	for (const index of [
+		1,
+		2,
+		3
+	]) {
+		const order = compareNumeric(left[index] ?? "0", right[index] ?? "0");
+		if (order !== 0) return order < 0 ? -1 : 1;
+	}
+	const pre = (match) => match[4] === void 0 ? [] : match[4].split(".");
+	const [ours, theirs] = [pre(left), pre(right)];
+	if (ours.length === 0 || theirs.length === 0) return ours.length === theirs.length ? 0 : ours.length === 0 ? 1 : -1;
+	for (let index = 0; index < Math.max(ours.length, theirs.length); index += 1) {
+		const x = ours[index];
+		const y = theirs[index];
+		if (x === void 0) return -1;
+		if (y === void 0) return 1;
+		const [numericX, numericY] = [/^\d+$/.test(x), /^\d+$/.test(y)];
+		if (numericX && numericY) {
+			const order = compareNumeric(x, y);
+			if (order !== 0) return order < 0 ? -1 : 1;
+		} else if (numericX !== numericY) return numericX ? -1 : 1;
+		else if (x !== y) return x < y ? -1 : 1;
+	}
+	return 0;
+}
+/** Whether `version` is older than `latest`: by semver when both are versions, and otherwise whenever they differ. */
+function isBehind(version, latest) {
+	if (version === latest) return false;
+	const order = compareVersions(version, latest);
+	return order === null ? true : order < 0;
+}
+/**
+* Whether a version is a prerelease — `0.8.0-rc.1` — which the daily update check never counts as an update: a
+* machine is not told to "update" to a release candidate, nor a candidate told to go back to the last release.
+*/
+function isPrerelease(version) {
+	return VERSION_PATTERN.exec(version)?.[4] !== void 0;
+}
+/**
+* Whether `version` is within a package's `engines` range: true or false, or null when the range is not one this reads.
+*
+* Read are the comparators `>=`, `>`, `<=`, `<` and `=` (or none) before a whole version, joined by spaces, which must
+* all hold, and alternatives joined by `||`. That is every range this suite declares (`>=22.12.0`, `>=22.16.0`).
+* Anything else — `^22.12.0`, `>=22`, `22.x` — is null rather than a guess: a command printed to run under this Node
+* is printed only when the range it has to meet says it may. A leading `v`, as `process.version` has it, is read.
+*/
+function satisfiesRange(version, range) {
+	const wanted = version.replace(/^v/, "");
+	if (!isVersion(wanted)) return null;
+	const alternatives = range.split("||").map((alternative) => alternative.trim().split(/\s+/).filter(Boolean));
+	if (alternatives.some((comparators) => comparators.length === 0)) return null;
+	let any = false;
+	for (const comparators of alternatives) {
+		let all = true;
+		for (const comparator of comparators) {
+			const match = /^(>=|<=|>|<|=)?(.+)$/.exec(comparator);
+			const bound = match?.[2] ?? "";
+			if (!isVersion(bound)) return null;
+			const order = compareVersions(wanted, bound);
+			if (!(match?.[1] === ">=" ? order >= 0 : match?.[1] === "<=" ? order <= 0 : match?.[1] === ">" ? order > 0 : match?.[1] === "<" ? order < 0 : order === 0)) all = false;
+		}
+		if (all) any = true;
+	}
+	return any;
+}
+/**
+* The command a person is told to run for one of this suite's own CLIs (design 2026-10-04, D1 and D5; CUE-403).
+*
+* A bare `agent-gmail approve …` is not runnable for most of the people it is printed for: a package run by npx, by a
+* managed runtime or from a checkout puts nothing on their PATH. So every such command names this process's Node and
+* a checked file of the product it runs, with the suite directories it uses pinned as options — and when no file can
+* be checked, there is no command at all, only a sentence saying what is missing. The caller says which package it is
+* and what to run; it never supplies the program or quotes the line.
+*
+* Three directions. A product's own CLI is found from the product itself, walking from one of its own modules to its
+* manifest: no registration is ever asked. A channel's handoff to core is found the way the channel itself finds core,
+* through its installed dependency, and only the same release. Another product's command is found among the servers
+* registered with the person's MCP clients, which the caller scanned and passes in: only a file-backed registration of
+* exactly the printing package's version, checked on disk. Nothing a registration names is run, or asked anything —
+* not even its interpreter for a version: no installer wrote down where a scanned entry came from, so none is trusted
+* to run (D1). This module never scans, spawns or probes.
+*
+* What is checked is checked when the command is printed, not for ever (D6): the file it names is real, readable and
+* inside its package then, and a later change to that installation is a later fact.
+*/
+/** The gate a constructor call has to pass: only this module holds it. */
+const GATE = Symbol("locateCliCommand");
+/**
+* A command that runs one of this suite's own CLIs, made only by `locateCliCommand`. Rendered as every printed command
+* is — a line to paste, or on Windows its words as JSON when no line is safe in every shell (`inlineCommand`,
+* `commandText`).
+*
+* A class with a private field, so the type is nominal: an object literal with the same fields is not one, and nor is
+* a spread copy of one with other words in it, as it would be with a symbol-keyed brand. Only the type is exported;
+* the class and its gate are not.
+*/
+var PrintedCommand = class {
+	#entry;
+	/** The words, as the program is to receive them: this Node, its flags, the entry, then the CLI's own words. */
+	words;
+	/** The line to paste; null when one of the words has no printing that every Windows shell passes on alike. */
+	line;
+	platform;
+	constructor(gate, words, platform, entry) {
+		if (gate !== GATE) throw new TypeError("a printed command is made by locateCliCommand, and only there");
+		this.#entry = entry;
+		this.words = Object.freeze([...words]);
+		this.line = quoteCommand(this.words, platform).line;
+		this.platform = platform;
+		Object.freeze(this);
+	}
+	/**
+	* The real path of the file it runs, as it was checked when the command was located: a fact about then (D6). The
+	* command names this path and nothing else, so what runs is whatever is there when the person runs it.
+	*/
+	get entry() {
+		return this.#entry;
+	}
+	/**
+	* As JSON — a result's field written out by `--json`, or returned to an MCP client — it is the text it always was:
+	* its line, or its words as JSON with what to do when no Windows line is safe (`commandText`). Rendered where it
+	* leaves the process, so a field can hold the command itself and the wire stays the same.
+	*/
+	toJSON() {
+		return quotedText(this);
+	}
+	/** Never interpolated: a sentence gives a command through `handoffSentence`, a value through `handoffText`. */
+	[Symbol.toPrimitive]() {
+		throw new TypeError("a printed command is rendered with handoffText or handoffSentence, never interpolated");
+	}
+};
+const STRIP_TYPES = "--experimental-strip-types";
+const TRANSFORM_TYPES = "--experimental-transform-types";
+/** The suite's packages, by name, and its channel packages, which reach core through their own dependency on it. */
+const SUITE_PACKAGES = new Set(CHANNEL_SNAPSHOT.map(({ packageName }) => packageName));
+const CHANNEL_PACKAGES$1 = new Set(CHANNEL_SNAPSHOT.filter(({ manifest }) => manifest.channel !== "core").map(({ packageName }) => packageName));
+/**
+* Locates the command that runs `request.target`'s CLI with `request.words`, or says why there is none.
+*
+* The program is always this process's Node (`process.execPath`), which must satisfy the target's `engines.node`; no
+* interpreter named anywhere else is run, or asked its version. A TypeScript entry gets `--experimental-strip-types`,
+* which Node 22.12–22.17 needs, and `--experimental-transform-types` only when this source run was started with it;
+* no other flag this process was started with is carried — debug, preload, condition and memory flags are not what the
+* CLI needs. The suite directories the command uses go between the entry and its words, one canonical option each,
+* before any `--`.
+*
+* Synchronous, so a hint or a renderer can call it where it builds its sentence; for another product the caller scans
+* the registrations first and passes them in (`request.registrations`).
+*/
+function locateCliCommand(request, runtime = {
+	version: process.version,
+	execArgv: process.execArgv
+}) {
+	const { caller, target } = request;
+	const [first] = request.words;
+	if (first !== void 0 && (isAbsolute(first) || suiteCommandOf(first) !== null)) throw new TypeError(`the words to run start after the program: ${JSON.stringify(first)} is one`);
+	const platform = request.platform ?? process.platform;
+	let version = VERSION;
+	const fail = (reason, detail, extra = {}) => notLocated(target, version, reason, detail, runtime.version, extra);
+	let callerFile;
+	try {
+		callerFile = fileURLToPath(caller.url);
+	} catch {
+		return fail("caller", `${caller.url} is not a module on this machine`);
+	}
+	const callerSource = callerFile.endsWith(".ts");
+	const nearest = nearestPackage(dirname(callerFile));
+	const callerManifest = nearest?.manifest ?? null;
+	if (nearest === null || callerManifest === null || callerManifest.name !== caller.packageName) {
+		const name = typeof callerManifest?.name === "string" ? callerManifest.name : "no named package";
+		return fail("manifest", `the package ${callerFile} belongs to is ${name}, not ${caller.packageName}`);
+	}
+	const callerVersion = typeof callerManifest.version === "string" ? callerManifest.version : null;
+	if (callerVersion !== null) version = callerVersion;
+	let callerRoot;
+	try {
+		callerRoot = realpathSync(nearest.root);
+	} catch {
+		return fail("caller", `${nearest.root} cannot be resolved`);
+	}
+	if (!isAbsolute(process.execPath)) return fail("interpreter", `this Node, ${process.execPath}, is not a full path`);
+	const pins = {};
+	for (const key of request.uses) pins[key] = request.paths[key];
+	let words;
+	try {
+		words = normalizePathOptionWords(request.words, pins, 0);
+	} catch (error) {
+		return fail("arguments", error instanceof Error ? error.message : String(error));
+	}
+	const build = (found) => buildCommand(target, found, words, runtime, callerSource, platform);
+	const located = (built, found, direction) => Object.freeze({
+		ok: true,
+		command: built.command,
+		basis: Object.freeze({
+			callerSource,
+			callerRoot,
+			callerVersion,
+			targetRoot: found.root,
+			targetVersion: typeof found.manifest.version === "string" ? found.manifest.version : null,
+			callerWorkspace: null,
+			targetWorkspace: null,
+			entryKind: built.entryKind,
+			...direction
+		})
+	});
+	if (caller.packageName === target.packageName) {
+		const found = {
+			root: callerRoot,
+			manifest: callerManifest,
+			source: callerSource
+		};
+		const built = build(found);
+		if (!built.ok) return fail(built.reason, built.detail, { nodeRange: built.nodeRange });
+		return located(built, found, {
+			direction: "own",
+			sameCheckout: true
+		});
+	}
+	if (target.manifest.channel === "core" && CHANNEL_PACKAGES$1.has(caller.packageName)) {
+		const installed = installedPackage(dirname(callerFile), target.packageName);
+		if (installed === null) return fail("core", `${caller.packageName} has no ${target.packageName} installed where it can find one`);
+		const manifest = readPackageManifest(installed);
+		if (manifest === null || manifest.name !== target.packageName) return fail("manifest", `the package found as ${target.packageName}, at ${installed}, is not that package`);
+		if (manifest.version !== version) {
+			const theirs = typeof manifest.version === "string" ? manifest.version : "of no version";
+			return fail("version", `${caller.packageName} ${version} finds ${target.packageName} ${theirs}, at ${installed}`);
+		}
+		const callerWorkspace = workspaceOf(callerRoot);
+		const targetWorkspace = workspaceOf(installed);
+		const sameCheckout = callerWorkspace !== null && callerWorkspace === targetWorkspace;
+		const found = {
+			root: installed,
+			manifest,
+			source: callerSource && sameCheckout
+		};
+		const built = build(found);
+		if (!built.ok) return fail(built.reason, built.detail, { nodeRange: built.nodeRange });
+		return located(built, found, {
+			direction: "channel-to-core",
+			callerWorkspace,
+			targetWorkspace,
+			sameCheckout
+		});
+	}
+	if (!SUITE_PACKAGES.has(caller.packageName)) return fail("direction", `${caller.packageName} is not a package of this suite`);
+	if (request.registrations === void 0) return fail("no-registrations", "nothing registered was given to look through for another product's command");
+	const facts = registrationFactsOf(target);
+	const notUsed = [];
+	const usable = [];
+	let engineRange;
+	for (const server of request.registrations) {
+		if (!startsProduct(server, facts, platform)) continue;
+		const reject = (why) => notUsed.push(Object.freeze({
+			client: server.client,
+			path: server.path,
+			name: server.name,
+			why
+		}));
+		if (isNpxRegistration(server, facts, platform)) {
+			reject("npx");
+			continue;
+		}
+		if (withoutPathOptions(server.args).dangling) {
+			reject("arguments");
+			continue;
+		}
+		const launcher = launcherOf(server, facts, platform);
+		const files = registrationFiles(server, facts, platform);
+		if (![...files.scripts, ...files.command === null ? [] : [files.command]].some((file) => isAbsolute(file))) {
+			reject("no-file");
+			continue;
+		}
+		const found = registeredPackage(files, target, facts);
+		if (found === null) {
+			reject("no-package");
+			continue;
+		}
+		const managedAt = launcher === "managed" ? registrationVersion(server, facts, platform) : version;
+		if (found.manifest.version !== version || managedAt !== version) {
+			reject("version");
+			continue;
+		}
+		const built = build(found);
+		if (!built.ok) {
+			reject(built.reason);
+			if (built.reason === "engine") engineRange ??= built.nodeRange;
+			continue;
+		}
+		usable.push({
+			server,
+			launcher,
+			built,
+			found
+		});
+	}
+	const rank = ({ server, launcher }) => [
+		launcher === "managed" ? "0" : "1",
+		server.client,
+		server.path,
+		server.name,
+		server.command,
+		...server.args
+	];
+	const [best] = usable.sort((a, b) => compareWords(rank(a), rank(b)));
+	if (best === void 0) {
+		if (engineRange !== void 0) return fail("engine", `it needs Node ${engineRange}, and this is Node ${runtime.version}`, {
+			nodeRange: engineRange,
+			registrations: notUsed
+		});
+		return fail("not-registered", notRegistered(notUsed, version), { registrations: notUsed });
+	}
+	const { client, path, name } = best.server;
+	return located(best.built, best.found, {
+		direction: "cross-product",
+		sameCheckout: false,
+		registration: Object.freeze({
+			client,
+			path,
+			name,
+			launcher: best.launcher
+		})
+	});
+}
+/**
+* Checks what was found and makes its command: the target's Node range against this Node, then the entry — the source
+* CLI or the manifest's bin for the command it declares — as a readable file inside its package.
+*/
+function buildCommand(target, found, words, runtime, callerSource, platform) {
+	const engines = found.manifest.engines;
+	const range = typeof engines === "object" && engines !== null ? engines.node : void 0;
+	if (typeof range !== "string") return {
+		ok: false,
+		reason: "engine",
+		detail: `${target.packageName} at ${found.root} declares no Node range this can check`
+	};
+	if (satisfiesRange(runtime.version, range) !== true) return {
+		ok: false,
+		reason: "engine",
+		detail: `it needs Node ${range}, and this is Node ${runtime.version}`,
+		nodeRange: range
+	};
+	let entry;
+	if (found.source) entry = join(found.root, "src", "cli.ts");
+	else {
+		const declared = found.manifest.agentcomms;
+		const binary = typeof declared === "object" && declared !== null ? declared.binary : void 0;
+		const bin = found.manifest.bin;
+		const path = binary === target.manifest.binary && typeof bin === "object" && bin !== null && Object.hasOwn(bin, target.manifest.binary) ? bin[target.manifest.binary] : void 0;
+		if (typeof path !== "string" || path.length === 0) return {
+			ok: false,
+			reason: "bin",
+			detail: `the bin of ${target.packageName} at ${found.root} does not name the command it declares`
+		};
+		entry = resolve(found.root, path);
+	}
+	const checked = checkedEntry(found.root, entry);
+	if (checked.ok === false) return {
+		ok: false,
+		reason: "entry",
+		detail: checked.why
+	};
+	const flags = /\.[cm]?ts$/.test(checked.path) ? [STRIP_TYPES, ...callerSource && runtime.execArgv.includes(TRANSFORM_TYPES) ? [TRANSFORM_TYPES] : []] : [];
+	return {
+		ok: true,
+		command: new PrintedCommand(GATE, [
+			process.execPath,
+			...flags,
+			checked.path,
+			...words
+		], platform, checked.path),
+		entryKind: found.source ? "source" : "bin"
+	};
+}
+/**
+* The target's package a registration's files lead to, or null: a script it starts, real or as written when it is
+* gone, inside the package (or inside the product's own server wrapper, which depends on it); or, for the product's
+* own command, the package that command links into or that npm installed beside it.
+*/
+function registeredPackage(files, target, facts) {
+	for (const script of files.scripts) {
+		if (!isAbsolute(script)) continue;
+		const found = packageAround(script, target, facts);
+		if (found !== null) {
+			const source = join(found.root, "src", "cli.ts");
+			const real = realpathOfExisting(script);
+			return {
+				...found,
+				source: real !== null && sameFile(real, source)
+			};
+		}
+	}
+	const { command } = files;
+	if (command === null || !isAbsolute(command)) return null;
+	const linked = packageAround(command, target, facts);
+	if (linked !== null) return {
+		...linked,
+		source: false
+	};
+	const dir = dirname(command);
+	for (const candidate of [join(dir, "node_modules"), join(dir, "..", "lib", "node_modules")]) {
+		let root;
+		try {
+			root = realpathSync(join(candidate, ...target.packageName.split("/")));
+		} catch {
+			continue;
+		}
+		const manifest = readPackageManifest(root);
+		if (manifest?.name === target.packageName) return {
+			root,
+			manifest,
+			source: false
+		};
+	}
+	return null;
+}
+/** The target's package that `file` is in — directly, or through the product's server wrapper, which depends on it. */
+function packageAround(file, target, facts) {
+	const real = realpathOfExisting(file);
+	if (real === null) return null;
+	const nearest = nearestPackage(dirname(real));
+	if (nearest === null || nearest.manifest === null) return null;
+	let root;
+	try {
+		root = realpathSync(nearest.root);
+	} catch {
+		return null;
+	}
+	if (nearest.manifest.name === target.packageName) return {
+		root,
+		manifest: nearest.manifest
+	};
+	if (facts.npxPackage === target.packageName || nearest.manifest.name !== facts.npxPackage) return null;
+	const installed = installedPackage(root, target.packageName);
+	const manifest = installed === null ? null : readPackageManifest(installed);
+	return installed !== null && manifest?.name === target.packageName ? {
+		root: installed,
+		manifest
+	} : null;
+}
+function sameFile(a, b) {
+	try {
+		return realpathSync(a) === realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+/** Two lists of words in order: the first that differs decides, and a list that runs out first comes first. */
+function compareWords(a, b) {
+	for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+		const [x, y] = [a[index], b[index]];
+		if (x !== y) return x < y ? -1 : 1;
+	}
+	return a.length - b.length;
+}
+/** Why no registration of another product could be used, in a clause: how many were looked at, and what each was. */
+function notRegistered(notUsed, version) {
+	if (notUsed.length === 0) return "no MCP client on this machine has it registered";
+	const said = {
+		npx: "run by npx, which is never used for this",
+		arguments: "with a path option that has no value",
+		"no-file": "not started from a file named by its full path",
+		"no-package": "whose package cannot be found or read",
+		version: "of another or an unknown version",
+		engine: "whose Node range this Node is outside, or which declares none",
+		bin: "whose package does not name its command",
+		entry: "whose command file is missing, unreadable or outside its package"
+	};
+	const counts = /* @__PURE__ */ new Map();
+	for (const { why } of notUsed) counts.set(why, (counts.get(why) ?? 0) + 1);
+	const parts = [...counts].map(([why, count]) => `${count} ${said[why]}`);
+	return `none of ${notUsed.length === 1 ? "the 1 registration" : `the ${notUsed.length} registrations`} of it is ${version} in a file this can check (${parts.join("; ")})`;
+}
+function notLocated(target, version, reason, detail, nodeVersion, extra) {
+	const named = `${target.manifest.label} ${version} (${target.packageName})`;
+	const { nodeRange, registrations } = extra;
+	const message = nodeRange === void 0 ? `${named} is not locatable here: ${detail}. Install or update it through your usual route, then try again.` : `${named} needs Node ${nodeRange}, and this is Node ${nodeVersion}, so there is no command to run it with here. Run it again under a Node in that range.`;
+	const notLocated = {
+		ok: false,
+		reason,
+		product: target.manifest.label,
+		package: target.packageName,
+		version,
+		...nodeRange === void 0 ? {} : { nodeRange },
+		...registrations === void 0 ? {} : { registrations: Object.freeze([...registrations]) },
+		detail,
+		message
+	};
+	Object.defineProperties(notLocated, {
+		toJSON: { value: () => message },
+		[Symbol.toPrimitive]: { value: () => {
+			throw new TypeError("a missing command is said with handoffText or handoffSentence, never interpolated");
+		} }
+	});
+	return Object.freeze(notLocated);
+}
+/**
+* The entry's real path, when it is a readable regular file inside its package's real root by whole segments — as
+* written and after links are resolved — or why not.
+*
+* Checked now, for the command printed now (D6). This does not make the path durable: an npx cache evicted, a global
+* install upgraded in place or a file replaced after this is what the command meets when it runs — a missing file
+* fails with Node's own error naming it, a replaced one runs as it then is. Nothing here, or in the command, looks
+* anywhere else for the product, PATH included, and a later locate checks the path again.
+*/
+function checkedEntry(root, entry) {
+	if (!isWithin(root, entry)) return {
+		ok: false,
+		why: `${entry} is outside its package, ${root}`
+	};
+	let real;
+	try {
+		real = realpathSync(entry);
+	} catch {
+		return {
+			ok: false,
+			why: `${entry} is not there`
+		};
+	}
+	if (!isWithin(root, real)) return {
+		ok: false,
+		why: `${entry} leads to ${real}, outside its package, ${root}`
+	};
+	try {
+		if (!statSync(real).isFile()) return {
+			ok: false,
+			why: `${entry} is not a file`
+		};
+		accessSync(real, constants$1.R_OK);
+	} catch {
+		return {
+			ok: false,
+			why: `${entry} cannot be read`
+		};
+	}
+	return {
+		ok: true,
+		path: real
+	};
+}
+/**
+* The real root of the package `name` installed for a module in `start`, found as Node's own resolution finds one: in
+* `node_modules` of each directory from there up. Not resolved through its `exports` — core's point at a build, and
+* which entry to run is decided here — and never from a global folder, which `import` does not read either.
+*/
+function installedPackage(start, name) {
+	let dir = resolve(start);
+	for (;;) {
+		if (basename(dir) !== "node_modules") {
+			const candidate = join(dir, "node_modules", ...name.split("/"));
+			try {
+				if (statSync(candidate).isDirectory()) return realpathSync(candidate);
+			} catch {}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/**
+* The real repository checkout whose workspace lists `root` as one of its packages, or null: the nearest
+* `pnpm-workspace.yaml` above it, and its `packages` globs. A package under the checkout but not one of them — an
+* installed copy in its `node_modules` — is not a workspace package of it.
+*/
+function workspaceOf(root) {
+	let dir = dirname(root);
+	for (;;) {
+		const globs = workspaceGlobs(dir);
+		if (globs !== null) return inWorkspace(relative(dir, root).split(sep), globs) ? dir : null;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/** The `packages` globs of `dir/pnpm-workspace.yaml`, or null when there is no such file. */
+function workspaceGlobs(dir) {
+	let text;
+	try {
+		text = readFileSync(join(dir, "pnpm-workspace.yaml"), "utf8");
+	} catch (error) {
+		const code = error.code;
+		return code === "ENOENT" || code === "ENOTDIR" ? null : [];
+	}
+	const unquote = (glob) => glob.trim().replace(/^(['"])(.*)\1$/, "$2");
+	const lines = text.split(/\r?\n/);
+	const at = lines.findIndex((line) => /^packages\s*:/.test(line));
+	if (at < 0) return [];
+	const inline = /^packages\s*:\s*\[(.*)\]\s*(?:#.*)?$/.exec(lines[at]);
+	if (inline) return (inline[1] ?? "").split(",").map(unquote).filter(Boolean);
+	const globs = [];
+	for (const line of lines.slice(at + 1)) {
+		if (/^\s*(?:#.*)?$/.test(line)) continue;
+		const item = /^\s+-\s*(.*?)\s*(?:#.*)?$/.exec(line);
+		if (!item) break;
+		globs.push(unquote(item[1] ?? ""));
+	}
+	return globs;
+}
+/** Whether a path, as segments from the workspace root, is one of its packages: some glob takes it and no `!` one. */
+function inWorkspace(segments, globs) {
+	const matches = (glob) => segmentsMatch(segments, glob.replace(/^\.\//, "").replace(/\/+$/, "").split("/").filter((part) => part !== "."));
+	const included = globs.filter((glob) => !glob.startsWith("!"));
+	const excluded = globs.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+	return included.some(matches) && !excluded.some(matches);
+}
+function segmentsMatch(path, pattern) {
+	const [head, ...rest] = pattern;
+	if (head === void 0) return path.length === 0;
+	if (head === "**") return segmentsMatch(path, rest) || path.length > 0 && segmentsMatch(path.slice(1), pattern);
+	const [segment] = path;
+	if (segment === void 0) return false;
+	return new RegExp(`^${head.split("*").map(escapeRegExp$1).join("[^/]*")}$`).test(segment) && segmentsMatch(path.slice(1), rest);
+}
+function escapeRegExp$1(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* The commands a package tells a person to run, made once per printing process (design 2026-10-04, D1 and D5;
+* CUE-403). How a channel migrates a handoff to these is in CONTRIBUTING.md, "Telling a person what to run".
+*
+* A package makes them from where it is — a module of its own and its package name, the caller — with the folders and
+* shell of the process printing: `openCore({ caller })` puts them on `core.handoffs`. Each method takes the CLI's own
+* words, never the program, and returns a `Handoff`: a located `PrintedCommand`, or why there is none here. Nothing
+* here quotes a line by hand, names a bare binary, or guesses an installation.
+*/
+/** The suite folders every CLI command opens: what a command is pinned to unless it says otherwise. */
+const HANDOFF_FOLDERS = Object.freeze([
+	"configDir",
+	"stateDir",
+	"dataDir",
+	"secretsDir"
+]);
+Object.freeze({
+	url: import.meta.url,
+	packageName: "@agentcomms/core"
+});
+/** A channel of this release, by its word; a programming error for a word that is none. */
+function entryOf$1(channel) {
+	const entry = CHANNEL_SNAPSHOT.find((each) => each.manifest.channel === channel);
+	if (entry === void 0) throw new TypeError(`"${channel}" is not a channel of this release`);
+	return entry;
+}
+/** The folders a command is pinned to. */
+function usesOf(use) {
+	return [...use?.uses ?? HANDOFF_FOLDERS, ...use?.downloads ? ["downloadsDir"] : []];
+}
+/** The commands a package prints, located from `caller` (CONTRIBUTING.md, "Telling a person what to run"). */
+function cliHandoffs(options) {
+	const { caller, paths, registrations } = options;
+	const platform = options.platform ?? process.platform;
+	const own = CHANNEL_SNAPSHOT.find((entry) => entry.packageName === caller.packageName);
+	if (own === void 0) throw new TypeError(`${caller.packageName} is not a package of this suite`);
+	const locate = (target, words, use) => {
+		const result = locateCliCommand({
+			caller,
+			target,
+			words,
+			uses: usesOf(use),
+			paths,
+			platform,
+			...registrations === void 0 ? {} : { registrations }
+		}, ...options.runtime === void 0 ? [] : [options.runtime]);
+		return result.ok ? result.command : result;
+	};
+	const handoffs = Object.freeze({
+		caller,
+		platform,
+		own: (words, use) => locate(own, words, use),
+		core: (words, use) => locate(entryOf$1("core"), words, use),
+		of: (channel, words, use) => locate(entryOf$1(channel), words, use),
+		on: (other) => other === platform ? handoffs : cliHandoffs({
+			...options,
+			platform: other
+		}),
+		registered: async () => cliHandoffs({
+			...options,
+			registrations: (await scanRegisteredServers(options.env ?? process.env, platform)).servers
+		}),
+		withRegistrations: (servers) => cliHandoffs({
+			...options,
+			registrations: servers
+		})
+	});
+	return handoffs;
+}
+/**
+* `core.handoffs` — quoted for `platform` when one is given — for anything that prints a command. A programming error
+* when core was opened without its caller: the package has to give it one (`openCore({ caller })`), and there is no
+* bare name to print instead.
+*/
+function requireHandoffs(core, platform) {
+	const handoffs = requiredHandoffs(core.handoffs);
+	return platform === void 0 ? handoffs : handoffs.on(platform);
+}
+const MAP = {
+	inbox: "inboxes",
+	account: "accounts"
+};
+/**
+* An own property only.
+*
+* A name is user input and the maps are plain objects, so `config.inboxes.constructor` is a function — and a lookup
+* of an inbox called `constructor`, which version 1 allows, found it.
+*/
+function own$1(map, key) {
+	return Object.hasOwn(map, key) ? map[key] : void 0;
+}
+function resolveName(config, kind, name, notFound) {
+	if (kind === "inbox") {
+		const inbox = own$1(config.inboxes, name);
+		if (inbox) return {
+			alias: name,
+			inbox
+		};
+	} else {
+		const account = own$1(config.accounts, name);
+		if (account) return {
+			alias: name,
+			account
+		};
+	}
+	const renamed = formerNameRefusal(config, kind, name);
+	if (renamed) throw renamed;
+	throw notFound?.() ?? defaultNotFound(config, kind, name);
+}
+/** What to say when there are no mailboxes at all: how one is connected, in words (`connectMailboxWords`). */
+function noInboxesHint() {
+	const connect = connectMailboxWords();
+	return connect ? `No inboxes yet: add one with ${connect}, at a terminal or from a chat.` : "No inboxes yet.";
+}
+function defaultNotFound(config, kind, name) {
+	if (kind === "inbox") {
+		const known = Object.keys(config.inboxes);
+		return new CommsError("NOT_FOUND", `no inbox called "${name}"`, { hint: known.length ? `Known inboxes: ${known.join(", ")}.` : noInboxesHint() });
+	}
+	return new CommsError("NOT_FOUND", `no account called "${name}"`);
+}
+function lookupName(config, kind, name) {
+	return kind === "inbox" ? own$1(config.inboxes, name) : own$1(config.accounts, name);
+}
+function findById(config, kind, id) {
+	if (kind === "inbox") {
+		for (const [alias, inbox] of Object.entries(config.inboxes)) if (inbox.id === id) return {
+			alias,
+			inbox
+		};
+	} else for (const [alias, account] of Object.entries(config.accounts)) if (account.id === id) return {
+		alias,
+		account
+	};
+	return null;
+}
+/**
+* The refusal for a former name, or null when `name` is not one.
+*
+* The replacement is looked up by id rather than read from the record, so a chain of renames ends at the name the
+* account has today — and an account removed since its rename is said to be gone, rather than pointing somebody at a
+* name that now belongs to nothing.
+*/
+function formerNameRefusal(config, kind, name) {
+	if (config.version !== 2) return null;
+	const former = own$1(config.formerNames[MAP[kind]], name);
+	if (!former) return null;
+	const current = kind === "inbox" ? findById(config, "inbox", former.id) : findById(config, "account", former.id);
+	if (!current) return new CommsError("NOT_FOUND", `"${name}" was renamed to "${former.name}", which has since been removed`, { details: {
+		formerName: name,
+		id: former.id
+	} });
+	return new CommsError("NOT_FOUND", `"${name}" was renamed to "${current.alias}"`, {
+		hint: `Use "${current.alias}".`,
+		details: {
+			formerName: name,
+			currentName: current.alias,
+			id: former.id
+		}
+	});
+}
+/**
+* Whether `name` may be given to a new or renamed account of this kind and platform.
+*
+* Each version keeps its own rule, because version 1's differ by kind today and must not change under a file an
+* older release also writes: a mailbox name need only be free among mailboxes, a workspace name among both. Version
+* 2 is stricter and the same for both: the grammar, the platform, free in both maps, and never a former name of
+* either kind.
 *
-* `only`, when given, is the most it may remove: the runtimes a person approved removing, from a dry run shown to
-* them. Anything else it would have removed is kept, and says why. Removal is approved as a list of paths, and a
-* runtime that became unused after that list was shown is not on it.
+* A check, not a reservation. Callers repeat it inside the config write, where the schema enforces the same rules
+* again for version 2, because anything can happen between asking and writing.
 */
-async function pruneManagedRuntimes(context, product, options = {}) {
-	const result = {
-		runtimeDir: join(context.core.paths.dataDir, "runtime"),
-		dryRun: options.dryRun === true,
-		removed: [],
-		kept: []
-	};
-	const candidates = [];
-	for (const { path, version } of await listManagedRuntimes(context.core.paths.dataDir, product.packageName)) {
-		const real = await realpath(path).catch(() => path);
-		candidates.push({
-			path,
-			version,
-			aliases: [.../* @__PURE__ */ new Set([path, real])]
-		});
+function nameAvailable(config, kind, name, platform) {
+	const refuse = (error) => ({
+		ok: false,
+		error
+	});
+	if (config.version === 1) {
+		if (RESERVED_ALIASES.has(name)) return refuse(new CommsError("USAGE", `"${name}" is reserved`, { hint: "Choose another name." }));
+		if (!isValidAlias(name)) return refuse(new CommsError("USAGE", `"${name}" is not a usable name`, { hint: "Lower-case letters, digits and dashes, up to 32 characters, not starting with a dash." }));
+		if (kind === "inbox" ? own$1(config.inboxes, name) : own$1(config.inboxes, name) ?? own$1(config.accounts, name)) return refuse(new CommsError("CONFIG", `"${name}" is already connected`, { hint: "Choose another name." }));
+		return { ok: true };
 	}
-	if (candidates.length === 0) return result;
-	const refuse = (why) => {
-		result.refused = why;
-		result.kept = candidates.map(({ path, version }) => ({
-			path,
-			version,
-			reason: "not checked"
+	const problem = nameShapeProblem(name, platform);
+	if (problem) return refuse(new CommsError("USAGE", problem));
+	if (own$1(config.inboxes, name) || own$1(config.accounts, name)) return refuse(new CommsError("CONFIG", `"${name}" is already connected`, { hint: "Choose another name." }));
+	for (const map of ["inboxes", "accounts"]) {
+		const former = own$1(config.formerNames[map], name);
+		if (former) return refuse(new CommsError("CONFIG", `"${name}" was the name of another account and cannot be used again`, {
+			hint: "A former name keeps pointing people at the account that had it. Choose another name.",
+			details: {
+				formerName: name,
+				id: former.id
+			}
 		}));
-		return result;
-	};
-	const processes = await (options.processes ?? runningCommandLines)();
-	if (processes === null) return refuse("the running processes on this machine could not be listed, so none of these can be shown unused");
-	const ledger = handedOutRuntimesPath(context.core.paths.dataDir);
-	const handedOut = await readHandedOut(ledger);
-	if (handedOut === null) return refuse(`${ledger} could not be read, so none of these can be shown never to have been handed out`);
-	const recorded = handedOut.flatMap((record) => record.config ? [{
-		client: record.client,
-		path: record.config
-	}] : []);
-	const scan = await scanRegisteredServers(context.env, process.platform, recorded);
-	if (scan.unreadable.length > 0) return refuse(`${scan.unreadable.map((file) => `${file.path} (${file.reason})`).join("; ")} could not be read, so none of these can be shown unregistered`);
-	const registered = scan.servers;
-	const known = new Set(knownClientConfigs(context.env).map((file) => file.path));
-	const mentions = (aliases, text) => aliases.some((alias) => text === alias || text.includes(`${alias}${sep}`) || text.includes(`${alias}/`));
-	const current = managedRuntimeDir(context.core.paths.dataDir, product.packageName, product.version);
-	for (const { path, version, aliases } of candidates) {
-		const owner = registered.find((server) => [server.command, ...server.args].some((part) => mentions(aliases, part)));
-		const printed = options.includePrinted ? void 0 : handedOut.find((record) => !record.applied && mentions(aliases, record.runtime));
-		const reason = path === current ? "this release" : owner ? `registered with ${owner.client} as "${owner.name}"${known.has(owner.path) ? "" : ` in ${owner.path}`}` : printed ? `printed for ${printed.client} as "${printed.name}" on ${printed.at.slice(0, 10)}, and where that entry went cannot be read; once it is gone, \`mcp prune --include-printed\` removes this` : processes.some((line) => mentions(aliases, line)) ? "a running process uses it" : null;
-		if (reason) {
-			result.kept.push({
-				path,
-				version,
-				reason
-			});
-			continue;
-		}
-		if (options.only !== void 0 && !options.only.includes(path)) {
-			result.kept.push({
-				path,
-				version,
-				reason: "not in the removal that was approved; prune again to include it"
-			});
-			continue;
-		}
-		if (!result.dryRun) await rm(path, { recursive: true });
-		result.removed.push({
-			path,
-			version
-		});
-	}
-	if (options.includePrinted && !result.dryRun && result.removed.length > 0) {
-		const gone = result.removed.map((item) => item.path);
-		const left = handedOut.filter((record) => !gone.some((path) => mentions([path], record.runtime)));
-		if (left.length !== handedOut.length) await writeFileAtomic(ledger, left.map((record) => `${JSON.stringify(record)}\n`).join(""));
-	}
-	return result;
-}
-/** Every runtime the installer handed out, or null when the record is there and cannot be read. */
-async function readHandedOut(path) {
-	let text;
-	try {
-		text = await readFile(path, "utf8");
-	} catch (error) {
-		return error.code === "ENOENT" ? [] : null;
-	}
-	const records = [];
-	for (const line of text.split("\n")) {
-		if (!line.trim()) continue;
-		try {
-			const record = JSON.parse(line);
-			if (typeof record.runtime !== "string") return null;
-			records.push({
-				at: String(record.at ?? ""),
-				client: String(record.client ?? ""),
-				name: String(record.name ?? ""),
-				runtime: record.runtime,
-				...typeof record.config === "string" ? { config: record.config } : {},
-				...record.applied === true ? { applied: true } : {}
-			});
-		} catch {
-			return null;
-		}
 	}
-	return records;
+	return { ok: true };
 }
 /**
 * A pattern for each package a channel's manifest names as a rival (`rivals.packages`).
@@ -5134,22 +6548,31 @@ function escapeRegExp(text) {
 /**
 * The command that removes a registered server, in its client's own terms — the name as the client's file has it,
 * which may be anything, so on Windows it can have no line to paste, and is shown as its words, to be typed
-* (`shellCommand`). Never as a line with the name left out: that removed whatever entry had the stand-in's name.
+* (`quoteCommand`). Never as a line with the name left out: that removed whatever entry had the stand-in's name.
+*
+* The client's own command, so an external one (`externalCommand`). A name that is also one of this suite's commands,
+* or a path into one of its packages, is refused there, since such words are how a suite command would get round the
+* locator; that entry is removed by hand instead, from the file that holds it.
 */
-function removalCommand(client, name, platform) {
-	return commandText(shellCommand([
-		client,
-		"mcp",
-		"remove",
-		name
-	], platform));
+function removalCommand(client, server, platform) {
+	try {
+		return remedy(externalCommand([
+			client,
+			"mcp",
+			"remove",
+			server.name
+		], "the MCP client's own command removes an entry from its own configuration", platform));
+	} catch {
+		return remedy(`remove "${server.name}" from ${server.path} by hand, then restart ${server.client}`);
+	}
 }
-function gmailRemoval({ client, name: server, path, scope }, platform) {
-	if (scope === "project") return `remove "${server}" from the project entry in ${path} by hand`;
+function gmailRemoval(registered, platform) {
+	const { client, name: server, path, scope } = registered;
+	if (scope === "project") return remedy(`remove "${server}" from the project entry in ${path} by hand`);
 	switch (client) {
-		case "claude-code": return removalCommand("claude", server, platform);
-		case "codex": return removalCommand("codex", server, platform);
-		default: return `remove the "${server}" entry from ${path}, then restart ${client}`;
+		case "claude-code": return removalCommand("claude", registered, platform);
+		case "codex": return removalCommand("codex", registered, platform);
+		default: return remedy(`remove the "${server}" entry from ${path}, then restart ${client}`);
 	}
 }
 /**
@@ -5160,7 +6583,7 @@ function findRivalPackageServers(servers, packages, platform = process.platform)
 	const patterns = rivalPatterns(packages);
 	const findings = [];
 	for (const server of servers) {
-		const line = [server.command, ...server.args].join(" ");
+		const line = [server.command, ...withoutPathOptions(server.args).words].join(" ");
 		const known = patterns.find((candidate) => candidate.pattern.test(line));
 		if (!known) continue;
 		findings.push({
@@ -5185,7 +6608,7 @@ function findRivalWordServers(servers, word, product) {
 	return servers.filter((server) => !isProductServer(server, product) && pattern.test([
 		server.name,
 		server.command,
-		...server.args,
+		...withoutPathOptions(server.args).words,
 		server.url ?? ""
 	].join(" ")));
 }
@@ -5351,10 +6774,6 @@ function renderPrune(result, color) {
 	if (lines.length === 0) lines.push(`No managed runtimes to remove in ${result.runtimeDir}.`);
 	return lines.join("\n");
 }
-/** The channel's fixed approval-command prefix with this generated id, rendered by the common shell rule. */
-function changeApprovalCommand(approveCommand, approvalId, platform = process.platform) {
-	return shellCommand([...(approveCommand ?? "agentcomms approve").trim().split(/\s+/), approvalId], platform);
-}
 /**
 * The change policy that governs a change, as `config` stands: the strictest of the policies over everything the change
 * touches.
@@ -5466,7 +6885,7 @@ async function prepareChange(core, request, options) {
 				change: binding
 			}),
 			expiresAt: record.expiresAt,
-			next: nextStep(record.approvalId, policy, options)
+			next: nextStep(record.approvalId, policy, core, options)
 		};
 	} catch (error) {
 		await auditRefusal(core, "change.prepare", error, {
@@ -5498,8 +6917,9 @@ async function claimChange(core, approvalId, expect, options) {
 			change: binding,
 			policy
 		}, {
-			pendingHint: `Ask the user to run ${inlineCommand(changeApprovalCommand(options.approveCommand, approvalId, options.platform))} in their own terminal, then try again with the same approval.`,
-			platform: options.platform
+			pendingHint: handoffSentence(requireHandoffs(core, options.platform).own(["approve", approvalId]), (command) => `Ask the user to run ${command} in their own terminal, then try again with the same approval.`),
+			platform: options.platform,
+			handoffs: core.handoffs
 		});
 		const decided = stricterPolicy(policy, record.requiredPolicy) === "chat" ? "chat" : "confirm";
 		await auditChange(core, {
@@ -5517,7 +6937,11 @@ async function claimChange(core, approvalId, expect, options) {
 			paths: binding.loosened.map((loosening) => loosening.path),
 			changes: binding.loosened
 		};
-	} catch (error) {
+	} catch (caught) {
+		const error = isMisdirectedSend(caught) ? new CommsError(caught.code, caught.message, {
+			hint: sendApprovesHint(await requireHandoffs(core, options.platform).registered(), approvalId),
+			...caught.details === void 0 ? {} : { details: caught.details }
+		}) : caught;
 		await auditRefusal(core, "change.claim", error, {
 			surface: options.surface,
 			approvalId,
@@ -5528,11 +6952,11 @@ async function claimChange(core, approvalId, expect, options) {
 	}
 }
 /** A change approval, checked to be one and to describe the change its digest binds. */
-async function changeRecord(core, approvalId) {
+async function changeRecord(core, approvalId, options = {}) {
 	const record = await core.approvals.get(approvalId);
 	if (!record) throw new CommsError("NOT_FOUND", `no approval ${approvalId}`, { hint: "Prepare the change again; an approval expires ten minutes after it is made." });
 	if (approvalKind(record) === "download") throw new CommsError("USAGE", `${approvalId} is a question about where to save files, not a configuration change`, { hint: DOWNLOAD_ANSWER_HINT });
-	if (approvalKind(record) !== "change") throw new CommsError("USAGE", `approval ${approvalId} is for a send, not a configuration change`, { hint: `Approve it with the command that prepared it: ${channelApproveCommands({ sending: true })}.` });
+	if (approvalKind(record) !== "change") throw new CommsError("USAGE", `approval ${approvalId} is for a send, not a configuration change`, { hint: sendApprovesHint(await requireHandoffs(core, options.platform).registered(), approvalId) });
 	if (!record.change || changeDigest(record.change) !== record.digest) throw new CommsError("BAD_DATA", "this approval does not describe the change it is bound to", {
 		hint: "Nothing was approved. Prepare the change again.",
 		details: { approvalId }
@@ -5547,7 +6971,7 @@ async function changeRecord(core, approvalId) {
 async function beginChangeApproval(core, approvalId, options) {
 	let record;
 	try {
-		record = await changeRecord(core, approvalId);
+		record = await changeRecord(core, approvalId, options);
 		const challenge = await core.approvals.issueChallenge(approvalId, "change", options.platform);
 		return {
 			approvalId,
@@ -5568,7 +6992,7 @@ async function beginChangeApproval(core, approvalId, options) {
 async function finishChangeApproval(core, approvalId, answer, options) {
 	let record;
 	try {
-		record = await changeRecord(core, approvalId);
+		record = await changeRecord(core, approvalId, options);
 		const digest = changeDigest(record.change);
 		const approved = await core.approvals.approve(approvalId, "terminal", {
 			draftMessageId: digest,
@@ -5629,8 +7053,8 @@ async function revokeChange(core, approvalId, reason, options) {
 function changePolicyOf(record) {
 	return record.requiredPolicy === "chat" ? "chat" : "confirm";
 }
-function nextStep(approvalId, policy, options) {
-	return policy === "chat" ? `Show this preview to the user and ask. If they say yes, claim approval ${approvalId} and apply the change; if not, revoke it.` : `The change policy is confirm: ask the user to run ${inlineCommand(changeApprovalCommand(options.approveCommand, approvalId, options.platform))} in their own terminal and type the code it shows. Then claim approval ${approvalId} and apply the change.`;
+function nextStep(approvalId, policy, core, options) {
+	return policy === "chat" ? `Show this preview to the user and ask. If they say yes, claim approval ${approvalId} and apply the change; if not, revoke it.` : handoffSentence(requireHandoffs(core, options.platform).own(["approve", approvalId]), (command) => `The change policy is confirm: ask the user to run ${command} in their own terminal and type the code it shows. Then claim approval ${approvalId} and apply the change.`);
 }
 /**
 * One line per step of a change approval: who asked, from which surface, under which policy, and how it ended.
@@ -5790,13 +7214,11 @@ async function gatedChange(core, change, options) {
 		status: "approval-required",
 		prepared: await prepareChange(core, request, {
 			surface: options.surface,
-			approveCommand: options.approveCommand,
 			platform: options.platform
 		})
 	};
 	const consent = await claimChange(core, options.approvalId, request, {
 		surface: options.surface,
-		approveCommand: options.approveCommand,
 		platform: options.platform
 	});
 	return {
@@ -5814,11 +7236,9 @@ async function gatedChange(core, change, options) {
 */
 async function gatedChangeAtTerminal(core, change, options) {
 	const streams = options.streams ?? defaultStreams;
-	const { approveCommand } = options;
 	const first = await gatedChange(core, change, {
 		surface: "cli",
 		approvalId: options.approvalId,
-		approveCommand,
 		platform: options.output.platform
 	});
 	if (first.status === "applied") return first.result;
@@ -5826,9 +7246,9 @@ async function gatedChangeAtTerminal(core, change, options) {
 	if (!(agentMarker(options.env) === null && canPrompt(options.env, streams, { json: options.output.json === true }))) {
 		if (options.output.json !== true) streams.stdout.write(`${prepared.preview}\n\n`);
 		const carrying = [options.approvalFlag ?? "--approval", prepared.approvalId];
-		const { command } = options;
+		const handoffs = requireHandoffs(core, options.output.platform);
 		throw new CommsError("APPROVAL_PENDING", `this change needs approval first: ${prepared.summary}`, {
-			hint: options.pendingHint?.(prepared) ?? approvalHint(prepared, typeof command === "string" ? `${command} ${carrying.join(" ")}` : withWords(command, ...carrying), approveCommand, options.output.platform),
+			hint: options.pendingHint?.(prepared) ?? approvalHint(prepared, handoffs[options.rerunOn ?? "own"](insertWordsBeforeSentinel(options.rerun, ...carrying)), handoffs),
 			details: {
 				approvalId: prepared.approvalId,
 				policy: prepared.policy,
@@ -5849,7 +7269,6 @@ async function gatedChangeAtTerminal(core, change, options) {
 	const second = await gatedChange(core, change, {
 		surface: "cli",
 		approvalId: prepared.approvalId,
-		approveCommand,
 		platform: options.output.platform
 	});
 	if (second.status !== "applied") throw new CommsError("UNEXPECTED", "the approved change asked for approval again");
@@ -5862,9 +7281,13 @@ async function gatedChangeAtTerminal(core, change, options) {
 * Shared with a command that reports a waiting change rather than failing on it — `agent-gmail setup`, which stops at
 * its registration step and says why in its report — so the two say it in the same words.
 */
-function approvalHint(prepared, rerun, approveCommand, platform = typeof rerun === "string" ? process.platform : rerun.platform) {
-	const run = typeof rerun === "string" ? `\`${rerun}\`` : inlineCommand(rerun);
-	return prepared.policy === "confirm" ? `Show the person the preview. They run ${inlineCommand(changeApprovalCommand(approveCommand, prepared.approvalId, platform))}; then run ${run}.` : `Show the person the preview. Once they say yes, run ${run}.`;
+function approvalHint(prepared, rerun, maker) {
+	const run = isCommand(rerun) ? inlineCommand(rerun) : null;
+	const rerunSaid = isCommand(rerun) ? "" : rerun.message;
+	if (prepared.policy !== "confirm") return run === null ? `Show the person the preview. ${rerunSaid}` : `Show the person the preview. Once they say yes, run ${run}.`;
+	const approve = maker.own(["approve", prepared.approvalId]);
+	if (isCommand(approve) && run !== null) return `Show the person the preview. They run ${inlineCommand(approve)}; then run ${run}.`;
+	return `Show the person the preview. ${handoffSentence(approve, (command) => `They run ${command}.`)} ${run === null ? rerunSaid : `Then run ${run}.`}`;
 }
 /**
 * Approves a configuration change at a terminal, the way a person approves a send: read the preview, type the code.
@@ -5884,11 +7307,7 @@ async function approveChangeAtTerminal(core, approvalId, env, output, streams =
 		refuseUnlessPerson(env, streams, {
 			refusedToAgent: "only a person can approve a change, not an agent",
 			refusedWithoutTerminal: "approving a change needs an interactive terminal",
-			command: commandText(shellCommand([
-				"agentcomms",
-				"approve",
-				approvalId
-			], output.platform)),
+			command: requireHandoffs(core, output.platform).own(["approve", approvalId]),
 			color: output.color,
 			json: output.json
 		});
@@ -6074,11 +7493,17 @@ const KEYCHAIN_SERVICE = "agent-communications";
 * answer an OS prompt, so it must not hang.
 */
 const KEYCHAIN_TIMEOUT_MS = 12e3;
+/** "Run the doctor": core's, located from whatever is printing, or why there is none here. */
+function doctorSentence(handoffs, say) {
+	return handoffSentence(requiredHandoffs(handoffs).core(["doctor"]), say, { instead: "Call comms_doctor from a chat." });
+}
 var FileSecretStore = class {
 	kind = "file";
 	directory;
-	constructor(directory) {
+	#handoffs;
+	constructor(directory, options = {}) {
 		this.directory = directory;
+		this.#handoffs = options.handoffs;
 	}
 	#path(ref) {
 		return join(this.directory, `${createHash("sha256").update(ref).digest("hex").slice(0, 32)}.json`);
@@ -6098,7 +7523,7 @@ var FileSecretStore = class {
 		} catch (error) {
 			if (error.code === "ENOENT") return null;
 			throw new CommsError("SECRET_STORE_UNAVAILABLE", "a stored secret file could not be read", {
-				hint: "Run `agentcomms doctor`; re-authorise the inbox if the file is damaged.",
+				hint: `${doctorSentence(this.#handoffs, (command) => `Run ${command}.`)} Re-authorise the inbox if the file is damaged.`,
 				cause: error
 			});
 		}
@@ -6133,10 +7558,10 @@ async function loadKeyringModule() {
 var KeychainTimeout = class extends Error {
 	name = "KeychainTimeout";
 };
-function keychainError(action, cause, timeoutMs) {
+function keychainError(action, cause, timeoutMs, handoffs) {
 	const timedOut = cause instanceof KeychainTimeout;
 	return new CommsError(timedOut ? "KEYCHAIN_APPROVAL_PENDING" : "SECRET_STORE_UNAVAILABLE", timedOut ? `the system keychain did not answer within ${Math.round(timeoutMs / 1e3)}s while trying to ${action}` : `the system keychain refused to ${action} (it may be locked, or access was denied)`, {
-		hint: timedOut ? "Look for a system dialog asking to allow access to the keychain, then retry. Run `agentcomms doctor` for details." : "Unlock the keychain and retry, or run `agentcomms doctor`. On macOS a Node upgrade can require allowing access again.",
+		hint: timedOut ? `Look for a system dialog asking to allow access to the keychain, then retry. ${doctorSentence(handoffs, (command) => `Run ${command} for details.`)}` : `Unlock the keychain and retry. ${doctorSentence(handoffs, (command) => `Run ${command} for details.`)} On macOS a Node upgrade can require allowing access again.`,
 		details: { reason: timedOut ? "KEYCHAIN_APPROVAL_PENDING" : "KEYCHAIN_UNAVAILABLE" },
 		cause
 	});
@@ -6161,6 +7586,7 @@ var KeychainSecretStore = class {
 	#module;
 	#timeoutMs;
 	#namespace;
+	#handoffs;
 	/** One keychain call at a time: parallel calls would each raise their own OS prompt and exhaust the thread pool. */
 	#queue = Promise.resolve();
 	/**
@@ -6174,17 +7600,18 @@ var KeychainSecretStore = class {
 	* @param namespace keeps entries of different config directories apart (a test run or a second setup must never
 	*   read or overwrite another's `client:default:secret`); see {@link keychainNamespace}.
 	*/
-	constructor(module, namespace, timeoutMs = KEYCHAIN_TIMEOUT_MS) {
+	constructor(module, namespace, timeoutMs = KEYCHAIN_TIMEOUT_MS, options = {}) {
 		this.#module = module;
 		this.#namespace = namespace;
 		this.#timeoutMs = timeoutMs;
+		this.#handoffs = options.handoffs;
 	}
 	#entry(ref) {
 		return new this.#module.AsyncEntry(KEYCHAIN_SERVICE, `${this.#namespace}:${ref}`, { linux: { store: "secret-service" } });
 	}
 	#serial(action, fn) {
 		const run = this.#queue.then(async () => {
-			if (this.#stuck) throw keychainError(action, new KeychainTimeout(), this.#timeoutMs);
+			if (this.#stuck) throw keychainError(action, new KeychainTimeout(), this.#timeoutMs, this.#handoffs);
 			const native = fn();
 			try {
 				return await raceTimeout(native, this.#timeoutMs);
@@ -6196,7 +7623,7 @@ var KeychainSecretStore = class {
 						if (this.#stuck === stuck) this.#stuck = null;
 					});
 				}
-				throw keychainError(action, error, this.#timeoutMs);
+				throw keychainError(action, error, this.#timeoutMs, this.#handoffs);
 			}
 		});
 		this.#queue = run.catch(() => void 0);
@@ -6236,10 +7663,11 @@ function keychainNamespace(configDir) {
 }
 /** Opens the backend recorded in config for an inbox or client. */
 async function openSecretStore(kind, options) {
-	if (kind === "file") return new FileSecretStore(options.secretsDir);
+	const told = { handoffs: options.handoffs };
+	if (kind === "file") return new FileSecretStore(options.secretsDir, told);
 	const keyring = options.keyring === void 0 ? await loadKeyringModule() : options.keyring;
 	if (!keyring) throw new CommsError("SECRET_STORE_UNAVAILABLE", "secrets are kept in the system keychain, but the keychain module is missing", { hint: "Reinstall with optional dependencies, or re-add the inbox with --store file." });
-	return new KeychainSecretStore(keyring, options.namespace);
+	return new KeychainSecretStore(keyring, options.namespace, KEYCHAIN_TIMEOUT_MS, told);
 }
 var InboxStateStore = class {
 	directory;
@@ -6273,25 +7701,37 @@ var InboxStateStore = class {
 	}
 };
 function openCore(options = {}) {
-	const paths = resolvePaths(options);
+	const { paths, pathOverrides } = resolvePathIdentity(options);
 	const now = options.now ?? (() => /* @__PURE__ */ new Date());
-	const config = new ConfigStore(paths.configDir);
+	const handoffs = options.caller === void 0 ? void 0 : cliHandoffs({
+		caller: options.caller,
+		paths,
+		platform: options.platform,
+		env: options.env
+	});
+	const config = new ConfigStore(paths.configDir, { handoffs });
 	let cached = null;
 	return {
 		paths,
+		pathOverrides,
 		config,
 		states: new InboxStateStore(paths.stateDir),
-		approvals: new ApprovalStore(paths.stateDir, { now }),
+		approvals: new ApprovalStore(paths.stateDir, {
+			now,
+			handoffs
+		}),
 		ledger: new SendLedger(paths.stateDir, now),
 		plans: new PlanStore(paths.stateDir, now),
 		taint: new TaintStore(paths.stateDir, now),
 		audit: new AuditLog(paths.stateDir, now),
+		handoffs,
 		async secrets(kind) {
 			const chosen = kind ?? secretsStoreOf(await config.load());
 			if (cached?.kind === chosen) return cached.store;
 			const store = await openSecretStore(chosen, {
 				secretsDir: paths.secretsDir,
-				namespace: keychainNamespace(paths.configDir)
+				namespace: keychainNamespace(paths.configDir),
+				handoffs
 			});
 			cached = {
 				kind: chosen,
@@ -6491,81 +7931,6 @@ strictObject({
 	sha256: string().regex(/^[0-9a-f]{64}$/, "a SHA-256 is 64 lowercase hex digits")
 });
 /**
-* Versions as semver writes and orders them — what an update compares, and what the daily update check's reader needs
-* to decide whether the release it last heard of is newer than the one running.
-*
-* Here rather than in `npm.ts`, which also talks to the registry: the reader of `update-check.json` is imported by
-* every server, WhatsApp's included, and must carry no network code at all (design 2026-09-28 §1). `npm.ts` re-exports
-* all of it, so nothing that imported these from there changes.
-*/
-/**
-* A version, exactly as semver writes one: `1.2.3`, `1.2.3-rc.1`, `1.2.3+build`.
-*
-* Anything the registry answers is checked against this before it is used, because a version goes into a directory
-* name (`runtime/<version>-gmail`), a sentence a person approves, and an argument to `npm install`. A registry — or a
-* mirror somebody configured — that answered `../x` or `1.0.0 && …` would otherwise put that in all three.
-*/
-const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
-function isVersion(value) {
-	return typeof value === "string" && VERSION_PATTERN.test(value);
-}
-/** Two numeric strings with no leading zeros, compared as numbers of any size. */
-function compareNumeric(a, b) {
-	if (a.length !== b.length) return a.length < b.length ? -1 : 1;
-	return a < b ? -1 : a > b ? 1 : 0;
-}
-/**
-* Semver precedence: -1, 0 or 1, or null when either is not a version.
-*
-* Numbers compare as numbers (`0.10.0` is after `0.9.9`), a prerelease comes before its release, and build metadata
-* counts for nothing. Written out rather than taken from a dependency: it is twenty lines, and the core installs as
-* few packages as it can.
-*/
-function compareVersions(a, b) {
-	const left = VERSION_PATTERN.exec(a);
-	const right = VERSION_PATTERN.exec(b);
-	if (!left || !right) return null;
-	for (const index of [
-		1,
-		2,
-		3
-	]) {
-		const order = compareNumeric(left[index] ?? "0", right[index] ?? "0");
-		if (order !== 0) return order < 0 ? -1 : 1;
-	}
-	const pre = (match) => match[4] === void 0 ? [] : match[4].split(".");
-	const [ours, theirs] = [pre(left), pre(right)];
-	if (ours.length === 0 || theirs.length === 0) return ours.length === theirs.length ? 0 : ours.length === 0 ? 1 : -1;
-	for (let index = 0; index < Math.max(ours.length, theirs.length); index += 1) {
-		const x = ours[index];
-		const y = theirs[index];
-		if (x === void 0) return -1;
-		if (y === void 0) return 1;
-		const [numericX, numericY] = [/^\d+$/.test(x), /^\d+$/.test(y)];
-		if (numericX && numericY) {
-			const order = compareNumeric(x, y);
-			if (order !== 0) return order < 0 ? -1 : 1;
-		} else if (numericX !== numericY) return numericX ? -1 : 1;
-		else if (x !== y) return x < y ? -1 : 1;
-	}
-	return 0;
-}
-/** Whether `version` is older than `latest`: by semver when both are versions, and otherwise whenever they differ. */
-function isBehind(version, latest) {
-	if (version === latest) return false;
-	const order = compareVersions(version, latest);
-	return order === null ? true : order < 0;
-}
-/**
-* Whether a version is a prerelease — `0.8.0-rc.1` — which the daily update check never counts as an update: a
-* machine is not told to "update" to a release candidate, nor a candidate told to go back to the last release.
-*/
-function isPrerelease(version) {
-	return VERSION_PATTERN.exec(version)?.[4] !== void 0;
-}
-/** The package version, read from package.json at build time. */
-const VERSION = "0.13.0";
-/**
 * Registering, pruning and listing the MCP servers of every channel, from the core.
 *
 * `agentcomms mcp install` registers the core server; `comms_server_install` registers any channel's; and
@@ -6765,7 +8130,9 @@ function serverInstallChange(core, env, request, own) {
 			checkPin(config, request);
 			const product = await productNow();
 			const { version } = product;
-			const preflight = await preflightInstall(context, product, installOptions(request));
+			const preflight = await preflightInstall(context, product, installOptions(request)).catch(async (error) => {
+				throw await remedyLocated(error, core);
+			});
 			const { target, previous, effective, kept, command } = preflight;
 			planned = {
 				product,
@@ -6796,7 +8163,9 @@ function serverInstallChange(core, env, request, own) {
 		},
 		apply: async () => {
 			if (planned === void 0) throw new CommsError("UNEXPECTED", "the registration was applied before it was planned");
-			const result = await mcpInstall(context, planned.product, installOptions(request), planned.install);
+			const result = await mcpInstall(context, planned.product, installOptions(request), planned.install).catch(async (error) => {
+				throw await remedyLocated(error, core);
+			});
 			return {
 				...result,
 				restart: result.applied ? `Restart ${request.client} to load "${result.name}": no MCP client loads a new server into a session that is already running.` : null
@@ -6805,6 +8174,23 @@ function serverInstallChange(core, env, request, own) {
 	};
 }
 /**
+* A refusal of `mcp install` with its remedy — another install of the same product — said with the command located:
+* the printing package's own, core's, or another product's found among this machine's registrations (CUE-403). The
+* installer says only the words; it may not import the locator.
+*/
+async function remedyLocated(error, core) {
+	const remedy = installRemedyOf(error);
+	if (remedy === void 0 || !(error instanceof CommsError)) return error;
+	const channel = CHANNELS.find((each) => channelServer(each).binary === remedy.binary);
+	if (channel === void 0) return error;
+	const maker = await requireHandoffs(core).registered();
+	return new CommsError(error.code, error.message, {
+		hint: handoffSentence(maker.of(channel, remedy.words), remedy.say),
+		...error.details === void 0 ? {} : { details: error.details },
+		...error.cause === void 0 ? {} : { cause: error.cause }
+	});
+}
+/**
 * Removing a channel's unused managed runtimes, as a change.
 *
 * A dry run is free: it removes nothing. Otherwise the plan is that same dry run, and each runtime it would remove is
@@ -6822,7 +8208,7 @@ function serverPruneChange(core, env, request, own) {
 	};
 	const { packageName, version } = ownProduct(request.channel, own) ?? {
 		packageName: channelServer(request.channel).packageName,
-		version: "0.13.0"
+		version: "0.13.1"
 	};
 	const product = {
 		packageName,
@@ -7057,40 +8443,52 @@ async function pendingUpdate(options) {
 	};
 	return verdict;
 }
-/**
-* The two ways on, as a tool call and as a command — and the command through npx, for a machine with no `agentcomms`
-* installed: one that runs only a plugin's server, say, has neither the core server nor the command.
-*/
-const UPDATE_WAYS = Object.freeze({
-	update: {
-		tool: "comms_update",
-		command: "agentcomms update",
-		npx: "npx -y @agentcomms/core@latest update"
-	},
-	later: {
-		tool: "comms_update",
-		arguments: { later: true },
-		command: "agentcomms update --later",
-		npx: "npx -y @agentcomms/core@latest update --later"
-	}
-});
+function updateCommands(core, platform) {
+	const handoffs = requireHandoffs(core, platform);
+	return {
+		update: handoffs.core(["update"]),
+		later: handoffs.core(["update", "--later"])
+	};
+}
+/** One of them in a sentence `say` makes: in backticks, or, with no command here, the sentence saying why. */
+function updateCommandSaid(commands, which, say) {
+	return handoffSentence(commands[which], say);
+}
+function updateWaysOf(commands) {
+	return {
+		update: {
+			tool: "comms_update",
+			command: commands.update
+		},
+		later: {
+			tool: "comms_update",
+			arguments: { later: true },
+			command: commands.later
+		}
+	};
+}
+/** A channel's product name, from core's snapshot of the manifests: `Gmail`. */
+function labelOf(channel) {
+	return CHANNEL_SNAPSHOT.find((entry) => entry.manifest.channel === channel)?.manifest.label ?? channel;
+}
 /**
 * What a stopped tool call says, in words an agent passes on: the owner's sentence first, then the versions, then the
 * two ways on — the update, from chat or a terminal, or "not now", which the person approves like any other change.
 */
-function updateStopMessage(pending, where) {
+function updateStopMessage(pending, where, commands) {
+	const server = where.channel === "core" ? "the core server" : `the ${labelOf(where.channel)} server`;
 	const didNotRun = `Nothing was done: ${where.tool} did not run.`;
-	const later = `Not now: call comms_update with \`later: true\` — a change the person approves — and nothing stops again until midnight; the next request after it asks again. At a terminal: \`${UPDATE_WAYS.later.command}\` (\`${UPDATE_WAYS.later.npx}\` where agentcomms is not installed).`;
+	const later = `Not now: call comms_update with \`later: true\` — a change the person approves — and nothing stops again until midnight; the next request after it asks again. ${updateCommandSaid(commands, "later", (command) => `At a terminal: ${command}.`)}`;
 	if (pending.kind === "restart") return [
 		"Hang on a minute, the update is installed, but this server isn't running it yet. Restart the client first.",
-		`This is ${where.server} ${pending.running}; ${pending.latest} is installed on this machine — every registration of this server names it — and a client starts it only once it is restarted. ${didNotRun}`,
+		`This is ${server}, ${pending.running}; ${pending.latest} is installed on this machine — every registration of this server names it — and a client starts it only once it is restarted. ${didNotRun}`,
 		`Ask the person to restart the MCP client — quit it and open it again — and carry on after. ${later}`
 	].join("\n");
 	return [
 		UPDATE_FIRST,
-		`This is ${where.server} ${pending.running}; the latest release is ${pending.latest}. ${didNotRun}`,
+		`This is ${server}, ${pending.running}; the latest release is ${pending.latest}. ${didNotRun}`,
 		"Ask the person which they want:",
-		`- Update now: call comms_update on the agentcomms (core) server. It shows every step and asks before it changes anything; restart the client after. At a terminal: \`${UPDATE_WAYS.update.command}\` (\`${UPDATE_WAYS.update.npx}\` where agentcomms is not installed). A server comms_update does not find registered here — a plugin's, an extension's — is updated where it was installed.`,
+		`- Update now: call comms_update on the core server. It shows every step and asks before it changes anything; restart the client after. ${updateCommandSaid(commands, "update", (command) => `At a terminal: ${command}.`)} A server comms_update does not find registered here — a plugin's, an extension's — is updated where it was installed.`,
 		`- ${later}`
 	].join("\n");
 }
@@ -7117,7 +8515,6 @@ const CHANNEL_PACKAGES = Object.freeze(CHANNELS.map((channel) => channelServer(c
 const SERVER_PACKAGES = Object.freeze(CHANNELS.map((channel) => channelServer(channel).npxPackage).filter((name) => !CHANNEL_PACKAGES.includes(name)));
 Object.freeze([.../* @__PURE__ */ new Set([...CHANNEL_PACKAGES, ...SERVER_PACKAGES])].sort());
 channelServer("core").packageName;
-listed(CHANNELS.map((channel) => `\`${channelServer(channel).binary} mcp prune\``), "and");
 /**
 * "Not now": no server or command on this machine stops for the update until the next local midnight.
 *
@@ -7225,8 +8622,9 @@ function updateToolGate(options) {
 		if (await claimsApproval(options.core, args[claim?.argument ?? "approvalId"], claim)) return null;
 		return stoppedCall(pending, {
 			server: options.server,
+			channel: options.channel,
 			tool
-		});
+		}, updateCommands(options.core));
 	};
 }
 /**
@@ -7234,15 +8632,17 @@ function updateToolGate(options) {
 * a client that shows the model only text blocks (Cursor) reads it there. Claude Code and Codex show only
 * `structuredContent`, so the same words are its `message`, with the versions and the two ways on beside them.
 */
-function stoppedCall(pending, where) {
-	const message = updateStopMessage(pending, where);
+function stoppedCall(pending, where, commands) {
+	const message = updateStopMessage(pending, where, commands);
+	const ways = updateWaysOf(commands);
+	const leaving = (value) => JSON.parse(JSON.stringify(value));
 	return {
 		isError: true,
 		content: [{
 			type: "text",
 			text: message
 		}],
-		structuredContent: { error: {
+		structuredContent: leaving({ error: {
 			code: "UPDATE_REQUIRED",
 			message,
 			hint: pending.kind === "restart" ? "Restart the MCP client, or put the stop off until midnight with comms_update `later: true` once the person agrees." : "Update with comms_update (the person approves its preview), or put it off until midnight with comms_update `later: true` once the person agrees.",
@@ -7252,10 +8652,10 @@ function stoppedCall(pending, where) {
 				running: pending.running,
 				latest: pending.latest,
 				installed: pending.kind === "restart",
-				update: UPDATE_WAYS.update,
-				later: UPDATE_WAYS.later
+				update: ways.update,
+				later: ways.later
 			}
-		} }
+		} })
 	};
 }
 /** The commands never stopped, by their first word; `mcp` alone runs a server, which stops each call itself. */
@@ -7350,19 +8750,21 @@ async function updateGateAtTerminal(options) {
 		...where
 	});
 	if (pending === null) return null;
-	if (!(agentMarker(env) === null && canPrompt(env, streams, {
+	const person = agentMarker(env) === null && canPrompt(env, streams, {
 		json: output.json,
 		noInput: options.noInput === true
-	}))) throw updateRequired(pending, options.binary);
+	});
+	const commands = updateCommands(core, output.platform);
+	if (!person) throw updateRequired(pending, cliOf(options.channel), commands);
 	const bold = (word) => paint(output.color, "bold", word);
 	const answer = (await askLine(streams, pending.kind === "restart" ? `${pending.latest} is installed (this is ${pending.running}). Switch ${bold("now")}, ${bold("later")} today, or ${bold("cancel")}? ` : `${pending.latest} is out (you have ${pending.running}). Update ${bold("now")}, ${bold("later")} today, or ${bold("cancel")}? `)).trim().toLowerCase();
 	if (answer === "now" || answer === "update") {
 		if (pending.kind === "restart") {
-			streams.stdout.write(`${pending.latest} is installed globally; this ${options.binary} is ${pending.running}, started from somewhere else — npx's cache, a project's own install, a checkout. Run your command again from the installed one. ${options.binary} did not run.\n`);
+			streams.stdout.write(`${pending.latest} is installed globally; this ${cliOf(options.channel)} is ${pending.running}, started from somewhere else — npx's cache, a project's own install, a checkout. Run your command again from the installed one. The command did not run.\n`);
 			return EXIT_CODES.UPDATE;
 		}
 		if (!options.update) {
-			streams.stdout.write(`${options.binary} reads only this machine and cannot fetch the update itself. Run \`${UPDATE_WAYS.update.command}\` (\`${UPDATE_WAYS.update.npx}\` where agentcomms is not installed), then run your command again.\n`);
+			streams.stdout.write(`This ${cliOf(options.channel)} reads only this machine and cannot fetch the update itself. ${updateCommandSaid(commands, "update", (command) => `Run ${command}, then run your command again.`)}\n`);
 			return EXIT_CODES.UPDATE;
 		}
 		return afterUpdate(await options.update(), options, pending);
@@ -7371,39 +8773,50 @@ async function updateGateAtTerminal(options) {
 		const result = await gatedChangeAtTerminal(core, updateLaterChange(core, { now }), {
 			env,
 			output,
-			command: UPDATE_WAYS.later.command,
-			approveCommand: options.approveCommand,
+			rerun: ["update", "--later"],
+			rerunOn: "core",
 			answered: true,
 			streams
 		});
 		streams.stderr.write(`Put off until midnight${result.latest ? `: ${result.latest} will be asked about again tomorrow` : ""}.\n`);
 		return null;
 	}
-	throw new CommsError("USAGE", `cancelled: ${options.binary} did not run, and nothing was changed`, { hint: `Update with \`${UPDATE_WAYS.update.command}\`, or put it off until tomorrow with \`${UPDATE_WAYS.later.command}\`.` });
+	throw new CommsError("USAGE", "cancelled: the command did not run, and nothing was changed", { hint: bothSaid(commands, (update, later) => `Update with ${update}, or put it off until tomorrow with ${later}.`) });
+}
+/**
+* The CLI a gate stops, in product words — "Gmail CLI", "core CLI" — for its sentences: never its binary, which is no
+* command most people can run, and which a sentence would read as one (CUE-403).
+*/
+function cliOf(channel) {
+	if (channel === "core") return "core CLI";
+	return `${CHANNEL_SNAPSHOT.find((entry) => entry.manifest.channel === channel)?.manifest.label ?? channel} CLI`;
 }
 /**
 * The stop where nobody can be asked: the command does not run. "Update" names the update and "not now"; "restart"
 * — the update installed, and an older copy running — says to run the command from the installed one.
 */
-function updateRequired(pending, binary) {
-	const later = `\`${UPDATE_WAYS.later.command}\` to put it off until tomorrow`;
-	const npx = `Where agentcomms is not installed: \`${UPDATE_WAYS.update.npx}\`, and \`${UPDATE_WAYS.later.npx}\`.`;
+function updateRequired(pending, cli, commands) {
+	const ways = updateWaysOf(commands);
 	const details = {
 		running: pending.running,
 		latest: pending.latest,
 		installed: pending.kind === "restart",
-		update: UPDATE_WAYS.update,
-		later: UPDATE_WAYS.later
+		update: ways.update,
+		later: ways.later
 	};
-	if (pending.kind === "restart") return new CommsError("UPDATE_REQUIRED", `Hang on a minute, the update is installed, but this command isn't running it yet. ${pending.latest} is installed globally, and this ${binary} is ${pending.running}: run the command again from the installed one, or ${later}`, {
-		hint: `Nothing was done. An older copy is running — npx's cache, a project's own install, a checkout. "Not now" is a change a person approves: an agent gets the preview and an approval id (exit 10), and runs the same command again with --approval <id> once the person agrees. ${npx}`,
+	if (pending.kind === "restart") return new CommsError("UPDATE_REQUIRED", `Hang on a minute, the update is installed, but this command isn't running it yet. ${pending.latest} is installed globally, and this ${cli} is ${pending.running}: ${handoffSentence(commands.later, (later) => `run the command again from the installed one, or ${later} to put it off until tomorrow`)}`, {
+		hint: `Nothing was done. An older copy is running — npx's cache, a project's own install, a checkout. "Not now" is a change a person approves: an agent gets the preview and an approval id (exit 10), and runs the same command again with --approval <id> once the person agrees.`,
 		details
 	});
-	return new CommsError("UPDATE_REQUIRED", `${UPDATE_FIRST} ${pending.latest} is out (you have ${pending.running}): run \`${UPDATE_WAYS.update.command}\` first, or ${later}`, {
-		hint: `Nothing was done. Both are changes a person approves: an agent gets the preview and an approval id (exit 10), and runs the same command again with --approval <id> once the person agrees. ${npx}`,
+	return new CommsError("UPDATE_REQUIRED", `${UPDATE_FIRST} ${pending.latest} is out (you have ${pending.running}): ${bothSaid(commands, (update, later) => `run ${update} first, or ${later} to put it off until tomorrow`)}`, {
+		hint: `Nothing was done. Both are changes a person approves: an agent gets the preview and an approval id (exit 10), and runs the same command again with --approval <id> once the person agrees.`,
 		details
 	});
 }
+/** The update and "not now" in one sentence; with no command here — the same core gives both or neither — why not. */
+function bothSaid(commands, say) {
+	return handoffSentence(commands.update, (update) => handoffSentence(commands.later, (later) => say(update, later)));
+}
 /**
 * What the terminal says after the person's "now", and the exit status. "Updated. Run your command again." only when
 * the update did everything and this command's release is now installed where it runs from — its global package at
@@ -7411,8 +8824,10 @@ function updateRequired(pending, binary) {
 * script that goes on after `cmd && next` must not take it for the command's success.
 */
 async function afterUpdate(outcome, options, before) {
-	const { streams, binary } = options;
-	const notRun = `${binary} did not run`;
+	const { streams } = options;
+	const cli = cliOf(options.channel);
+	const notRun = "The command did not run";
+	const commands = updateCommands(options.core, options.output.platform);
 	if (outcome === "failed") {
 		streams.stdout.write(`${notRun}: the update did not finish — each step says how it went, above.\n`);
 		return EXIT_CODES.UNAVAILABLE;
@@ -7426,10 +8841,10 @@ async function afterUpdate(outcome, options, before) {
 			streams.stdout.write("Updated. Run your command again.\n");
 			return EXIT_CODES.OK;
 		}
-		streams.stdout.write(`${before.latest} is installed here: run your command again from it. ${notRun}.\n`);
+		streams.stdout.write(`${before.latest} is installed here: run your command again from it. It did not run.\n`);
 		return EXIT_CODES.UPDATE;
 	}
-	streams.stdout.write(`${notRun}: the update did not bring it to ${before.latest}. \`${UPDATE_WAYS.update.command}\` updates what this machine registers and has installed globally — what it found is said above — and this ${binary} ${before.running} is started from somewhere else: npx's cache, a project's own install, a checkout. Run it from ${before.latest}, or put this off until tomorrow with \`${UPDATE_WAYS.later.command}\`.\n`);
+	streams.stdout.write(`${notRun}: the update did not bring it to ${before.latest}. The update moves what this machine registers and has installed globally — what it found is said above — and this ${cli}, ${before.running}, is started from somewhere else: npx's cache, a project's own install, a checkout. ${handoffSentence(commands.later, (later) => `Run it from ${before.latest}, or put this off until tomorrow with ${later}.`)}\n`);
 	return EXIT_CODES.UPDATE;
 }
 async function askLine(streams, question) {
@@ -7446,7 +8861,7 @@ async function askLine(streams, question) {
 }
 channelServer("core").packageName;
 //#endregion
-//#region ../core/dist/tool-arguments-JmEBiWPl.mjs
+//#region ../core/dist/tool-arguments-BcYu_EPp.mjs
 const APPLIED = Symbol.for("agentcomms.strictToolArguments");
 const TARGET = "draft-2020-12";
 /**
@@ -8450,7 +9865,7 @@ strictObject({
 		}))) !== JSON.stringify(narrowing)) issue(["narrowing"], kept ? `${kept.label}'s server is pinned by ${narrowingWords(narrowing)}, as its entries have always been written` : `\`inbox\`, \`--read-only\` and \`workspace\` are Gmail's and Slack's; a channel after them is pinned by ${narrowingWords(narrowing)} and nothing else`);
 	}
 	if (isCore) {
-		if (manifest.binary !== CORE_BINARY) issue(["binary"], `the core's command is \`${CORE_BINARY}\``);
+		if (manifest.binary !== CORE_BINARY) issue(["binary"], "is not the core's own command name");
 	} else if (!CHANNEL_BINARY.test(manifest.binary)) issue(["binary"], "a channel's command is `agent-<something>`");
 	(manifest.server.bins ?? []).forEach((bin, index) => {
 		if (!CHANNEL_BINARY.test(bin)) issue([
@@ -8474,7 +9889,7 @@ strictObject({
 		if (rivals.word === void 0 && rivals.packages === void 0) issue(["rivals"], "a word or packages");
 		if (rivals.word === void 0 !== (rivals.can === void 0)) issue(["rivals"], "`word` and `can` come together: what a server matching the word can do unapproved");
 	}
-	if (manifest.approve !== void 0 && !manifest.approve.startsWith(`${manifest.binary} `)) issue(["approve"], `the channel's own command: \`${manifest.binary} …\``);
+	if (manifest.approve !== void 0 && !manifest.approve.startsWith(`${manifest.binary} `)) issue(["approve"], "must start with the channel's own command, its `binary`, and a space");
 	if (manifest.skills) {
 		const family = manifest.skills.prefix.slice(0, -1);
 		if (manifest.skills.contract !== `skills/_shared/contract-${family}.md`) issue(["skills", "contract"], `skills/_shared/contract-${family}.md: a skill's contract is chosen by its prefix`);
@@ -8765,20 +10180,25 @@ function newWhatsAppAccount(options) {
 * The configuration has names this channel can use.
 *
 * WhatsApp accounts are `organisation/whatsapp`, which only version 2 of the configuration names. A version-1 file is
-* one an older release on this machine may still share; `agentcomms names migrate` moves it on, and until then this
-* channel adds and reads nothing rather than invent a flat name for a platform that never had one.
+* one an older release on this machine may still share; core's `names migrate` moves it on, and until then this
+* channel adds and reads nothing rather than invent a flat name for a platform that never had one. The refusal names
+* core's command as `handoffs` find it: the core this package installs.
 */
-function requireNamedConfig(config) {
-	if (config.version !== 2) throw new CommsError("CONFIG", "WhatsApp accounts need the organisation/platform names, and this configuration still has the old flat ones", { hint: "Run `agentcomms names migrate --dry-run` to see what everything would be called, then `agentcomms names migrate`." });
+function requireNamedConfig(config, handoffs) {
+	if (config.version !== 2) throw new CommsError("CONFIG", "WhatsApp accounts need the organisation/platform names, and this configuration still has the old flat ones", { hint: handoffSentence(handoffs.core([
+		"names",
+		"migrate",
+		"--dry-run"
+	]), (dryRun) => handoffSentence(handoffs.core(["names", "migrate"]), (migrate) => `Run ${dryRun} to see what everything would be called, then ${migrate}.`), { instead: "Call comms_names_migrate from a chat." }) });
 }
 /** Every WhatsApp account's name, sorted. Other platforms' accounts in the same map are not this channel's. */
 function whatsappAccountNames(config) {
 	return Object.entries(config.accounts).filter(([, account]) => account.platform === PLATFORM).map(([name]) => name).sort();
 }
-function notFound(config, name) {
+function notFound(config, name, handoffs) {
 	return () => {
 		const known = whatsappAccountNames(config);
-		return new CommsError("NOT_FOUND", `no WhatsApp account called "${name}"`, { hint: known.length ? `Known accounts: ${known.join(", ")}.` : "None yet: a person adds one with `agent-whatsapp add <organisation/whatsapp>`." });
+		return new CommsError("NOT_FOUND", `no WhatsApp account called "${name}"`, { hint: known.length ? `Known accounts: ${known.join(", ")}.` : handoffSentenceToFill(handoffs.own(["add"]), ["<organisation>/whatsapp"], (command) => `None yet: a person adds one with ${command}.`) });
 	};
 }
 /**
@@ -8787,19 +10207,15 @@ function notFound(config, name) {
 * Through core's `resolveName`, so a former name is refused with the name the account has now. Another platform's
 * account under the name is "not found", as a missing one is. A record whose mode is not `read`, or whose `source`
 * is not a store path this package would read, is refused rather than acted on: nothing here would know what it
-* means, and the vocabulary is closed (design §5).
+* means, and the vocabulary is closed (design §5). A refusal names this package's commands as `handoffs` find them.
 */
-function requireAccount(config, name, platform = process.platform) {
+function requireAccount(config, name, handoffs) {
 	if (name === void 0 || name === "") throw new CommsError("USAGE", "which WhatsApp account? there is no default", { hint: "Pass the account, as `organisation/whatsapp`." });
-	requireNamedConfig(config);
-	const { account } = resolveName(config, "account", name, notFound(config, name));
-	if (account.platform !== "whatsapp") throw notFound(config, name)();
+	requireNamedConfig(config, handoffs);
+	const { account } = resolveName(config, "account", name, notFound(config, name, handoffs));
+	if (account.platform !== "whatsapp") throw notFound(config, name, handoffs)();
 	const mode = account.mode ?? account.tier;
-	if (mode !== "read") throw new CommsError("CONFIG", `"${name}" is recorded in mode "${String(mode)}", and WhatsApp accounts only read`, { hint: `Nothing was read. Remove it with ${inlineCommand(shellCommand([
-		"agent-whatsapp",
-		"remove",
-		name
-	], platform))} and add it again.` });
+	if (mode !== "read") throw new CommsError("CONFIG", `"${name}" is recorded in mode "${String(mode)}", and WhatsApp accounts only read`, { hint: `Nothing was read. ${handoffSentence(handoffs.own(["remove", name]), (command) => `Remove it with ${command} and add it again.`)}` });
 	const source = account.source;
 	if (source !== void 0 && (typeof source !== "string" || basename(source) !== "ChatStorage.sqlite")) throw new CommsError("CONFIG", `"${name}" names a store this package does not read`, { hint: `Only a file called ${STORE_FILE} is read. Remove the account and add it again.` });
 	return {
@@ -9230,7 +10646,7 @@ function nodeSupportsSqlite(version = process.versions.node) {
 /** Refuses to start on a Node too old for `node:sqlite`, saying which Node it is and what it needs. */
 function requireSupportedNode(version = process.versions.node) {
 	if (nodeSupportsSqlite(version)) return;
-	throw new CommsError("CONFIG", `agent-whatsapp needs Node ${MIN_NODE} or newer, and this is Node ${version}`, {
+	throw new CommsError("CONFIG", `the WhatsApp channel needs Node ${MIN_NODE} or newer, and this is Node ${version}`, {
 		hint: `It reads WhatsApp's store with Node's own SQLite (node:sqlite), which Node ${MIN_NODE} is the first to have complete. Install a newer Node — the current 22 or 24 release — and run it again.`,
 		details: {
 			reason: "NODE_TOO_OLD",
@@ -9253,7 +10669,7 @@ function loadSqlite() {
 				return await import("node:sqlite");
 			} catch (error) {
 				throw new CommsError("CONFIG", `this Node (${process.versions.node}) has no usable node:sqlite`, {
-					hint: `agent-whatsapp needs Node ${MIN_NODE} or newer, run without flags that turn built-in modules off.`,
+					hint: `The WhatsApp channel needs Node ${MIN_NODE} or newer, run without flags that turn built-in modules off.`,
 					cause: error
 				});
 			} finally {
@@ -9450,19 +10866,22 @@ var WhatsAppIndex = class WhatsAppIndex {
 	constructor(db) {
 		this.#db = db;
 	}
-	/** Every read opens the index through here, and cannot without the account's lists. */
-	static async open(directory, accountName, visibility, platform = process.platform) {
+	/**
+	* Every read opens the index through here, and cannot without the account's lists. A refusal names the sync to run
+	* as `handoffs` find it.
+	*/
+	static async open(directory, accountName, visibility, handoffs) {
 		const path = join(directory, INDEX_FILE);
+		const sync = () => handoffs.own([
+			"sync",
+			"--account",
+			accountName
+		]);
 		try {
 			await stat(path);
 		} catch {
 			throw new CommsError("NOT_FOUND", `"${accountName}" has not been synced yet, so there is nothing to read`, {
-				hint: `Run ${inlineCommand(shellCommand([
-					"agent-whatsapp",
-					"sync",
-					"--account",
-					accountName
-				], platform))} (or the whatsapp_sync tool) first.`,
+				hint: handoffSentence(sync(), (command) => `Run ${command} (or the whatsapp_sync tool) first.`, { instead: "Call the whatsapp_sync tool first." }),
 				details: { reason: "NOT_SYNCED" }
 			});
 		}
@@ -9470,12 +10889,7 @@ var WhatsAppIndex = class WhatsAppIndex {
 		const db = await openDatabase(path, { readOnly: true });
 		if (db.prepare("SELECT value FROM meta WHERE key = 'format'").get()?.value !== String(2)) {
 			db.close();
-			throw new CommsError("CONFIG", `the index for "${accountName}" was written by another version of this package`, { hint: `Run ${inlineCommand(shellCommand([
-				"agent-whatsapp",
-				"sync",
-				"--account",
-				accountName
-			], platform))} to rebuild it.` });
+			throw new CommsError("CONFIG", `the index for "${accountName}" was written by another version of this package`, { hint: handoffSentence(sync(), (command) => `Run ${command} to rebuild it.`, { instead: "Call the whatsapp_sync tool to rebuild it." }) });
 		}
 		db.function("agent_sees_chat", { deterministic: true }, (id) => visibility.seesChat(String(id)) ? 1 : 0);
 		db.function("agent_kind", { deterministic: true }, (id) => chatKindOf(String(id)));
@@ -9752,8 +11166,8 @@ var ChatListStore = class {
 *   so a run that stopped before the rename finishes on the next one.
 * - **Logged.** A line in core's audit log, and a line on stderr for the person when a command did it.
 *
-* A version-1 configuration has no `organisation/whatsapp` names, so nothing moves until `agentcomms names migrate`
-* has run; the file stays where it is and the next run tries again.
+* A version-1 configuration has no `organisation/whatsapp` names, so nothing moves until core's `names migrate` has
+* run — named as the context's handoffs find core's command — and the file stays where it is for the next run.
 */
 const SPIKE_CONFIG_FILE = "whatsapp-spike.json";
 const spikeAccountSchema = looseObject({
@@ -9807,7 +11221,7 @@ async function migrateSpikeAccounts(context) {
 		const config = await context.core.config.load();
 		if (config.version !== 2) return {
 			...result,
-			deferred: "the configuration still has the old flat names; after `agentcomms names migrate`, the spike’s accounts move on the next run"
+			deferred: `the configuration still has the old flat names; ${handoffSentence(context.handoffs.core(["names", "migrate"]), (command) => `after ${command}, the spike’s accounts move on the next run`, { instead: "after comms_names_migrate, the spike’s accounts move on the next run." }).replace(/\.$/, "")}`
 		};
 		const moving = [];
 		const records = Object.entries(spike.data.accounts).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
@@ -9945,6 +11359,8 @@ var WhatsAppContext = class {
 	surface;
 	platform;
 	core;
+	/** The commands this tells a person to run, located, and quoted for this context's shell. */
+	handoffs;
 	lists;
 	/** The name a pinned server was started for, as given. */
 	pinned;
@@ -9957,10 +11373,14 @@ var WhatsAppContext = class {
 		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
 		this.surface = options.surface ?? "cli";
 		this.platform = options.platform ?? process.platform;
-		this.core = openCore({
+		this.core = options.core ?? openCore({
 			env: this.env,
-			now: this.now
+			now: this.now,
+			platform: this.platform,
+			...options.pathOverrides ? { pathOverrides: options.pathOverrides } : {},
+			caller: CALLER
 		});
+		this.handoffs = requireHandoffs(this.core).on(this.platform);
 		this.lists = new ChatListStore(this.core.paths.configDir);
 		this.pinned = options.account;
 		this.#log = options.log;
@@ -9974,12 +11394,13 @@ var WhatsAppContext = class {
 	migration() {
 		this.#migration ??= migrateSpikeAccounts({
 			core: this.core,
+			handoffs: this.handoffs,
 			lists: this.lists,
 			env: this.env,
 			now: this.now,
 			surface: this.surface
 		}).then((result) => {
-			if (result) this.#log?.(`agent-whatsapp: ${describeMigration(result)}`);
+			if (result) this.#log?.(`WhatsApp: ${describeMigration(result)}`);
 			return result;
 		});
 		return this.#migration;
@@ -9997,7 +11418,7 @@ var WhatsAppContext = class {
 	*/
 	async checkPin() {
 		if (this.pinned === void 0) return;
-		this.#pinnedId = requireAccount(await this.config(), this.pinned, this.platform).account.id;
+		this.#pinnedId = requireAccount(await this.config(), this.pinned, this.handoffs).account.id;
 	}
 	/** The name a call acts on: the one it gave, checked against the pin when there is one. */
 	async #nameFor(config, named) {
@@ -10013,7 +11434,7 @@ var WhatsAppContext = class {
 	/** One account, resolved and checked, with the person's lists for it — which every read applies. */
 	async account(named) {
 		const config = await this.config();
-		const { name, account } = requireAccount(config, await this.#nameFor(config, named), this.platform);
+		const { name, account } = requireAccount(config, await this.#nameFor(config, named), this.handoffs);
 		return {
 			name,
 			account,
@@ -10040,7 +11461,8 @@ var WhatsAppContext = class {
 		return {
 			...this.#source,
 			env: this.env,
-			isDefault
+			isDefault,
+			handoffs: this.handoffs
 		};
 	}
 	/** The account's own directory under core's state directory: its index and its brief snapshots. */
@@ -10235,7 +11657,7 @@ async function draftMessage(context, request) {
 	for (const { name, account, lists } of scope) {
 		let index;
 		try {
-			index = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.platform);
+			index = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.handoffs);
 		} catch (error) {
 			if (scope.length > 1 && isCommsError(error) && error.details?.reason === "NOT_SYNCED") continue;
 			throw error;
@@ -10420,7 +11842,7 @@ async function openIndex(context, accountName) {
 	const { name, account, lists } = await context.account(accountName);
 	return {
 		name,
-		index: await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.platform)
+		index: await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.handoffs)
 	};
 }
 async function listChats(context, request) {
@@ -10560,7 +11982,7 @@ var SourceTimeout = class extends Error {
 const stuckCalls = /* @__PURE__ */ new WeakMap();
 function pendingError(options) {
 	return new CommsError("TRANSIENT", "reading WhatsApp’s message store is waiting for a macOS permission dialog", {
-		hint: `Look for a dialog asking whether ${responsibleApp(options.env ?? {}) ?? "your terminal or MCP client"} may access data from other apps, choose Allow, then run this again. An MCP server cannot answer it: run \`agent-whatsapp status\` in a terminal once, or grant Full Disk Access.`,
+		hint: `Look for a dialog asking whether ${responsibleApp(options.env ?? {}) ?? "your terminal or MCP client"} may access data from other apps, choose Allow, then run this again. ${handoffSentence(options.handoffs.own(["status"]), (command) => `An MCP server cannot answer it: run ${command} in a terminal once, or grant Full Disk Access.`, { instead: "An MCP server cannot answer it: grant Full Disk Access." })}`,
 		details: { reason: "MACOS_PROMPT_PENDING" }
 	});
 }
@@ -10600,7 +12022,11 @@ function sourceError(error, path, options) {
 	const code = error?.code;
 	const platform = options.platform ?? process.platform;
 	if (code === "ENOENT" || code === "ENOTDIR") return new CommsError("NOT_FOUND", `there is no WhatsApp message store at ${path}`, {
-		hint: options.isDefault ? "Is WhatsApp for Mac installed and signed in here? It creates this file once it has synced. The WhatsApp Business app keeps its own, under group.net.whatsapp.WhatsAppSMB.shared: pass it with --source." : "Check the path given with --source.",
+		hint: options.isDefault ? `Is WhatsApp for Mac installed and signed in here? It creates this file once it has synced. ${handoffSentenceToFill(options.handoffs.own(["add"]), [
+			"<organisation>/whatsapp",
+			"--source",
+			"<path to its ChatStorage.sqlite>"
+		], (command) => `The WhatsApp Business app keeps its own, under group.net.whatsapp.WhatsAppSMB.shared: add it with ${command}.`, { instead: "The WhatsApp Business app keeps its own, under group.net.whatsapp.WhatsAppSMB.shared: a person adds that with add’s --source." })}` : "Check the path given with --source.",
 		details: {
 			reason: "NO_STORE",
 			path
@@ -10745,7 +12171,7 @@ async function removeStaleSnapshots(workDir) {
 * The caller owns the result and must `dispose()` it: the copy is every message in the store, and it lives only as
 * long as the import that reads it.
 */
-async function snapshotStore(storePath, workDir, options = {}) {
+async function snapshotStore(storePath, workDir, options) {
 	checkStorePath(storePath);
 	const attempts = options.attempts ?? 5;
 	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -10799,7 +12225,7 @@ const SQLITE_HEADER = Buffer.from("SQLite format 3\0", "latin1");
 * Opening the file is what macOS's privacy check guards, so this is the cheapest honest test of access: a `stat` can
 * succeed where an `open` is refused. The bytes are only compared with SQLite's magic header.
 */
-async function probeStore(storePath, options = {}) {
+async function probeStore(storePath, options) {
 	checkStorePath(storePath);
 	const io = options.io ?? nodeSourceIo;
 	let header;
@@ -10860,7 +12286,7 @@ async function statusOf(context, named, check) {
 	}
 	let index = { synced: false };
 	try {
-		const opened = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.platform);
+		const opened = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.handoffs);
 		try {
 			const stats = opened.stats();
 			index = {
@@ -10903,7 +12329,7 @@ async function whatsappStatus(context, request) {
 		accounts,
 		reads: READS,
 		sends: SENDS,
-		...accounts.length === 0 ? { setup: "agent-whatsapp add <organisation>/whatsapp — run by a person, in a terminal" } : {},
+		...accounts.length === 0 ? { setup: handoffSentenceToFill(context.handoffs.own(["add"]), ["<organisation>/whatsapp"], (command) => `${command} — run by a person, in a terminal`) } : {},
 		...spike ? { spike: describeMigration(spike) } : {}
 	};
 }
@@ -10911,8 +12337,14 @@ async function whatsappStatus(context, request) {
 //#region src/operations/sync.ts
 /** Builds tried before a sync whose lists keep changing under it gives up. */
 const LIST_ROUNDS = 3;
-function removedWhileSyncing(name) {
-	return new CommsError("NOT_FOUND", `"${name}" was removed while it was being synced, so nothing was indexed`, { hint: "Add it again with `agent-whatsapp add` to read it." });
+/** The account went while it synced; adding it again — this name, this store — is the person's, located here. */
+function removedWhileSyncing(context, name, account) {
+	const add = [
+		"add",
+		name,
+		...account.source === void 0 ? [] : ["--source", account.source]
+	];
+	return new CommsError("NOT_FOUND", `"${name}" was removed while it was being synced, so nothing was indexed`, { hint: handoffSentence(context.handoffs.own(add), (command) => `Add it again with ${command} to read it.`) });
 }
 function sameLists(a, b) {
 	return JSON.stringify([a.allow, a.deny]) === JSON.stringify([b.allow, b.deny]);
@@ -10933,7 +12365,7 @@ async function syncAccount(context, request) {
 	const directory = context.accountDir(account);
 	return withFileLock(context.syncLock(account), async () => {
 		let current = await context.accountById(account.id);
-		if (!current) throw removedWhileSyncing(name);
+		if (!current) throw removedWhileSyncing(context, name, account);
 		await ensurePrivateDir(directory);
 		const staleRemoved = await removeStaleSnapshots(directory);
 		const snapshot = await snapshotStore(store.path, directory, context.sourceOptions(store.isDefault));
@@ -10957,7 +12389,7 @@ async function syncAccount(context, request) {
 						copied: snapshot.copied
 					}, new Visibility(built.lists), async () => {
 						const now = await context.accountById(account.id);
-						if (!now) throw removedWhileSyncing(built.name);
+						if (!now) throw removedWhileSyncing(context, built.name, account);
 						current = now;
 						return sameLists(now.lists, built.lists);
 					});
@@ -10991,4 +12423,4 @@ async function syncAccount(context, request) {
 	});
 }
 //#endregion
-export { paint as $, EXIT_CODES as A, colorEnabled as B, checkStorePath as C, CHANNELS as D, strictToolArguments as E, approvalsOf as F, gatedChangeAtTerminal as G, commandText as H, approveChangeAtTerminal as I, isCommsError as J, inlineCommand as K, canPrompt as L, absoluteSearchPath as M, agentMarker as N, CHANNEL_SERVERS as O, approvalKind as P, openCore as Q, channelManifest as R, storeIdentity as S, expandSource as T, escapeForDisplay as U, commandPathOf as V, exemptFromUpdateGate as W, nameAvailable as X, lookupName as Y, nameShapeProblem as Z, chatRefOf as _, listChats as a, shellCommand as at, requireAccount as b, Presenter as c, updateGateAtTerminal as ct, draftMessage as d, withFileLock as dt, renderInstall as et, Visibility as f, writeResult as ft, requireSupportedNode as g, WhatsAppIndex as h, CHAT_KINDS as i, serverPruneChange as it, UNTRUSTED_NOTICE as j, CommsError as k, innerText as l, updateToolGate as lt, WhatsAppContext as m, whatsappStatus as n, runCommand as nt, readChat as o, toCommsError as ot, listKey as p, VERSION$1 as pt, installExitStatus as q, probeStore as r, serverInstallChange as rt, searchMessages as s, truncateDisplay as st, syncAccount as t, renderPrune as tt, composeDraft as u, windowsSystemProgram as ut, PLATFORM as v, defaultStorePath as w, requireNamedConfig as x, newWhatsAppAccount as y, childEnvironment as z };
+export { paint as $, PATH_OPTIONS as A, colorEnabled as B, checkStorePath as C, CHANNEL_SERVERS as D, strictToolArguments as E, approvalsOf as F, handoffSentence as G, escapeForDisplay as H, approveChangeAtTerminal as I, isCommsError as J, handoffText as K, canPrompt as L, absoluteSearchPath as M, agentMarker as N, CommsError as O, approvalKind as P, openCore as Q, childEnvironment as R, storeIdentity as S, expandSource as T, exemptFromUpdateGate as U, commandPathOf as V, gatedChangeAtTerminal as W, nameAvailable as X, lookupName as Y, nameShapeProblem as Z, chatRefOf as _, VERSION$1 as _t, listChats as a, sendApprovesHint as at, requireAccount as b, Presenter as c, toCommsError as ct, draftMessage as d, updateToolGate as dt, pathOverridesFromCliOptions as et, Visibility as f, windowsSystemProgram as ft, requireSupportedNode as g, PACKAGE_NAME as gt, WhatsAppIndex as h, CALLER as ht, CHAT_KINDS as i, runCommand as it, UNTRUSTED_NOTICE as j, EXIT_CODES as k, innerText as l, truncateDisplay as lt, WhatsAppContext as m, writeResult as mt, whatsappStatus as n, renderPrune as nt, readChat as o, serverInstallChange as ot, listKey as p, withFileLock as pt, installExitStatus as q, probeStore as r, resolvePaths as rt, searchMessages as s, serverPruneChange as st, syncAccount as t, renderInstall as tt, composeDraft as u, updateGateAtTerminal as ut, PLATFORM as v, defaultStorePath as w, requireNamedConfig as x, newWhatsAppAccount as y, cliHandoffs as z };