@agentcomms/resend 0.12.1 → 0.12.2

package/dist/cli.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { $ as installExitStatus, B as agentMarker, C as policyChange, D as sendPolicyOf, E as removeAccountChange, F as CHANNEL_SERVERS, H as approvalsOf, I as CommsError, J as commandPathOf, L as EXIT_CODES, N as checkNewName, O as showAccount, Q as gatedChangeAtTerminal, R as SEND_LOOKUP, S as policyApprovalRefusal, T as policyWanted, U as approveChangeAtTerminal, V as approvalKind, W as canPrompt, X as exemptFromUpdateGate, Y as escapeForDisplay, _ as runDoctor, a as revokeSendApproval, at as runCommand, b as listAccounts, c as downloadReceived, ct as serverPruneChange, d as listReceived, dt as truncateDisplay, et as openCore, f as listScheduled, ft as updateGateAtTerminal, g as showSentEmail, h as showReceived, i as prepareSend, it as renderPrune, k as ResendContext, l as getMetrics, lt as terminalUpdateHooks, m as listSuppressions, mt as writeResult, n as executeSend, nt as refuseUnclaimedApproval, o as sendStatus, ot as runUpdateCheckChild, p as listSentEmails, q as colorEnabled, r as finishSendApproval, rt as renderInstall, s as cancelScheduledChange, st as serverInstallChange, t as beginSendApproval, tt as paint, u as listDomains, v as addAccountChange, w as policyReport, x as modeOf, y as inspectKey, yt as VERSION, z as UPDATE_CHECK_CHILD_COMMAND } from "./send-W8SmlF7p.mjs";
+import { $ as installExitStatus, B as agentMarker, C as policyChange, D as sendPolicyOf, E as removeAccountChange, F as CHANNEL_SERVERS, H as approvalsOf, I as CommsError, J as commandPathOf, L as EXIT_CODES, N as checkNewName, O as showAccount, Q as gatedChangeAtTerminal, R as SEND_LOOKUP, S as policyApprovalRefusal, T as policyWanted, U as approveChangeAtTerminal, V as approvalKind, W as canPrompt, X as exemptFromUpdateGate, Y as escapeForDisplay, _ as runDoctor, a as revokeSendApproval, at as runCommand, b as listAccounts, c as downloadReceived, ct as serverPruneChange, d as listReceived, dt as truncateDisplay, et as openCore, f as listScheduled, ft as updateGateAtTerminal, g as showSentEmail, h as showReceived, i as prepareSend, it as renderPrune, k as ResendContext, l as getMetrics, lt as terminalUpdateHooks, m as listSuppressions, mt as writeResult, n as executeSend, nt as refuseUnclaimedApproval, o as sendStatus, ot as runUpdateCheckChild, p as listSentEmails, q as colorEnabled, r as finishSendApproval, rt as renderInstall, s as cancelScheduledChange, st as serverInstallChange, t as beginSendApproval, tt as paint, u as listDomains, v as addAccountChange, w as policyReport, x as modeOf, y as inspectKey, yt as VERSION, z as UPDATE_CHECK_CHILD_COMMAND } from "./send-BlDpMIlS.mjs";
 import path from "node:path";
 import fs from "node:fs";
-import childProcess from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { stripVTControlCharacters } from "node:util";
+import childProcess from "node:child_process";
 import process$1 from "node:process";
 import { EventEmitter } from "node:events";
 import { Writable } from "node:stream";
