@agentcomms/whatsapp 0.12.1 → 0.12.3

package/dist/{sync-BiO86eEl.mjs → sync-DJlsr6xq.mjs}

@@ -4,16 +4,16 @@ import path, { basename, delimiter, dirname, isAbsolute, join, resolve, sep } fr
 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 { execFile, spawn } from "node:child_process";
-import { styleText } from "node:util";
 //#endregion
 //#region src/version.ts
 /** The package version, read from package.json at build time. */
-const VERSION$1 = "0.12.1";
+const VERSION$1 = "0.12.3";
 //#endregion
-//#region ../core/dist/update-check-Ba6REc8M.mjs
+//#region ../core/dist/update-check-Dq-D4bAD.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
@@ -392,9 +392,15 @@ async function takeOverStale(lockPath, staleMs) {
 async function withFileLock(lockPath, fn, options = {}) {
 	const timeoutMs = options.timeoutMs ?? 5e3;
 	const staleMs = options.staleMs ?? 3e4;
-	const deadline = Date.now() + timeoutMs;
+	const started = Date.now();
+	let deadline = started + timeoutMs;
+	/** `maxWaitMs`'s end: fixed when the wait begins, whatever the lock does. */
+	const limit = options.maxWaitMs === void 0 ? Number.POSITIVE_INFINITY : started + options.maxWaitMs;
 	const token = randomBytes(12).toString("hex");
 	let lastCode = "EEXIST";
+	/** The token of the holder this caller saw last, and how many times it has seen the lock change hands. */
+	let holder;
+	let handOvers = 0;
 	await ensurePrivateDir(dirname(lockPath));
 	for (;;) try {
 		const handle = await open(lockPath, "wx", 384);
@@ -409,10 +415,20 @@ async function withFileLock(lockPath, fn, options = {}) {
 		const code = error.code;
 		if (!CONTENDED.has(code ?? "")) throw error;
 		lastCode = code ?? lastCode;
-		if (code === "EEXIST" && await isStale(lockPath, await readLock(lockPath), staleMs)) {
-			await takeOverStale(lockPath, staleMs);
-			continue;
+		if (code === "EEXIST") {
+			const body = await readLock(lockPath);
+			if (await isStale(lockPath, body, staleMs)) {
+				await takeOverStale(lockPath, staleMs);
+				continue;
+			}
+			const seen = typeof body?.token === "string" ? body.token : void 0;
+			if (seen !== void 0 && seen !== holder) {
+				if (holder !== void 0) handOvers += 1;
+				holder = seen;
+				if (options.timeoutPerHolder) deadline = Date.now() + timeoutMs;
+			}
 		}
+		if (Date.now() > limit) throw new CommsError("LOCK_TIMEOUT", `gave up waiting for ${lockPath}: the wait hit its overall limit of ${(limit - started) / 1e3} s`, { hint: (handOvers > 0 ? `It changed hands ${handOvers} time(s) while this waited, never to this process: busy rather than stuck. Retry in a moment.` : "Retry in a moment. If it persists and no other process is running, delete the lock file.") + (lastCode === "EEXIST" ? "" : ` (last error: ${lastCode})`) });
 		if (Date.now() > deadline) throw new CommsError("LOCK_TIMEOUT", `another agent-communications process is holding ${lockPath}`, { hint: `Retry in a moment. If it persists and no other process is running, delete the lock file.` + (lastCode === "EEXIST" ? "" : ` (last error: ${lastCode})`) });
 		await setTimeout$1(25 + Math.floor(Math.random() * 50));
 	}
@@ -950,6 +966,253 @@ function connectMailboxCommand() {
 	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;
+}
+/**
+* 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.
+*
+* 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
+* as quotes at all, so `'C:\Profiles\First Last\outgoing'` reached the command as two words, quote marks and all, and
+* PowerShell does, but escapes a quote inside them by doubling it rather than as `'\''`. A command printed on Windows
+* has to be safe in both, because nothing says which one it will be pasted into (CUE-306) — and safe is not enough:
+* the program has to receive the same words from either. Three readers stand between the line and the program. cmd.exe
+* hands the program the line as it is, and the program's own parser (the C runtime's, Node's) splits it. PowerShell
+* reads the line itself, a double-quoted word with its backslashes as plain characters, and then writes a new command
+* line for the program: Windows PowerShell 5.1 the old way ("Legacy" in about_Parsing, "Passing arguments to native
+* applications") — a word quoted only when it holds whitespace, as it is, and an empty word dropped — and PowerShell
+* 7.3 and later its own way ("Standard") — quoted when it must be, with every backslash before a quote doubled. For a
+* `.cmd` script, which is how npm installs `agentcomms`, `claude` and `codex` on Windows, PowerShell 7 goes back to the
+* old way, and cmd.exe then reads that new line. So on Windows:
+*
+* - A word of letters, digits and `_ + = : . / \`, with `@` and `-` anywhere but first, is left as it is: no reader
+*   does anything with it, and a backslash is an ordinary character to all of them, at the end too. A first `@` is
+*   splatting to PowerShell, and a `,` its array operator — two words — so a word with either is quoted. So is a word
+*   that starts with a digit, which PowerShell may read as a number (`1kb`, `0x10`), and one that starts with `-` but
+*   is not a plain option, which PowerShell may read as a parameter of its own and split (`-name.x`).
+* - A word that double quotes bring through all three readers whole goes in double quotes. Inside them cmd.exe reads
+*   `& | < > ^ ( )` and spaces as ordinary characters, and PowerShell reads everything as ordinary but `$`, the
+*   backtick and a double quote. What is left special in one or the other is kept out: a double quote, which ends the
+*   quoting in both — and PowerShell takes the curly ones, `“ ” „`, for one too; `$` and the backtick, PowerShell's
+*   expansion and escape; `%`, which cmd.exe expands as `%NAME%` before it looks at quotes at all; `!`, which it
+*   expands as `!NAME!` inside quotes too wherever delayed expansion is on, and which then makes a `^` inside quotes an
+*   escape; and any control or formatting character — a line break ends the command in cmd.exe even inside quotes, a
+*   tab pasted into cmd.exe can complete a file name, and a right-to-left override shows a line other than the one
+*   that runs. Three more cannot come through: an empty word, which Windows PowerShell drops; a word ending in a
+*   backslash, which the C runtime reads with the closing quote as `\"` — and doubled for it, PowerShell 7 passes both
+*   backslashes on where cmd.exe and Windows PowerShell pass one; and a word with `& | < > ^ ( )` but no whitespace,
+*   which PowerShell passes to a `.cmd` script unquoted, for cmd.exe to run `&whoami` from or to split at `|`.
+* - With any other word in it, no line is printed at all (`line` is null), and the printers show the command's words
+*   as JSON instead, saying it has to be typed. Not a line with the word left out: a placeholder in its place was
+*   still a command that ran — `claude mcp remove NAME` removed whatever entry was called `NAME`, and an install
+*   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.
+*
+* Everywhere else there is always a line: single quotes make any word safe.
+*/
+function shellCommand(words, platform = process.platform) {
+	if (platform !== "win32") return {
+		words,
+		line: words.map(posixShellWord).join(" "),
+		platform
+	};
+	const printed = words.map(windowsShellWord);
+	return {
+		words,
+		line: printed.includes(null) ? 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);
+}
+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.
+*/
+function windowsShellWord(word) {
+	if (/^(?:--?[A-Za-z][A-Za-z0-9-]*|(?!\+?\.?\d)[\w+=:./\\][\w@+=:./\\-]*)$/.test(word)) return word;
+	if (word === "" || word.endsWith("\\")) return null;
+	if (/["$`%!\u201C-\u201E]|[\p{C}\p{Zl}\p{Zp}]/u.test(word)) return null;
+	if (/[&|<>^()]/.test(word) && !/\s/.test(word)) return null;
+	return `"${word}"`;
+}
+/**
+* The words of a command as a JSON array, for a command that cannot be printed as a line: something to read, and to
+* parse, and nothing to run.
+*
+* Pasted into either Windows shell by mistake, it runs nothing. PowerShell refuses it before running anything: a `[`
+* opens a type name, and a quoted string is none. cmd.exe looks for a program called `["agentcomms"` or the like, and
+* finds none — and nothing in the line is anything else to it: every character it acts on, inside quotes or out (`%`,
+* `!`), is written as a `\u` escape, and so is every double quote inside a word, so the quotes cmd.exe sees are the
+* JSON's own, in pairs, and `&`, `|`, `<`, `>`, `^` and the parentheses are only ever inside them, where it reads them
+* as characters. `$` and the backtick are escaped too, so that PowerShell would expand nothing even if it read on, and
+* so is everything outside printable ASCII — a line break, a curly quote, a right-to-left override. A backslash is
+* doubled, as JSON has it.
+*/
+function commandAsJson(words) {
+	const word = (text) => {
+		let json = "";
+		for (let index = 0; index < text.length; index++) {
+			const code = text.charCodeAt(index);
+			const char = text[index];
+			if (char === "\\") json += "\\\\";
+			else if (code >= 32 && code <= 126 && !"\"%!$`".includes(char)) json += char;
+			else json += `\\u${code.toString(16).padStart(4, "0")}`;
+		}
+		return `"${json}"`;
+	};
+	return `[${words.map(word).join(",")}]`;
+}
+/** 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;
+}
+/** 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: `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.` });
+}
 /**
 * 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.
@@ -1951,40 +2214,6 @@ function canonicalLoosening(loosening) {
 function sameLoosening(a, b) {
 	return canonicalLoosening(a) === canonicalLoosening(b);
 }
-/** 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);
-}
 /**
 * The digest a download's question is bound to: the account, the download, the request, the files it listed and the
 * names it showed them under.
@@ -2135,6 +2364,32 @@ function refusalFor(record) {
 	const kind = approvalKind(record);
 	return kind === "change" ? refuseChange : kind === "download" ? refuseDownload : refuse;
 }
+/**
+* A claim whose caller was cancelled before it changed anything (`ClaimOptions.signal`).
+*
+* `USAGE` and `cancelled:`, the words every cancellation in this repository is reported in, with `details.reason`
+* saying so for a caller that branches on it — and in the record's own kind: a question is not an approval, and
+* nothing is sent by answering one. The record is as it was, and the hint says so.
+*/
+function cancelledClaim(record) {
+	const kind = approvalKind(record);
+	if (kind === "download") return new CommsError("USAGE", "cancelled: nothing was saved", {
+		hint: "The question was not used: the same call, made again with the same answer, can still use it until it expires.",
+		details: {
+			choiceId: record.approvalId,
+			state: record.state,
+			reason: "cancelled"
+		}
+	});
+	return new CommsError("USAGE", `cancelled: ${kind === "change" ? "nothing was changed" : "nothing was sent"}`, {
+		hint: "The approval was not used: the same call, made again, can still use it until it expires.",
+		details: {
+			approvalId: record.approvalId,
+			state: record.state,
+			reason: "cancelled"
+		}
+	});
+}
 var ApprovalStore = class {
 	directory;
 	#now;
@@ -2247,19 +2502,23 @@ 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) {
+	#requireKind(record, kind, 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 \`agentcomms approve ${id}\` — 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.`);
+		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.`);
 	}
 	/** Issues a new challenge to show a human; only its hash is kept. */
-	async issueChallenge(approvalId, kind = "send") {
+	async issueChallenge(approvalId, kind = "send", platform = process.platform) {
 		const challenge = newChallenge();
 		await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, kind);
+			this.#requireKind(current, kind, platform);
 			if (current.state !== "pending") throw this.#stateError(current);
 			return {
 				...current,
@@ -2276,10 +2535,10 @@ var ApprovalStore = class {
 	* A change is approved the same way, with `kind: 'change'` and its digest standing in for the draft (see
 	* `createChange`), so a person's typed code means one thing whichever kind of approval it is typed for.
 	*/
-	async approve(approvalId, via, live, answer, kind = "send") {
+	async approve(approvalId, via, live, answer, kind = "send", platform = process.platform) {
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, kind);
+			this.#requireKind(current, kind, platform);
 			if (current.state !== "pending") throw this.#stateError(current);
 			if (!current.challengeHash) throw refusalFor(current)("APPROVAL_REQUIRED", "no challenge was issued for this approval", current);
 			if (live.draftMessageId !== current.draftMessageId || live.digest !== current.digest) {
@@ -2336,8 +2595,9 @@ var ApprovalStore = class {
 	async claimForSend(approvalId, live, options = {}) {
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "send");
+			this.#requireKind(current, "send", options.platform ?? process.platform);
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (code, reason) => {
 				failure = {
 					code,
@@ -2446,8 +2706,9 @@ var ApprovalStore = class {
 		const digest = changeDigest(live.change);
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "change");
+			this.#requireKind(current, "change", options.platform ?? process.platform);
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (reason) => {
 				failure = {
 					code: "APPROVAL_VOID",
@@ -2461,7 +2722,11 @@ 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 \`agentcomms approve ${approvalId}\` 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 ?? `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.approvedVia !== "terminal") return voidWith("the change policy is confirm, and this was not approved at a terminal");
 			}
 			return {
@@ -2538,13 +2803,13 @@ var ApprovalStore = class {
 	*
 	* Only a pending question can be answered, and only once: a second answer is refused, not taken over the first.
 	*/
-	async answerDownload(approvalId, via, answer) {
+	async answerDownload(approvalId, via, answer, platform = process.platform) {
 		const recorded = answer.choice === "other" ? {
 			choice: "other",
 			folder: answer.folder
 		} : { choice: answer.choice };
 		return await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "download");
+			this.#requireKind(current, "download", platform);
 			if (current.state === "approved") throw refuseDownload("APPROVAL_VOID", "the question was answered already, and it is answered once", current);
 			if (current.state !== "pending") throw this.#stateError(current);
 			if (!current.download || downloadDigest(current.download) !== current.digest) throw refuseDownload("APPROVAL_VOID", "the question does not describe the download it is bound to", current);
@@ -2575,13 +2840,17 @@ var ApprovalStore = class {
 	* gave it in the conversation. Under `confirm`, only a question the person answered at a terminal or in a trusted
 	* form can be claimed; a pending one is refused, and left as it is, so they can still answer it. One used, voided or
 	* expired is refused as an approval in that state is.
+	*
+	* `options.signal` is the download's cancellation, asked under the lock as a send's is (`ClaimOptions.signal`): a
+	* download cancelled while this waited saves nothing and leaves the question open, the answer still unused.
 	*/
 	async claimForDownload(approvalId, live, options = {}) {
 		const digest = downloadDigest(live);
 		let failure = null;
 		const result = await this.#transition(approvalId, (current) => {
-			this.#requireKind(current, "download");
+			this.#requireKind(current, "download", options.platform ?? process.platform);
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (reason) => {
 				failure = {
 					code: "APPROVAL_VOID",
@@ -3923,13 +4192,13 @@ 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) {
+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: \`${installCommand$1(product, options, other)}\`. --force does not replace a server this did not install.` });
+		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.` });
 	}
 	if (taken.length > 0 && !options.force) {
 		for (const pin of PIN_OPTIONS) {
@@ -3937,14 +4206,14 @@ function claimName(product, options, name, existing) {
 			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: \`${installCommand$1(product, options, second === name ? `${name}-2` : second)}\`.` });
+			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))}.` });
 		}
 		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: \`${installCommand$1(product, again, name, ["--force"])}\`.` });
+		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))}.` });
 	}
 	return taken;
 }
@@ -3987,8 +4256,11 @@ function keepNarrowing(product, options, previous) {
 * 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 = []) {
+function installCommand$1(product, options, name, extra, platform) {
 	const words = [
 		product.binary,
 		"mcp",
@@ -4000,7 +4272,7 @@ function installCommand$1(product, options, name, extra = []) {
 	words.push(...product.serverArgs(options));
 	if (options.launcher && options.launcher !== "managed") words.push("--launcher", options.launcher);
 	words.push(...extra);
-	return words.map((word) => /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`).join(" ");
+	return shellCommand(words, platform);
 }
 /**
 * A command's exit status and what it printed, kept here and never shown: codex prints an entry's env. Started as
@@ -4043,8 +4315,13 @@ 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) {
-	const unknown = () => new CommsError("CONFIG", `codex would not say what it has registered as "${name}", so nothing was written`, { hint: `Look with \`codex mcp get ${name}\`. If it is not an older copy of this server, choose another --name; \`--print\` shows the entry to add by hand.` });
+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([
+		"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.` });
 	let answer;
 	try {
 		answer = await capture$1(env, binary, [
@@ -4147,10 +4424,10 @@ async function preflightInstall(context, product, options) {
 		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) : [];
+	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");
-		if (reported) previous = claimName(product, options, name, [reported]);
+		const reported = await codexRegistration(context.env, binary, name, configPath ?? "codex", context.platform);
+		if (reported) previous = claimName(product, options, name, [reported], context.platform);
 	}
 	const { options: effective, kept } = keepNarrowing(product, options, previous);
 	const node = await resolveNode(context.env);
@@ -4275,9 +4552,21 @@ async function mcpInstall(context, product, options, planned) {
 	};
 	const existing = scan.servers;
 	const { cliName, binary, own, configPath, writes } = target;
-	const warnings = (product.warnAbout?.(existing.filter((server) => server.client === options.client)) ?? []).filter(Boolean);
+	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" ? `\`claude mcp remove ${name} --scope user\`` : options.client === "codex" ? `\`codex mcp remove ${name}\`` : `delete "${name}" from ${configPath}`;
+		const removal = options.client === "claude-code" ? inlineCommand(shellCommand([
+			"claude",
+			"mcp",
+			"remove",
+			name,
+			"--scope",
+			"user"
+		], context.platform)) : options.client === "codex" ? inlineCommand(shellCommand([
+			"codex",
+			"mcp",
+			"remove",
+			name
+		], context.platform)) : `delete "${name}" from ${configPath}`;
 		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) {
@@ -4372,7 +4661,7 @@ async function mcpInstall(context, product, options, planned) {
 					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 \`${installCommand$1(product, effective, name)}\`. The old entry is in ${backupPath}.`,
+					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}.`,
 					cause: error
 				});
 			}
@@ -4381,7 +4670,17 @@ async function mcpInstall(context, product, options, planned) {
 		} 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 \`${cliName} mcp get ${name}\`. If it is an older ${product.binary}, remove it with \`${cliName} mcp remove ${name}\` and run this again; if not, choose another --name.`,
+				hint: `Look at it with ${inlineCommand(shellCommand([
+					cliName,
+					"mcp",
+					"get",
+					name
+				], context.platform))}. If it is an older ${product.binary}, remove it with ${inlineCommand(shellCommand([
+					cliName,
+					"mcp",
+					"remove",
+					name
+				], context.platform))} and run this again; if not, choose another --name.`,
 				cause: error
 			});
 			throw error;
@@ -4717,19 +5016,32 @@ function rivalPatterns(packages) {
 function escapeRegExp(text) {
 	return text.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 }
-function gmailRemoval({ client, name: server, path, scope }) {
+/**
+* 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.
+*/
+function removalCommand(client, name, platform) {
+	return commandText(shellCommand([
+		client,
+		"mcp",
+		"remove",
+		name
+	], platform));
+}
+function gmailRemoval({ client, name: server, path, scope }, platform) {
 	if (scope === "project") return `remove "${server}" from the project entry in ${path} by hand`;
 	switch (client) {
-		case "claude-code": return `claude mcp remove ${server}`;
-		case "codex": return `codex mcp remove ${server}`;
+		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}`;
 	}
 }
 /**
 * Registered servers that are one of `packages` — another server for the same service whose send tools no approval
-* step gates — each with why it matters and how to remove it.
+* step gates — each with why it matters and how to remove it. `platform` is the shell the removal is quoted for.
 */
-function findRivalPackageServers(servers, packages) {
+function findRivalPackageServers(servers, packages, platform = process.platform) {
 	const patterns = rivalPatterns(packages);
 	const findings = [];
 	for (const server of servers) {
@@ -4740,14 +5052,14 @@ function findRivalPackageServers(servers, packages) {
 			...server,
 			packageName: known.name,
 			reason: `${known.name} exposes send tools that no approval step gates`,
-			removal: gmailRemoval(server)
+			removal: gmailRemoval(server, platform)
 		});
 	}
 	return findings;
 }
 /** What registering a server says about the rival packages its manifest names: one line each. */
-function rivalPackageWarnings(servers, packages) {
-	return findRivalPackageServers(servers, packages).map((finding) => `${finding.packageName} is registered with ${finding.client} as "${finding.name}": ${finding.reason}. Remove it: ${finding.removal}`);
+function rivalPackageWarnings(servers, packages, platform = process.platform) {
+	return findRivalPackageServers(servers, packages, platform).map((finding) => `${finding.packageName} is registered with ${finding.client} as "${finding.name}": ${finding.reason}. Remove it: ${finding.removal}`);
 }
 /**
 * Registered servers that name the service's `word` anywhere — their name, command, arguments or URL — and are not
@@ -4833,7 +5145,7 @@ function serverFactsOf({ packageName, manifest }) {
 	if (rivals === void 0) return facts;
 	return {
 		...facts,
-		warnAbout: (servers) => [...rivals.packages ? rivalPackageWarnings(servers, rivals.packages) : [], ...rivals.word !== void 0 && rivals.can !== void 0 ? rivalWordWarnings(servers, rivals.word, rivals.can, facts) : []]
+		warnAbout: (servers, platform) => [...rivals.packages ? rivalPackageWarnings(servers, rivals.packages, platform) : [], ...rivals.word !== void 0 && rivals.can !== void 0 ? rivalWordWarnings(servers, rivals.word, rivals.can, facts) : []]
 	};
 }
 const CHANNEL_SERVERS = Object.freeze(Object.fromEntries(CHANNEL_SNAPSHOT.map((entry) => [entry.manifest.channel, serverFactsOf(entry)])));
@@ -4866,107 +5178,6 @@ function requireChannelManifest(channel) {
 	if (manifest === void 0) throw notAChannel(channel);
 	return manifest;
 }
-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;
-}
-/** 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: `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.` });
-}
 /**
 * One renderer for every surface a send preview is shown on — the chat, an elicitation form, a terminal. Text the
 * draft's author controls (body, subject, display names, file names, link text) must not be able to change how the
@@ -5025,9 +5236,9 @@ function renderPrune(result, color) {
 	if (lines.length === 0) lines.push(`No managed runtimes to remove in ${result.runtimeDir}.`);
 	return lines.join("\n");
 }
-/** The terminal command that approves a change, for the channel that asked. */
-function approveCommandOf(options) {
-	return options.approveCommand ?? "agentcomms approve";
+/** 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
@@ -5138,7 +5349,7 @@ async function prepareChange(core, request, options) {
 				change: binding
 			}),
 			expiresAt: record.expiresAt,
-			next: nextStep(record.approvalId, policy, approveCommandOf(options))
+			next: nextStep(record.approvalId, policy, options)
 		};
 	} catch (error) {
 		await auditRefusal(core, "change.prepare", error, {
@@ -5169,7 +5380,10 @@ async function claimChange(core, approvalId, expect, options) {
 		const record = await core.approvals.claimForChange(approvalId, {
 			change: binding,
 			policy
-		}, { pendingHint: `Ask the user to run \`${approveCommandOf(options)} ${approvalId}\` in their own terminal, then try again with the same approval.` });
+		}, {
+			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
+		});
 		const decided = stricterPolicy(policy, record.requiredPolicy) === "chat" ? "chat" : "confirm";
 		await auditChange(core, {
 			operation: "change.claim",
@@ -5217,7 +5431,7 @@ async function beginChangeApproval(core, approvalId, options) {
 	let record;
 	try {
 		record = await changeRecord(core, approvalId);
-		const challenge = await core.approvals.issueChallenge(approvalId, "change");
+		const challenge = await core.approvals.issueChallenge(approvalId, "change", options.platform);
 		return {
 			approvalId,
 			preview: renderChangePreview(record),
@@ -5242,7 +5456,7 @@ async function finishChangeApproval(core, approvalId, answer, options) {
 		const approved = await core.approvals.approve(approvalId, "terminal", {
 			draftMessageId: digest,
 			digest
-		}, answer, "change");
+		}, answer, "change", options.platform);
 		await auditChange(core, {
 			operation: "change.approve",
 			outcome: "ok",
@@ -5298,8 +5512,8 @@ async function revokeChange(core, approvalId, reason, options) {
 function changePolicyOf(record) {
 	return record.requiredPolicy === "chat" ? "chat" : "confirm";
 }
-function nextStep(approvalId, policy, approveCommand) {
-	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 \`${approveCommand} ${approvalId}\` in their own terminal and type the code it shows. Then claim approval ${approvalId} and apply the change.`;
+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.`;
 }
 /**
 * One line per step of a change approval: who asked, from which surface, under which policy, and how it ended.
@@ -5420,21 +5634,25 @@ function renderChangePreview(record) {
 * it on the second call, with its id.
 *
 * A change that loosens no setting and does nothing irreversible is applied directly: asking a person to agree to
-* something that needs no agreement teaches them to agree without reading. It refuses an approval id, as a report
-* refuses one (`refuseApprovalWithoutChange`), rather than applying and dropping it: the update check's stop lets a
-* call claiming an approval through (design 2026-09-28 §2), and one that is then never claimed would carry any
-* approval the store holds — one an agent had just had prepared for "not now", say — past the stop, to a tightening
-* or a cancellation made where the call itself was stopped.
+* something that needs no agreement teaches them to agree without reading. It refuses an approval id — in the change's
+* own words when it has them (`refuseApproval`) — as a report refuses one (`refuseApprovalWithoutChange`), rather than
+* applying and dropping it: the update check's stop lets a call claiming an approval through (design 2026-09-28 §2),
+* and one that is then never claimed would carry any approval the store holds — one an agent had just had prepared for
+* "not now", say — past the stop, to a tightening or a cancellation made where the call itself was stopped.
 */
 async function gatedChange(core, change, options) {
 	const request = await change.plan(await core.config.load());
 	const loosens = classifyChange(request.before, request.after).loosened.length > 0;
 	const acts = (request.effects ?? []).length > 0;
 	if (!loosens && !acts) {
-		if (options.approvalId) throw new CommsError("USAGE", "nothing was changed: as things stand this change needs no approval, so it takes none", {
-			hint: "Make the same call again without the approval: it applies at once and asks nobody. An approval is spent only on the change it was prepared for.",
-			details: { approvalId: options.approvalId }
-		});
+		if (options.approvalId) {
+			const refusal = await change.refuseApproval?.(options.approvalId);
+			if (refusal !== void 0) throw refusal;
+			throw new CommsError("USAGE", "nothing was changed: as things stand this change needs no approval, so it takes none", {
+				hint: "Make the same call again without the approval: it applies at once and asks nobody. An approval is spent only on the change it was prepared for.",
+				details: { approvalId: options.approvalId }
+			});
+		}
 		return {
 			status: "applied",
 			result: await change.apply(void 0, request)
@@ -5444,12 +5662,14 @@ async function gatedChange(core, change, options) {
 		status: "approval-required",
 		prepared: await prepareChange(core, request, {
 			surface: options.surface,
-			approveCommand: options.approveCommand
+			approveCommand: options.approveCommand,
+			platform: options.platform
 		})
 	};
 	const consent = await claimChange(core, options.approvalId, request, {
 		surface: options.surface,
-		approveCommand: options.approveCommand
+		approveCommand: options.approveCommand,
+		platform: options.platform
 	});
 	return {
 		status: "applied",
@@ -5470,14 +5690,17 @@ async function gatedChangeAtTerminal(core, change, options) {
 	const first = await gatedChange(core, change, {
 		surface: "cli",
 		approvalId: options.approvalId,
-		approveCommand
+		approveCommand,
+		platform: options.output.platform
 	});
 	if (first.status === "applied") return first.result;
 	const { prepared } = first;
 	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;
 		throw new CommsError("APPROVAL_PENDING", `this change needs approval first: ${prepared.summary}`, {
-			hint: approvalHint(prepared, `${options.command} ${options.approvalFlag ?? "--approval"} ${prepared.approvalId}`, approveCommand),
+			hint: approvalHint(prepared, typeof command === "string" ? `${command} ${carrying.join(" ")}` : withWords(command, ...carrying), approveCommand, options.output.platform),
 			details: {
 				approvalId: prepared.approvalId,
 				policy: prepared.policy,
@@ -5498,7 +5721,8 @@ async function gatedChangeAtTerminal(core, change, options) {
 	const second = await gatedChange(core, change, {
 		surface: "cli",
 		approvalId: prepared.approvalId,
-		approveCommand
+		approveCommand,
+		platform: options.output.platform
 	});
 	if (second.status !== "applied") throw new CommsError("UNEXPECTED", "the approved change asked for approval again");
 	return second.result;
@@ -5510,8 +5734,9 @@ 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) {
-	return prepared.policy === "confirm" ? `Show the person the preview. They run \`${approveCommandOf({ approveCommand })} ${prepared.approvalId}\`; then run \`${rerun}\`.` : `Show the person the preview. Once they say yes, run \`${rerun}\`.`;
+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}.`;
 }
 /**
 * Approves a configuration change at a terminal, the way a person approves a send: read the preview, type the code.
@@ -5531,7 +5756,11 @@ 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: `agentcomms approve ${approvalId}`,
+			command: commandText(shellCommand([
+				"agentcomms",
+				"approve",
+				approvalId
+			], output.platform)),
 			color: output.color,
 			json: output.json
 		});
@@ -6048,7 +6277,7 @@ function isPrerelease(version) {
 	return VERSION_PATTERN.exec(version)?.[4] !== void 0;
 }
 /** The package version, read from package.json at build time. */
-const VERSION = "0.12.1";
+const VERSION = "0.12.3";
 /**
 * Registering, pruning and listing the MCP servers of every channel, from the core.
 *
@@ -6306,7 +6535,7 @@ function serverPruneChange(core, env, request, own) {
 	};
 	const { packageName, version } = ownProduct(request.channel, own) ?? {
 		packageName: channelServer(request.channel).packageName,
-		version: "0.12.1"
+		version: "0.12.3"
 	};
 	const product = {
 		packageName,
@@ -6930,7 +7159,7 @@ async function askLine(streams, question) {
 }
 channelServer("core").packageName;
 //#endregion
-//#region ../core/dist/tool-arguments-CohGlMUZ.mjs
+//#region ../core/dist/tool-arguments-BMgRZ6DZ.mjs
 const APPLIED = Symbol.for("agentcomms.strictToolArguments");
 const TARGET = "draft-2020-12";
 /**
@@ -8351,13 +8580,17 @@ function notFound(config, name) {
 * 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).
 */
-function requireAccount(config, name) {
+function requireAccount(config, name, platform = process.platform) {
 	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)();
 	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 \`agent-whatsapp remove ${name}\` 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. Remove it with ${inlineCommand(shellCommand([
+		"agent-whatsapp",
+		"remove",
+		name
+	], platform))} 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 {
@@ -9009,13 +9242,18 @@ var WhatsAppIndex = class WhatsAppIndex {
 		this.#db = db;
 	}
 	/** Every read opens the index through here, and cannot without the account's lists. */
-	static async open(directory, accountName, visibility) {
+	static async open(directory, accountName, visibility, platform = process.platform) {
 		const path = join(directory, INDEX_FILE);
 		try {
 			await stat(path);
 		} catch {
 			throw new CommsError("NOT_FOUND", `"${accountName}" has not been synced yet, so there is nothing to read`, {
-				hint: `Run \`agent-whatsapp sync --account ${accountName}\` (or the whatsapp_sync tool) first.`,
+				hint: `Run ${inlineCommand(shellCommand([
+					"agent-whatsapp",
+					"sync",
+					"--account",
+					accountName
+				], platform))} (or the whatsapp_sync tool) first.`,
 				details: { reason: "NOT_SYNCED" }
 			});
 		}
@@ -9023,7 +9261,12 @@ 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 \`agent-whatsapp sync --account ${accountName}\` to rebuild it.` });
+			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.` });
 		}
 		db.function("agent_sees_chat", { deterministic: true }, (id) => visibility.seesChat(String(id)) ? 1 : 0);
 		db.function("agent_kind", { deterministic: true }, (id) => chatKindOf(String(id)));
@@ -9491,6 +9734,7 @@ var WhatsAppContext = class {
 	env;
 	now;
 	surface;
+	platform;
 	core;
 	lists;
 	/** The name a pinned server was started for, as given. */
@@ -9503,6 +9747,7 @@ var WhatsAppContext = class {
 		this.env = options.env ?? process.env;
 		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
 		this.surface = options.surface ?? "cli";
+		this.platform = options.platform ?? process.platform;
 		this.core = openCore({
 			env: this.env,
 			now: this.now
@@ -9513,7 +9758,7 @@ var WhatsAppContext = class {
 		this.#source = {
 			io: options.sourceIo,
 			timeoutMs: options.sourceTimeoutMs,
-			platform: options.platform
+			platform: this.platform
 		};
 	}
 	/** The spike's accounts moved in, once per process; what happened, when there was a spike file to move. */
@@ -9543,7 +9788,7 @@ var WhatsAppContext = class {
 	*/
 	async checkPin() {
 		if (this.pinned === void 0) return;
-		this.#pinnedId = requireAccount(await this.config(), this.pinned).account.id;
+		this.#pinnedId = requireAccount(await this.config(), this.pinned, this.platform).account.id;
 	}
 	/** The name a call acts on: the one it gave, checked against the pin when there is one. */
 	async #nameFor(config, named) {
@@ -9559,7 +9804,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));
+		const { name, account } = requireAccount(config, await this.#nameFor(config, named), this.platform);
 		return {
 			name,
 			account,
@@ -9781,7 +10026,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));
+			index = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.platform);
 		} catch (error) {
 			if (scope.length > 1 && isCommsError(error) && error.details?.reason === "NOT_SYNCED") continue;
 			throw error;
@@ -9966,7 +10211,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))
+		index: await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.platform)
 	};
 }
 async function listChats(context, request) {
@@ -10406,7 +10651,7 @@ async function statusOf(context, named, check) {
 	}
 	let index = { synced: false };
 	try {
-		const opened = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists));
+		const opened = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(lists), context.platform);
 		try {
 			const stats = opened.stats();
 			index = {
@@ -10537,4 +10782,4 @@ async function syncAccount(context, request) {
 	});
 }
 //#endregion
-export { renderPrune as $, CommsError as A, colorEnabled as B, checkStorePath as C, strictToolArguments as D, UNTRUSTED_NOTICE as E, approvalsOf as F, installExitStatus as G, escapeForDisplay as H, approveChangeAtTerminal as I, nameAvailable as J, isCommsError as K, canPrompt as L, absoluteSearchPath as M, agentMarker as N, CHANNELS as O, approvalKind as P, renderInstall as Q, channelManifest as R, storeIdentity as S, expandSource as T, exemptFromUpdateGate as U, commandPathOf as V, gatedChangeAtTerminal as W, openCore as X, nameShapeProblem as Y, paint as Z, chatRefOf as _, listChats as a, updateGateAtTerminal as at, requireAccount as b, Presenter as c, withFileLock as ct, draftMessage as d, runCommand as et, Visibility as f, requireSupportedNode as g, WhatsAppIndex as h, CHAT_KINDS as i, truncateDisplay as it, EXIT_CODES as j, CHANNEL_SERVERS as k, innerText as l, writeResult as lt, WhatsAppContext as m, whatsappStatus as n, serverPruneChange as nt, readChat as o, updateToolGate as ot, listKey as p, lookupName as q, probeStore as r, toCommsError as rt, searchMessages as s, windowsSystemProgram as st, syncAccount as t, serverInstallChange as tt, composeDraft as u, VERSION$1 as ut, PLATFORM as v, defaultStorePath as w, requireNamedConfig as x, newWhatsAppAccount as y, childEnvironment as z };
+export { paint as $, CommsError as A, colorEnabled as B, checkStorePath as C, strictToolArguments as D, UNTRUSTED_NOTICE 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, CHANNELS 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, EXIT_CODES as j, CHANNEL_SERVERS 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 };