@agentcomms/whatsapp 0.13.0 → 0.13.1

package/README.md

@@ -68,7 +68,7 @@ agent-whatsapp mcp install --client claude-code --account personal/whatsapp
 `mcp install` registers the server with your client, pinned to that account, as a change you approve: at a terminal
 you type `yes` to what it shows; run by an agent it exits `10` with a preview and an approval id, and the same command
 with `--approval <id>` registers it after your yes. Under the `confirm` change policy you approve with
-`agent-whatsapp approve <id>` and a code instead. Restart the client afterwards. From a chat, the core server's
+the approve command the result gives, and a code, instead. Restart the client afterwards. From a chat, the core server's
 `comms_server_install` with `channel: "whatsapp"` and `account` is the same change.
 
 For WhatsApp Business, add its store with

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as paint, A as EXIT_CODES, B as colorEnabled, C as checkStorePath, D as CHANNELS, F as approvalsOf, G as gatedChangeAtTerminal, H as commandText, I as approveChangeAtTerminal, J as isCommsError, K as inlineCommand, L as canPrompt, M as absoluteSearchPath, N as agentMarker, O as CHANNEL_SERVERS, P as approvalKind, Q as openCore, R as channelManifest, S as storeIdentity, T as expandSource, U as escapeForDisplay, V as commandPathOf, W as exemptFromUpdateGate, X as nameAvailable, Y as lookupName, Z as nameShapeProblem, _ as chatRefOf, a as listChats, at as shellCommand, b as requireAccount, c as Presenter, ct as updateGateAtTerminal, d as draftMessage, dt as withFileLock, et as renderInstall, f as Visibility, ft as writeResult, g as requireSupportedNode, h as WhatsAppIndex, i as CHAT_KINDS, it as serverPruneChange, k as CommsError, l as innerText, m as WhatsAppContext, n as whatsappStatus, nt as runCommand, o as readChat, p as listKey, pt as VERSION, q as installExitStatus, r as probeStore, rt as serverInstallChange, s as searchMessages, st as truncateDisplay, t as syncAccount, tt as renderPrune, ut as windowsSystemProgram, v as PLATFORM, w as defaultStorePath, x as requireNamedConfig, y as newWhatsAppAccount, z as childEnvironment } from "./sync-fzUQKMxy.mjs";
+import { $ as paint, A as PATH_OPTIONS, B as colorEnabled, C as checkStorePath, D as CHANNEL_SERVERS, F as approvalsOf, G as handoffSentence, H as escapeForDisplay, I as approveChangeAtTerminal, J as isCommsError, K as handoffText, L as canPrompt, M as absoluteSearchPath, N as agentMarker, O as CommsError, P as approvalKind, Q as openCore, R as childEnvironment, S as storeIdentity, T as expandSource, U as exemptFromUpdateGate, V as commandPathOf, W as gatedChangeAtTerminal, X as nameAvailable, Y as lookupName, Z as nameShapeProblem, _ as chatRefOf, _t as VERSION, a as listChats, at as sendApprovesHint, b as requireAccount, c as Presenter, d as draftMessage, et as pathOverridesFromCliOptions, f as Visibility, ft as windowsSystemProgram, g as requireSupportedNode, h as WhatsAppIndex, ht as CALLER, i as CHAT_KINDS, it as runCommand, k as EXIT_CODES, l as innerText, lt as truncateDisplay, m as WhatsAppContext, mt as writeResult, n as whatsappStatus, nt as renderPrune, o as readChat, ot as serverInstallChange, p as listKey, pt as withFileLock, q as installExitStatus, r as probeStore, rt as resolvePaths, s as searchMessages, st as serverPruneChange, t as syncAccount, tt as renderInstall, ut as updateGateAtTerminal, v as PLATFORM, w as defaultStorePath, x as requireNamedConfig, y as newWhatsAppAccount, z as cliHandoffs } from "./sync-DrWJVoXp.mjs";
 import { rm } from "node:fs/promises";
 import path, { delimiter, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -2989,22 +2989,27 @@ const WHATSAPP_MCP = {
 * The account itself is core's generic record in `config.json` (`config.ts`). Adding one loosens no setting core's
 * classifier judges — a new account in `read` on a platform whose only mode is `read` — so nothing is approved here:
 * the person typing the command is the one deciding.
+*
+* Every command they name — the one refused, the sync to run next, the remove that frees a name — is this
+* installation's own, located (`context.handoffs`): a bare `agent-whatsapp` is on nobody's PATH by default.
+*/
+/**
+* Refuses a command that is the person's to run, when an agent is running it — or when it is not at a terminal — and
+* hands the person that command: `words`, after the program, located here.
 */
-/** Refuses a command that is the person's to run, when an agent is running it — or when it is not at a terminal. */
-function refuseAnAgent(context, command, what) {
+function refuseAnAgent(context, words, what) {
 	const marker = agentMarker(context.env);
 	if (marker !== null || context.surface !== "cli") throw new CommsError("LOOSENING_REFUSED", `only a person ${what}`, {
-		hint: `Ask the person to run ${inlineCommand(command)} in their own terminal.`,
+		hint: handoffSentence(context.handoffs.own(words), (command) => `Ask the person to run ${command} in their own terminal.`),
 		...marker === null ? {} : { details: { marker } }
 	});
 }
 async function addAccount(context, request) {
-	refuseAnAgent(context, shellCommand([
-		"agent-whatsapp",
+	refuseAnAgent(context, [
 		"add",
 		request.name,
 		...request.source === void 0 ? [] : ["--source", request.source]
-	], context.platform), "chooses which WhatsApp store an agent may read");
+	], "chooses which WhatsApp store an agent may read");
 	const problem = nameShapeProblem(request.name, PLATFORM);
 	if (problem) throw new CommsError("USAGE", problem);
 	const isDefault = request.source === void 0;
@@ -3016,13 +3021,9 @@ async function addAccount(context, request) {
 	const identity = storeIdentity(path, isDefault);
 	/** The same checks, before the store is opened and again inside the write: anything can happen in between. */
 	const refuseTaken = (config) => {
-		requireNamedConfig(config);
+		requireNamedConfig(config, context.handoffs);
 		const free = nameAvailable(config, "account", request.name, PLATFORM);
-		if (!free.ok) throw lookupName(config, "account", request.name)?.platform === "whatsapp" ? new CommsError("USAGE", `"${request.name}" is already added`, { hint: `Remove it first with ${inlineCommand(shellCommand([
-			"agent-whatsapp",
-			"remove",
-			request.name
-		], context.platform))} to point it at another store.` }) : free.error;
+		if (!free.ok) throw lookupName(config, "account", request.name)?.platform === "whatsapp" ? new CommsError("USAGE", `"${request.name}" is already added`, { hint: handoffSentence(context.handoffs.own(["remove", request.name]), (command) => `Remove it first with ${command} to point it at another store.`) }) : free.error;
 		for (const [name, other] of Object.entries(config.accounts)) {
 			if (other.platform !== "whatsapp") continue;
 			if (context.storeOf(other).path === path || other.workspace === identity.workspace) throw new CommsError("USAGE", `that store is already added, as "${name}"`, { hint: "One name per message store." });
@@ -3052,12 +3053,11 @@ async function addAccount(context, request) {
 			default: isDefault,
 			id: account.workspace
 		},
-		next: commandText(shellCommand([
-			"agent-whatsapp",
+		next: context.handoffs.own([
 			"sync",
 			"--account",
 			request.name
-		], context.platform))
+		])
 	};
 }
 /**
@@ -3066,12 +3066,8 @@ async function addAccount(context, request) {
 */
 const REMOVE_WAIT_MS = 6e4;
 async function removeAccount(context, request) {
-	refuseAnAgent(context, shellCommand([
-		"agent-whatsapp",
-		"remove",
-		request.name
-	], context.platform), "removes a WhatsApp account");
-	const { account } = requireAccount(await context.config(), request.name, context.platform);
+	refuseAnAgent(context, ["remove", request.name], "removes a WhatsApp account");
+	const { account } = requireAccount(await context.config(), request.name, context.handoffs);
 	await withFileLock(context.syncLock(account), async () => {
 		await context.core.config.update((config) => {
 			if (lookupName(config, "account", request.name)?.id !== account.id) throw new CommsError("TRANSIENT", `"${request.name}" changed while it was being removed`, { hint: "Nothing was removed. Run it again." });
@@ -3115,7 +3111,7 @@ function effectOf(lists) {
 async function named(context, name, account, chatId) {
 	let index;
 	try {
-		index = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(void 0), context.platform);
+		index = await WhatsAppIndex.open(context.accountDir(account), name, new Visibility(void 0), context.handoffs);
 	} catch (error) {
 		if (!isCommsError(error) || error.details?.reason !== "NOT_SYNCED") throw error;
 		return {
@@ -3136,12 +3132,11 @@ async function named(context, name, account, chatId) {
 }
 /** The one path every list change takes: the person check first, before any input is read. */
 async function change(context, command, request, next) {
-	refuseAnAgent(context, shellCommand([
-		"agent-whatsapp",
+	refuseAnAgent(context, [
 		command,
 		...request.chat === void 0 ? [] : [request.chat],
 		...request.account === void 0 ? [] : ["--account", request.account]
-	], context.platform), "changes which chats an agent may see");
+	], "changes which chats an agent may see");
 	const chatId = request.chat === void 0 ? void 0 : chatRefOf(request.chat, { international: true }).id;
 	const { name, account } = await context.account(request.account);
 	const { before, after } = await context.lists.update(account.id, (lists) => next(lists, chatId));
@@ -3151,12 +3146,11 @@ async function change(context, command, request, next) {
 		deny: [...after.deny],
 		changed: JSON.stringify(before) !== JSON.stringify(after),
 		effect: effectOf(after),
-		next: commandText(shellCommand([
-			"agent-whatsapp",
+		next: context.handoffs.own([
 			"sync",
 			"--account",
 			name
-		], context.platform)),
+		]),
 		...chatId === void 0 ? {} : await named(context, name, account, chatId)
 	};
 }
@@ -3238,12 +3232,13 @@ function size(bytes) {
 	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
 function renderAdded(result, color) {
-	return [`${paint(color, "green", "Added")} ${result.account} → ${escapeForDisplay(result.store.path)}${result.store.default ? " (WhatsApp for Mac)" : ""}`, `Next: ${result.next}`].join("\n");
+	return [`${paint(color, "green", "Added")} ${result.account} → ${escapeForDisplay(result.store.path)}${result.store.default ? " (WhatsApp for Mac)" : ""}`, `Next: ${handoffText(result.next)}`].join("\n");
 }
 function renderRemoved(result, color) {
 	return `${paint(color, "green", "Removed")} ${result.account}, and its local index. WhatsApp's own store was not touched.`;
 }
-function renderStatus(result, color, platform = process.platform) {
+/** Status for a person; an account not synced yet names the sync, located as `handoffs` find this package's CLI. */
+function renderStatus(result, color, handoffs) {
 	const lines = [];
 	if (result.accounts.length === 0) lines.push(`No WhatsApp account yet. ${result.setup ?? ""}`);
 	for (const account of result.accounts) {
@@ -3257,12 +3252,11 @@ function renderStatus(result, color, platform = process.platform) {
 			lines.push(`  index   ${account.index.chats} chats, ${account.index.messages} messages, ${account.index.media} with media, ${account.index.statusChats} status-update chat(s) · synced ${account.index.indexedAt}`);
 			if (account.index.unattributedStatus > 0) lines.push(`          ${unattributed(account.index.unattributedStatus)}`);
 			for (const entry of account.index.degraded) lines.push(paint(color, "dim", `          without ${entry.part}: ${entry.costs}`));
-		} else lines.push(`  index   not synced yet — ${commandText(shellCommand([
-			"agent-whatsapp",
+		} else lines.push(`  index   not synced yet — ${handoffText(handoffs.own([
 			"sync",
 			"--account",
 			account.account
-		], platform))}`);
+		]))}`);
 	}
 	lines.push("", paint(color, "dim", `Reads: ${result.reads}.`), paint(color, "dim", `Sends: ${result.sends}.`));
 	return lines.join("\n");
@@ -3290,7 +3284,7 @@ function renderChatLists(result, color) {
 		...result.warning ? [paint(color, "yellow", result.warning)] : [],
 		`  allow  ${list(result.allow)}`,
 		`  deny   ${list(result.deny)}`,
-		paint(color, "dim", `Every read and draft applies this now. What is hidden leaves the index, and what the last sync left out comes back, at the next sync: ${result.next}`)
+		paint(color, "dim", `Every read and draft applies this now. What is hidden leaves the index, and what the last sync left out comes back, at the next sync: ${handoffText(result.next)}`)
 	].join("\n");
 }
 function renderChats(result, color) {
@@ -3353,17 +3347,6 @@ function renderDraft(result, color, opened) {
 }
 //#endregion
 //#region src/cli/program.ts
-/**
-* Every channel's approve command that can have prepared a send, from the manifests: the channels whose accounts can
-* be in `send`. WhatsApp's is not among them — it never sends — and a channel added later is, without an edit here.
-*/
-function sendApproveCommands() {
-	const commands = CHANNELS.flatMap((channel) => {
-		const manifest = channelManifest(channel);
-		return manifest?.approve && manifest.accounts?.modes.includes("send") ? [`\`${manifest.approve}\``] : [];
-	});
-	return commands.length <= 1 ? commands.join("") : `${commands.slice(0, -1).join(", ")} or ${commands.at(-1)}`;
-}
 async function run(argv, deps = {}) {
 	const streams = deps.streams ?? {
 		stdout: process.stdout,
@@ -3380,21 +3363,51 @@ async function run(argv, deps = {}) {
 		writeOut: (text) => streams.stdout.write(text),
 		writeErr: (text) => streams.stderr.write(text)
 	}).addHelpText("after", `
-Getting started (a person, in a terminal):
-  agent-whatsapp add personal/whatsapp         reads WhatsApp for Mac's store; macOS may ask to allow access
-  agent-whatsapp sync --account personal/whatsapp
-  agent-whatsapp chats --account personal/whatsapp
-  agent-whatsapp search "invoice" --account personal/whatsapp
-  agent-whatsapp draft +15555550101 "On my way"   a link; you press send in WhatsApp
-  agent-whatsapp deny +15555550102 --account personal/whatsapp   agents never see that chat
-  agent-whatsapp mcp install --client claude-code --account personal/whatsapp
+Getting started — a person runs these with this CLI, in a terminal:
+  add personal/whatsapp         reads WhatsApp for Mac's store; macOS may ask to allow access
+  sync --account personal/whatsapp
+  chats --account personal/whatsapp
+  search "invoice" --account personal/whatsapp
+  draft +15555550101 "On my way"   a link; you press send in WhatsApp
+  deny +15555550102 --account personal/whatsapp   agents never see that chat
+  mcp install --client claude-code --account personal/whatsapp
 
 Nothing here connects to WhatsApp or any other server, and nothing here can send. Needs Node 22.16 or newer.
 
 Exit codes: 0 ok · 1 unexpected · 10 only a person may do that, or a change needs approval · 11 an update
-is out: update first, or put it off (agentcomms update, agentcomms update --later) · 64 usage
+is out: update first, or put it off (the stop names both commands) · 64 usage
 · 65 bad data (a store whose layout changed) · 66 not found · 69 unavailable · 75 temporary (retry;
 a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 configuration problem.`).exitOverride();
+	for (const { flag } of PATH_OPTIONS) program.addOption(new Option(`${flag} <dir>`, "pin this suite directory for this run").argParser((value) => {
+		if (value.length === 0) throw new InvalidArgumentError(`${flag} needs a non-empty directory`);
+		return value;
+	}));
+	let invocationCore;
+	const coreForInvocation = () => {
+		if (invocationCore) return invocationCore;
+		const options = program.opts();
+		const pathOverrides = pathOverridesFromCliOptions(Object.fromEntries(PATH_OPTIONS.map(({ key, option }) => [option, options[key]])));
+		invocationCore = Object.keys(pathOverrides).length === 0 && deps.core ? deps.core : openCore({
+			env,
+			platform,
+			pathOverrides,
+			caller: CALLER
+		});
+		return invocationCore;
+	};
+	/**
+	* This installation's own `--help`, for a command line that named nothing it can run: located from this package, and
+	* pinned to no folder, since help opens none — so it is there even before the folders are known.
+	*/
+	const help = () => cliHandoffs({
+		caller: CALLER,
+		paths: resolvePaths({
+			env,
+			platform
+		}),
+		platform,
+		env
+	}).own(["--help"], { uses: [] });
 	const output = () => {
 		const options = program.opts();
 		return {
@@ -3412,7 +3425,7 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 	program.hook("preAction", async (_program, command) => {
 		const path = commandPathOf(command);
 		if (exemptFromUpdateGate(path, ["status"])) return;
-		const core = openCore({ env });
+		const core = coreForInvocation();
 		let ended = null;
 		const code = await runCommand(output(), async () => {
 			ended = await updateGateAtTerminal({
@@ -3424,7 +3437,6 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 				output: output(),
 				noInput: false,
 				streams,
-				approveCommand: "agent-whatsapp approve",
 				approvals: approvalsOf(command)
 			});
 		}, streams);
@@ -3441,7 +3453,9 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 			requireSupportedNode();
 			await body(new WhatsAppContext({
 				...deps,
+				core: coreForInvocation(),
 				env,
+				pathOverrides: coreForInvocation().pathOverrides,
 				surface: "cli",
 				log: deps.log ?? ((line) => streams.stderr.write(`${line}\n`))
 			}), output(), ...args);
@@ -3486,7 +3500,7 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 			account: flags.account === void 0 ? void 0 : String(flags.account),
 			check: flags.check !== false
 		});
-		writeResult(result, options, () => renderStatus(result, options.color, context.platform), streams);
+		writeResult(result, options, () => renderStatus(result, options.color, context.handoffs), streams);
 	}));
 	accountOption(program.command("sync")).description("copy WhatsApp's store privately, check it, and rebuild the local index from the copy").action(act(async (context, options, flags) => {
 		const result = await syncAccount(context, { account: String(flags.account) });
@@ -3544,21 +3558,13 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 	program.command("approve <approvalId>").description("approve a change at this terminal — registering or pruning this server — by reading it and typing the code back; WhatsApp never sends, so there is no message to approve").action(act(async (context, options, approvalId) => {
 		const marker = agentMarker(env);
 		if (marker) throw new CommsError("APPROVAL_REQUIRED", "only a person can approve a change, not an agent", {
-			hint: `Ask the person to run ${inlineCommand(shellCommand([
-				"agent-whatsapp",
-				"approve",
-				approvalId
-			], context.platform))} in their own terminal.`,
+			hint: handoffSentence(context.handoffs.own(["approve", approvalId]), (command) => `Ask the person to run ${command} in their own terminal.`),
 			details: { marker }
 		});
-		if (!canPrompt(env, streams, { json: options.json })) throw new CommsError("APPROVAL_REQUIRED", "approving a change needs an interactive terminal", { hint: `Run ${inlineCommand(shellCommand([
-			"agent-whatsapp",
-			"approve",
-			approvalId
-		], context.platform))} directly in a terminal.` });
+		if (!canPrompt(env, streams, { json: options.json })) throw new CommsError("APPROVAL_REQUIRED", "approving a change needs an interactive terminal", { hint: handoffSentence(context.handoffs.own(["approve", approvalId]), (command) => `Run ${command} directly in a terminal.`) });
 		const pending = await context.core.approvals.get(approvalId);
 		if (!pending) throw new CommsError("NOT_FOUND", `no approval ${approvalId}`, { hint: "It may have expired, been used, or been cancelled. Prepare the change again." });
-		if (approvalKind(pending) !== "change") throw new CommsError("USAGE", `approval ${approvalId} is for a send, and WhatsApp never sends`, { hint: `Approve it with the command that prepared it — ${sendApproveCommands()} — not this one.` });
+		if (approvalKind(pending) !== "change") throw new CommsError("USAGE", `approval ${approvalId} is for a send, and WhatsApp never sends`, { hint: sendApprovesHint(await context.handoffs.registered(), approvalId) });
 		const outcome = await approveChangeAtTerminal(context.core, approvalId, env, {
 			json: options.json,
 			color: options.color,
@@ -3566,21 +3572,24 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 		}, streams);
 		streams.stdout.write(outcome.state === "approved" ? "Approved. This command approves; the change is applied by the command that prepared it.\n" : "Cancelled. Nothing was changed.\n");
 	}));
-	const changeAt = (context, change, flags, command) => gatedChangeAtTerminal(context.core, change, {
+	/** A change at this terminal; `rerun` is this command's words after the program, run again with its approval. */
+	const changeAt = (context, change, flags, rerun) => gatedChangeAtTerminal(context.core, change, {
 		approvalId: flags.approval === void 0 ? void 0 : String(flags.approval),
 		env,
 		output: output(),
-		command,
-		approveCommand: "agent-whatsapp approve",
+		rerun,
 		streams
 	});
 	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;
 		exitCode = await runCommand(output(), async () => {
 			requireSupportedNode();
-			await (deps.startMcp ?? (await import("./stdio-entry-BCIfuv69.mjs")).startWhatsAppStdioServer)({
+			await (deps.startMcp ?? (await import("./stdio-entry-vXXVDpnA.mjs")).startWhatsAppStdioServer)({
 				env,
 				platform,
+				...deps,
+				core: coreForInvocation(),
+				pathOverrides: coreForInvocation().pathOverrides,
 				...flags.account ? { account: String(flags.account) } : {}
 			});
 		}, streams);
@@ -3598,13 +3607,19 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 		"npx",
 		"local"
 	])).option("--no-verify", "do not start the server to check the entry works").option("--force", "replace this server's own earlier entry — this is how you upgrade", false).option("--print", "only print what would be written", false).option("--approval <approvalId>", "register the server this approval was given for").action(act(async (context, options, flags) => {
-		if (!flags.client) throw new CommsError("USAGE", "name the client with --client", { hint: "For example: `agent-whatsapp mcp install --client claude-code --account personal/whatsapp`." });
+		if (!flags.client) throw new CommsError("USAGE", "name the client with --client", { hint: handoffSentence(context.handoffs.own([
+			"mcp",
+			"install",
+			"--client",
+			"claude-code",
+			"--account",
+			"personal/whatsapp"
+		]), (command) => `For example: ${command}.`) });
 		const pinned = flags.account ?? mcp.opts().account;
 		const launcher = flags.launcher;
 		const name = flags.name;
 		await context.migration();
-		const again = shellCommand([
-			"agent-whatsapp",
+		const again = [
 			"mcp",
 			"install",
 			"--client",
@@ -3614,7 +3629,7 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 			...launcher !== void 0 ? ["--launcher", launcher] : [],
 			...flags.verify === false ? ["--no-verify"] : [],
 			...flags.force === true ? ["--force"] : []
-		], context.platform);
+		];
 		const result = await changeAt(context, serverInstallChange(context.core, env, {
 			channel: "whatsapp",
 			client: flags.client,
@@ -3634,12 +3649,11 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 			channel: "whatsapp",
 			dryRun: flags.dryRun === true,
 			includePrinted: flags.includePrinted === true
-		}, WHATSAPP_MCP), flags, shellCommand([
-			"agent-whatsapp",
+		}, WHATSAPP_MCP), flags, [
 			"mcp",
 			"prune",
 			...flags.includePrinted === true ? ["--include-printed"] : []
-		], context.platform));
+		]);
 		writeResult(result, output(), () => renderPrune(result, options.color), streams);
 	}));
 	try {
@@ -3653,13 +3667,14 @@ a macOS dialog may be waiting) · 77 permission needed (macOS privacy) · 78 con
 			].includes(error.code)) return 0;
 			const message = error.message.replace(/^error: /, "");
 			return runCommand(output(), async () => {
-				throw new CommsError("USAGE", message, { hint: "Run `agent-whatsapp --help` to see the commands." });
+				throw new CommsError("USAGE", message, { hint: handoffSentence(help(), (command) => `Run ${command} to see the commands.`) });
 			}, streams);
 		}
 		throw error;
 	}
 	if (!ran) {
-		streams.stderr.write(`${paint(output().color, "dim", "Nothing to do. Try `agent-whatsapp --help`.")}\n`);
+		const said = handoffSentence(help(), (command) => `Try ${command}.`);
+		streams.stderr.write(`${paint(output().color, "dim", `Nothing to do. ${said}`)}\n`);
 		return 64;
 	}
 	return exitCode;