@@ -3405,7 +3405,7 @@ is out: update first, or put it off (agentcomms update, agentcomms update --late
 	}));
 	const mcp = program.command("mcp").description("run the MCP server on stdio, for a coding agent to connect to").option("--account <name>", "pin the server to one account; every tool then acts on it and no other").action(async (flags) => {
 		ran = true;
-		const { startResendStdioServer } = await import("./stdio-entry-h_wAVp9z.mjs");
+		const { startResendStdioServer } = await import("./stdio-entry-Cibag7m5.mjs");
 		await startResendStdioServer({
 			...deps,
 			env,

package/dist/index.d.mts

@@ -11509,7 +11509,7 @@ type RegisteredPrompt = {
   remove(): void;
 };
 //#endregion
-//#region ../core/dist/index.d.mts
+//#region ../core/dist/change-flow-C4tw0Usg.d.mts
 type SendPolicy = "chat" | "confirm" | "never";
 /**
  * How a loosening of the configuration is approved: `chat` — the person says yes in the conversation and the agent
@@ -12006,6 +12006,17 @@ interface ClaimOptions {
    * names no product at all rather than the wrong one.
    */
   pendingHint?: string | undefined;
+  /**
+   * The caller's cancellation — an MCP request's signal — asked under the record's lock, immediately before the claim
+   * would change the record.
+   *
+   * A claim can wait: for the lock, while another process holds it. A caller that looked at its signal before calling
+   * and found it clear could be cancelled during that wait, and the claim then went through all the same, spending an
+   * approval on a call nobody was waiting for any more — whose outcome its caller then had to record as a failure,
+   * since a claim cannot be put back. Asked here, a cancellation that lands before the record changes leaves it exactly
+   * as it was, for the same call made again; one that lands after is the caller's to handle, as it always was.
+   */
+  signal?: AbortSignal | undefined;
 }
 declare class ApprovalStore {
   #private;
@@ -12099,10 +12110,14 @@ declare class ApprovalStore {
    * 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.
    */
   claimForDownload(approvalId: string, live: DownloadRequest, options?: {
     policy?: ChangePolicy | undefined;
     pendingHint?: string | undefined;
+    signal?: AbortSignal | undefined;
   }): Promise<ApprovalRecord & {
     download: DownloadBinding;
   }>;
@@ -12398,6 +12413,10 @@ interface ThrottleOptions {
   sleep?: (ms: number) => Promise<void>;
   /** Tests shorten this; nothing a person or an agent passes can. */
   intervalMs?: number;
+  /** How long one holder of the lock may keep everyone else waiting. Tests shorten this too. */
+  lockTimeoutMs?: number;
+  /** How long a request may wait for the lock in all: `LOCK_MAX_WAIT_MS`. Tests shorten this too. */
+  lockMaxWaitMs?: number;
 }
 //#endregion
 //#region src/context.d.ts

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { _t as RESEND_DOWNLOAD_ORIGIN, gt as RESEND_API_ORIGIN, ht as REFUSED, vt as ROUTES, yt as VERSION } from "./send-W8SmlF7p.mjs";
-import { t as createResendMcpServer } from "./server-ElSFoKeD.mjs";
+import { _t as RESEND_DOWNLOAD_ORIGIN, gt as RESEND_API_ORIGIN, ht as REFUSED, vt as ROUTES, yt as VERSION } from "./send-BlDpMIlS.mjs";
+import { t as createResendMcpServer } from "./server-B-ubuD7Z.mjs";
 //#region src/index.ts
 /**
 * The library entry of `@agentcomms/resend`.

package/dist/{send-W8SmlF7p.mjs → send-BlDpMIlS.mjs}

@@ -6,13 +6,13 @@ import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { homedir, platform, userInfo } from "node:os";
 import { constants as constants$1, realpathSync } from "node:fs";
-import { execFile, spawn } from "node:child_process";
 import "node:readline/promises";
 import { styleText } from "node:util";
+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.12.1";
+const VERSION$1 = "0.12.2";
 //#endregion
 //#region src/api/routes.ts
 /**
@@ -187,7 +187,7 @@ function refusedBecause(method, pathname) {
 	return null;
 }
 //#endregion
-//#region ../core/dist/update-check-Ba6REc8M.mjs
+//#region ../core/dist/update-check-B-WYPZae.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
@@ -564,9 +564,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);
@@ -581,10 +587,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));
 	}
@@ -2588,6 +2604,32 @@ function refusalFor(record) {
 	const kind = approvalKind(record);
 	return kind === "change" ? refuseChange : kind === "download" ? refuseDownload : refuse$1;
 }
+/**
+* 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"
+		}
+	});
+}
 /** The record as it may be shown to anyone, agents included: never the challenge hash. */
 function publicView(record) {
 	const { challengeHash: _hidden, ...rest } = record;
@@ -2796,6 +2838,7 @@ var ApprovalStore = class {
 		const result = await this.#transition(approvalId, (current) => {
 			this.#requireKind(current, "send");
 			if (current.state !== "pending" && current.state !== "approved") throw this.#stateError(current);
+			if (options.signal?.aborted) throw cancelledClaim(current);
 			const voidWith = (code, reason) => {
 				failure = {
 					code,
@@ -2906,6 +2949,7 @@ var ApprovalStore = class {
 		const result = await this.#transition(approvalId, (current) => {
 			this.#requireKind(current, "change");
 			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",
@@ -3033,6 +3077,9 @@ 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);
@@ -3040,6 +3087,7 @@ var ApprovalStore = class {
 		const result = await this.#transition(approvalId, (current) => {
 			this.#requireKind(current, "download");
 			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",
@@ -3308,6 +3356,219 @@ function nameAvailable(config, kind, name, platform) {
 	}
 	return { ok: true };
 }
+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.` });
+}
 /**
 * Enough of TOML to read codex's `config.toml`, and a refusal for anything else.
 *
@@ -4374,13 +4635,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) {
@@ -4388,14 +4649,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;
 }
@@ -4438,8 +4699,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",
@@ -4451,7 +4715,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
@@ -4494,8 +4758,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, [
@@ -4598,10 +4867,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);
@@ -4728,7 +4997,19 @@ async function mcpInstall(context, product, options, planned) {
 	const { cliName, binary, own, configPath, writes } = target;
 	const warnings = (product.warnAbout?.(existing.filter((server) => server.client === options.client)) ?? []).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) {
@@ -4823,7 +5104,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
 				});
 			}
@@ -4832,7 +5113,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;
@@ -5168,19 +5459,32 @@ function rivalPatterns(packages) {
 function escapeRegExp$2(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) {
@@ -5191,7 +5495,7 @@ 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;
@@ -5317,107 +5621,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
@@ -5978,21 +6181,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)
@@ -6075,8 +6282,10 @@ async function gatedChangeAtTerminal(core, change, options) {
 	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),
 			details: {
 				approvalId: prepared.approvalId,
 				policy: prepared.policy,
@@ -6110,7 +6319,8 @@ async function gatedChangeAtTerminal(core, change, options) {
 * 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}\`.`;
+	const run = typeof rerun === "string" ? `\`${rerun}\`` : inlineCommand(rerun);
+	return prepared.policy === "confirm" ? `Show the person the preview. They run \`${approveCommandOf({ approveCommand })} ${prepared.approvalId}\`; 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.
@@ -6792,7 +7002,7 @@ async function npmInstallGlobal(env, spec) {
 	}
 }
 /** The package version, read from package.json at build time. */
-const VERSION = "0.12.1";
+const VERSION = "0.12.2";
 /**
 * Registering, pruning and listing the MCP servers of every channel, from the core.
 *
@@ -7050,7 +7260,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.2"
 	};
 	const product = {
 		packageName,
@@ -7396,8 +7606,13 @@ async function latestReleases(names, latestVersion) {
 	if (first?.problem) throw new CommsError("PROVIDER_UNAVAILABLE", `${first.problem}${problems.length > 1 ? ` (and ${problems.length - 1} more)` : ""}`, { hint: "Nothing was checked or changed. Try again once the registry can be reached; `npm view <package> version` shows what npm itself reads." });
 	return Object.fromEntries(answers.map((answer) => [answer.name, answer.version ?? ""]));
 }
-/** How to register an entry again by hand: its channel's own `mcp install`, with every flag that decides its reach. */
-function installCommand(item) {
+/**
+* How to register an entry again by hand: its channel's own `mcp install`, with every flag that decides its reach.
+*
+* The entry's name and pins are read from the client's file, which may hold anything, so on Windows the command may
+* have no line to paste: the reasons below give it with `inlineCommand`, which shows it as words then.
+*/
+function installCommand(item, platform) {
 	const facts = channelServer(item.channel);
 	const words = [
 		facts.binary,
@@ -7408,7 +7623,7 @@ function installCommand(item) {
 	];
 	if (item.name !== facts.defaultServerName) words.push("--name", item.name);
 	words.push(...item.narrowing, "--force");
-	return words.join(" ");
+	return shellCommand(words, platform);
 }
 /**
 * Why a registration that is behind cannot be registered again from here, or undefined when it can.
@@ -7419,13 +7634,13 @@ function installCommand(item) {
 * been renamed or removed: registering it again would register a server that is refused when it starts.
 */
 async function whyNotUpdatable(context, config, item, narrowing) {
-	if (item.launcher !== "managed" && item.launcher !== "npx") return `it was not written by \`mcp install\`, so how it starts cannot be carried over; register it again with \`${installCommand(item)}\``;
+	if (item.launcher !== "managed" && item.launcher !== "npx") return `it was not written by \`mcp install\`, so how it starts cannot be carried over; register it again with ${inlineCommand(installCommand(item, context.platform))}`;
 	if (item.scope !== "user") return `it is registered for one project (in ${item.path}), and \`mcp install\` registers at user scope only; register it again from that project with ${item.client}'s own command`;
 	const target = await installTarget(context, {
 		client: item.client,
 		apply: true
 	});
-	if (!target.writes) return target.cliName ? `\`${target.cliName}\` is not ${clientCliSearch(context.env)}, so the entry cannot be replaced from here; run \`${installCommand(item)}\` where it is` : `this environment names no ${item.client} configuration to write to`;
+	if (!target.writes) return target.cliName ? `\`${target.cliName}\` is not ${clientCliSearch(context.env)}, so the entry cannot be replaced from here; run ${inlineCommand(installCommand(item, context.platform))} where it is` : `this environment names no ${item.client} configuration to write to`;
 	const own = pinOption(item.channel);
 	const pin = own === void 0 || own === "readOnly" ? void 0 : narrowing[own];
 	if (pin !== void 0) {
@@ -7469,7 +7684,8 @@ async function runtimesNeeded(dataDir, latest, managed) {
 async function inspect(core, env, deps) {
 	const context = {
 		env,
-		core
+		core,
+		platform: deps.platform
 	};
 	const scan = await scanRegisteredServers(env);
 	const unreadable = [...scan.unreadable];
@@ -7778,7 +7994,7 @@ async function planRegistrations(context, candidates, request) {
 		}
 		const keeps = narrowingArgs(item.channel, preflight.effective);
 		if (JSON.stringify(keeps) !== JSON.stringify(item.narrowing)) {
-			leave(item, `registering it again would not keep exactly ${item.narrowing.length > 0 ? item.narrowing.join(" ") : "no pin"}: ${item.client} itself has the entry as ${keeps.length > 0 ? keeps.join(" ") : "not pinned"}. Register it again yourself with the pins it should have: \`${installCommand(item)}\``);
+			leave(item, `registering it again would not keep exactly ${item.narrowing.length > 0 ? item.narrowing.join(" ") : "no pin"}: ${item.client} itself has the entry as ${keeps.length > 0 ? keeps.join(" ") : "not pinned"}. Register it again yourself with the pins it should have: ${inlineCommand(installCommand(item, context.platform))}`);
 			continue;
 		}
 		steps.push({
@@ -7803,7 +8019,8 @@ async function planRegistrations(context, candidates, request) {
 function updateChange(core, env, request = {}, deps = {}) {
 	const context = {
 		env,
-		core
+		core,
+		platform: deps.platform
 	};
 	let planned = null;
 	return {
@@ -7837,9 +8054,69 @@ function updateChange(core, env, request = {}, deps = {}) {
 			const result = await applyUpdate(context, planned, deps);
 			await recordFound(core, env, planned.report, deps, result);
 			return result;
+		},
+		refuseApproval: (approvalId) => {
+			if (planned === null) throw new CommsError("UNEXPECTED", "the update was refused before it was planned");
+			return nothingToApply(core, approvalId, planned);
 		}
 	};
 }
+/**
+* The refusal for an approval handed to an update with no step left in it (CUE-303).
+*
+* An update needs an approval only for its steps, so one with none takes no approval, and the general refusal said to
+* call again without it, as "it applies at once". An approval is prepared for an update while something is behind,
+* and it is usually claimed minutes later; meanwhile another session, or the person at a terminal, may have applied
+* the update. Then nothing is behind, calling again applies nothing, and "applies at once" read as an update about to
+* happen. So this says what is so: there is nothing to apply — nothing behind at all, or nothing that can be updated
+* from here — and the approval was not used, with what had become of it.
+*
+* The store is asked as it is. Its `get` answers null for an approval it does not have, and throws for anything else:
+* an id that is not one, a record it cannot read or parse. Every one of those was caught and said as "not used" with
+* nothing more, so a corrupt approval file or a permissions problem read as an approval that was simply not there.
+* Now a record that cannot be read goes up as itself, as it would from any other call that reads an approval, and an
+* id that is not one is said to be that.
+*/
+async function nothingToApply(core, approvalId, planned) {
+	if (!APPROVAL_ID_PATTERN.test(approvalId)) return new CommsError("USAGE", `nothing was changed: "${approvalId}" is not an approval id`, {
+		hint: "An approval id is the `approvalId` a call that needs approval returns, and nothing here needs one: a check — comms_update with `check`, or `agentcomms update --check` at a terminal — shows what is behind.",
+		details: { approvalId }
+	});
+	const record = await core.approvals.get(approvalId);
+	const unused = `so there is nothing to apply; the approval ${approvalId} was not used (${whatBecameOf(record)})`;
+	const details = {
+		approvalId,
+		...record ? { state: record.state } : {}
+	};
+	if (planned.nothingBehind) return new CommsError("USAGE", `nothing was changed: nothing is behind the latest release, ${unused}`, {
+		hint: "Nothing needs doing: a check — comms_update with `check`, or `agentcomms update --check` at a terminal — shows everything here up to date. A release published later is another update, with a preview and an approval of its own.",
+		details
+	});
+	return new CommsError("USAGE", `nothing was changed: what is behind cannot be updated from here, ${unused}`, {
+		hint: "Each is left for a person: a check — comms_update with `check`, or `agentcomms update --check` at a terminal — lists them, with why and what to run. The same call without the approval reports them too, and changes nothing.",
+		details
+	});
+}
+/**
+* What had become of an approval, for `nothingToApply`: none at all, or each state an approval can be in, by name.
+*
+* A record, so that a state added to the store is a type error here rather than a refusal that says nothing. The
+* send states are here too: any approval's id can be handed to an update, a send's among them, and this reads the
+* record before anything looks at its kind.
+*/
+function whatBecameOf(record) {
+	if (record === null) return "there is no approval by that id";
+	return {
+		pending: `it was still waiting to be approved, and lapses at ${record.expiresAt}`,
+		approved: `it had been approved, and lapses unspent at ${record.expiresAt}`,
+		sending: "it is an approval to send, and that send is under way",
+		used: "it had been spent already",
+		failed: "it had been spent on a send that failed",
+		unknown: "it had been spent on a send whose outcome was never recorded",
+		expired: `it had expired at ${record.expiresAt}`,
+		revoked: "it had been revoked"
+	}[record.state] ?? `it is ${JSON.stringify(record.state)}, a state this version does not know`;
+}
 /** The product a runtime of `packageName` is installed as: the channel whose package it is. */
 function runtimeProduct(packageName, version) {
 	const channel = CHANNELS.find((each) => channelServer(each).packageName === packageName);
@@ -8660,7 +8937,7 @@ function terminalUpdateHooks(core, env, options) {
 	};
 }
 //#endregion
-//#region ../core/dist/tool-arguments-CohGlMUZ.mjs
+//#region ../core/dist/tool-arguments-BMmJnuY4.mjs
 const APPLIED = Symbol.for("agentcomms.strictToolArguments");
 const TARGET = "draft-2020-12";
 /**
@@ -19982,12 +20259,38 @@ var Throttle = class {
 	#now;
 	#sleep;
 	#interval;
+	/**
+	* Five seconds **for each holder** of the lock, not for the whole line of callers ahead.
+	*
+	* Every Resend request on this machine takes this one lock, and an agent asking six accounts at once puts six
+	* callers on it at the same moment. With the timeout counted from when each began to wait, the sixth had to see
+	* five holders through inside one five-second budget; on a heavily loaded machine (a load of 97 on ten cores, in
+	* the pre-push run that showed it) the read and the fsynced write under the lock slow down with everything else,
+	* and it gave up with "another process is holding" while the lock was being handed on exactly as it should be. A
+	* person with several accounts and a busy machine would have had requests refused for no reason but the queue.
+	* Counted per holder, a caller gives up only once one holder has kept the lock for five seconds: the stuck lock
+	* the timeout is there for.
+	*
+	* Each request takes the lock once, to reserve its slot, and does its waiting outside it, so the line is only the
+	* requests in flight. But the lock is polled, not queued: whoever looks first after a release takes it, and a
+	* request that keeps looking at the wrong moment watches later ones go ahead of it, for as long as later ones keep
+	* arriving — and several servers each paging through sent mail keep them arriving. So the wait also has an end
+	* that no hand-over moves, `LOCK_MAX_WAIT_MS`, and past it the request is refused as a busy lock rather than left
+	* hanging. `after` waits the same way, because a stop it gave up on recording is a 429 that every other account
+	* carries on into.
+	*/
+	#lock;
 	/** Takes no account on purpose: see above. Every throttle on a state directory is the same one. */
 	constructor(stateDir, options = {}) {
 		this.path = join(stateDir, "resend", "throttle.json");
 		this.#now = options.now ?? Date.now;
 		this.#sleep = options.sleep ?? ((ms) => setTimeout$1(ms).then(() => void 0));
 		this.#interval = options.intervalMs ?? 500;
+		this.#lock = {
+			timeoutPerHolder: true,
+			maxWaitMs: options.lockMaxWaitMs ?? 3e4,
+			...options.lockTimeoutMs === void 0 ? {} : { timeoutMs: options.lockTimeoutMs }
+		};
 	}
 	async #read() {
 		try {
@@ -20004,6 +20307,10 @@ var Throttle = class {
 			throw error;
 		}
 	}
+	/** Runs `fn` holding the machine's one throttle lock, waiting for it as `#lock` says. */
+	#locked(fn) {
+		return withFileLock(`${this.path}.lock`, fn, this.#lock);
+	}
 	/** When Resend will next be asked anything from this machine, or null when it is not holding off. */
 	async blockedUntil() {
 		const state = await this.#read();
@@ -20031,7 +20338,7 @@ var Throttle = class {
 	* later.
 	*/
 	async before() {
-		const wait = await withFileLock(`${this.path}.lock`, async () => {
+		const wait = await this.#locked(async () => {
 			const state = await this.#read();
 			this.#refuseIfHeld(state);
 			const now = this.#now();
@@ -20062,7 +20369,7 @@ var Throttle = class {
 		else if (seconds("ratelimit-remaining") === 0) stopFor = seconds("ratelimit-reset") ?? 1;
 		if (stopFor === null) return null;
 		const until = this.#now() + Math.max(1, stopFor) * 1e3;
-		await withFileLock(`${this.path}.lock`, async () => {
+		await this.#locked(async () => {
 			const state = await this.#read();
 			await writeFileAtomic(this.path, JSON.stringify({
 				...state,

package/dist/{server-ElSFoKeD.mjs → server-B-ubuD7Z.mjs}

@@ -1,4 +1,4 @@
-import { A as CHANGE_POLICIES, C as policyChange, E as removeAccountChange, G as changeToolResult, I as CommsError, K as checkForUpdates, M as SEND_POLICIES, O as showAccount, P as strictToolArguments, R as SEND_LOOKUP, S as policyApprovalRefusal, T as policyWanted, Z as gatedChange, _ as runDoctor, b as listAccounts, c as downloadReceived, d as listReceived, f as listScheduled, g as showSentEmail, h as showReceived, i as prepareSend, j as MODES, k as ResendContext, l as getMetrics, m as listSuppressions, n as executeSend, nt as refuseUnclaimedApproval, o as sendStatus, p as listSentEmails, pt as updateToolGate, s as cancelScheduledChange, u as listDomains, ut as toCommsError, w as policyReport, yt as VERSION } from "./send-W8SmlF7p.mjs";
+import { A as CHANGE_POLICIES, C as policyChange, E as removeAccountChange, G as changeToolResult, I as CommsError, K as checkForUpdates, M as SEND_POLICIES, O as showAccount, P as strictToolArguments, R as SEND_LOOKUP, S as policyApprovalRefusal, T as policyWanted, Z as gatedChange, _ as runDoctor, b as listAccounts, c as downloadReceived, d as listReceived, f as listScheduled, g as showSentEmail, h as showReceived, i as prepareSend, j as MODES, k as ResendContext, l as getMetrics, m as listSuppressions, n as executeSend, nt as refuseUnclaimedApproval, o as sendStatus, p as listSentEmails, pt as updateToolGate, s as cancelScheduledChange, u as listDomains, ut as toCommsError, w as policyReport, yt as VERSION } from "./send-BlDpMIlS.mjs";
 import { S as union, c as boolean, g as object, h as number, s as array, x as string } from "./schemas-DiGKNDNq.mjs";
 import { t as McpServer } from "./mcp-DXXb3Vv3-Co5BzjYe.mjs";
 //#region src/mcp/server.ts

package/dist/{stdio-entry-h_wAVp9z.mjs → stdio-entry-Cibag7m5.mjs}

@@ -1,4 +1,4 @@
-import { t as createResendMcpServer } from "./server-ElSFoKeD.mjs";
+import { t as createResendMcpServer } from "./server-B-ubuD7Z.mjs";
 //#region src/mcp/stdio-entry.ts
 /**
 * Starting the stdio server. On stdio, **stdout is the protocol**: one stray `console.log` corrupts the stream, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcomms/resend",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Resend for coding agents: read domains, sent and received mail, metrics and suppressions, and send mail that nothing sends without a person's approval of exactly what goes out.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "commander": "^15.0.0",
     "zod": "^4.6.5",
-    "@agentcomms/core": "0.12.1"
+    "@agentcomms/core": "0.12.2"
   },
   "publishConfig": {
     "access": "public"
@@ -94,5 +94,5 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --experimental-strip-types --test --test-timeout=600000 \"test/**/*.test.ts\""
   },
-  "gitHead": "62c13e382939518b8464df3e0f582d07b3bea4cd"
+  "gitHead": "224763228ecc63ce403f0d12988865cfaa981f2a"
 }