a2a-exposed 0.8.40 → 0.8.42

package/lib/a2a.mjs

@@ -1,11 +1,12 @@
 // Minimal A2A client helpers (0.3 + 1.0) and HTTP utilities.
 import crypto from "node:crypto";
+import { CLI_COMMAND } from "./config.mjs";
 
 export const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 
 /** The one way docs, hints and CLI output tell people (and agents) to run the CLI: npx, always the latest release, no
  *  global install (agent sandboxes block global installs as untrusted code). A global install is an optional speed-up. */
-export const CLI = "npx -y a2a-exposed@latest";
+export const CLI = CLI_COMMAND;
 
 export class CliError extends Error {}
 export const die = (msg) => { throw new CliError(msg); };

package/lib/commands.mjs

@@ -23,9 +23,16 @@ export async function ownerTry(method, path, body, timeout) {
 }
 
 function printPush(res) {
-	for (const r of (res && res.push) || []) console.error(`push -> ${r.url}: ${r.ok ? "ok" : "FAILED"} (${r.info})`);
+	for (const r of (res && res.push) || []) {
+		// Older Workers return a full URL. Print only its host, including on that compatibility path.
+		let host = r.host || "unknown host";
+		if (!r.host && r.url) { try { host = new URL(r.url).host; } catch { /* omit invalid URLs */ } }
+		console.error(`push -> ${r.role || "task push config"} ${host} [${r.fingerprint || "unknown fingerprint"}]: ${r.ok ? "ok" : "FAILED"} (${/^HTTP \d{3}$/.test(r.info) ? r.info : "push request failed"})`);
+	}
 }
 
+const printState = (state, timestamp, task = "") => console.log(`${task ? `${task} ` : ""}current state: ${plainState({ status: { state } })} (${timestamp || "timestamp unavailable"})`);
+
 function printDelivery(res) {
 	const d = res && res.delivery;
 	if (!d) return;
@@ -102,6 +109,7 @@ export async function inbox(o) {
 		console.log(r.text);
 		console.log("<<< END PEER MESSAGE");
 		if (reply) console.log(`(a reply to a message you sent; read it with \`${CLI} history ${r.contextId}\`. Continue with send, not reply.)`);
+		printState(r.state, r.updated);
 	}
 	if (pairing.length) {
 		console.log(`=== ${pairing.length} pending pairing request${pairing.length === 1 ? "" : "s"} (another agent asks to connect; ${pairing[0].approval} approval)`);
@@ -129,8 +137,10 @@ export async function reply(id, o) {
 	const res = await owner("POST", `/owner/tasks/${q(id)}/reply`, {
 		text, state: o.state, artifact: !!o.artifact, artifactName: o["artifact-name"], force: !!o.force,
 	});
+	printPush(res.delivery || res);
 	printDelivery(res);
 	console.log(`${id} -> ${o.state}`);
+	console.log(`task state saved: ${res.task?.status?.state || o.state} (peers can read it with GetTask even if a push fails)`);
 }
 
 export async function history(ctx, o) {
@@ -138,10 +148,15 @@ export async function history(ctx, o) {
 	if (o.from) qs.set("from", o.from);
 	const rows = await owner("GET", `/owner/history/${q(ctx)}?${qs}`);
 	if (o.json) return out(rows);
+	const states = new Map();
+	const peers = new Map(rows.filter((e) => e.task_id && e.peer).map((e) => [e.task_id, e.peer]));
 	for (const e of rows) {
 		const tag = [e.event, e.state || e.role].filter(Boolean).join("/");
-		console.log(`${e.ts} ${(e.dir || "").padEnd(5)} ${(e.peer || "-").padEnd(10)} ${e.task_id || "-"} ${tag}: ${(e.text || "").slice(0, 400)}`);
+		const forced = e.data?.forced ? `forced: ${e.data.previousState} → ${e.data.state}; ` : "";
+		console.log(`${e.ts} ${(e.dir || "").padEnd(5)} ${(e.peer || "-").padEnd(10)} ${e.task_id || "-"} ${tag}: ${forced}${(e.text || "").slice(0, 400)}`);
+		if (e.currentState?.state || e.state) states.set(`${e.peer || peers.get(e.task_id) || "-"}/${e.task_id || "-"}`, e.currentState || { state: e.state, timestamp: e.ts });
 	}
+	for (const [task, status] of states) printState(status.state, status.timestamp, states.size > 1 ? task : "");
 }
 
 export async function contexts() {

package/lib/config.mjs

@@ -9,7 +9,12 @@ export function defaultConfigDir(base = process.env.XDG_CONFIG_HOME || path.join
 	return path.join(base, "a2a-exposed");
 }
 
-export const CONFIG_DIR = process.env.A2A_CONFIG_DIR || defaultConfigDir();
+export const CONFIG_DIR = path.resolve(process.env.A2A_CONFIG_DIR || defaultConfigDir());
+export const NON_DEFAULT_CONFIG = CONFIG_DIR !== path.resolve(defaultConfigDir());
+/** POSIX shell word; never interpolate paths as shell syntax. */
+export const shellQuote = (value) => /^[A-Za-z0-9_./:@+,-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\\''") + "'";
+export const DEFAULT_CLI_COMMAND = "npx -y a2a-exposed@latest";
+export const CLI_COMMAND = DEFAULT_CLI_COMMAND + (NON_DEFAULT_CONFIG ? ` --config-dir ${shellQuote(CONFIG_DIR)}` : "");
 export const CONFIG_FILE = path.join(CONFIG_DIR, "config.env");
 export const PEERS_FILE = path.join(CONFIG_DIR, "peers.json");
 

package/lib/deploy.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as C from "./config.mjs";
+import { pathNode, pinnedCommand, sameExecutable } from "./runtime.mjs";
 import { CLI, cardUrlProblem, cfErrorCode, die, fetchUpstreamCard, fingerprint, httpJson, randomToken, upstreamAuth, upstreamCardUrlProblem, upstreamUrlProblem } from "./a2a.mjs";
 import { owner, ownerTry } from "./commands.mjs";
 import { readHidden } from "./pair.mjs";
@@ -33,7 +34,9 @@ export const CLAUDE_CODE_NOTE = [
 	"  Then open the new session from the routine's runs and confirm it ran the inbox command without errors.",
 ].join("\n");
 
-const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "generic"];
+export const MAUSBOT_NOTE = "note (mausbot): the first test may only capture a verification sample. Verify and enable the webhook in MausBot, then run wake test again. HTTP 202 proves acceptance; check that the bot reads the inbox and replies.";
+
+const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "mausbot", "generic"];
 // WAKE_ACCESS_*: Cloudflare Access service token for a wake URL behind Access (set by `tunnel create`, or exported
 // by hand for your own Access-protected endpoint)
 export const WAKE_SECRETS = ["WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "WAKE_ACCESS_CLIENT_ID", "WAKE_ACCESS_CLIENT_SECRET"];
@@ -203,7 +206,7 @@ export function deploySecretsFromEnv() {
 
 const csv = (s) => String(s || "").split(",").map((x) => x.trim()).filter(Boolean);
 
-/** Save init/deploy flags. Returns { from, to } when the public URL switches between a custom domain and
+/** Validate init/deploy flags, check Node before writing, then save them. Returns { from, to } when the public URL switches between a custom domain and
  *  workers.dev (or to another custom domain), so the caller can tell the user what changed. */
 function applyFlags(o) {
 	const upd = {};
@@ -273,6 +276,8 @@ function applyFlags(o) {
 	if (upd.A2A_AGENT_SKILLS) {
 		try { if (!Array.isArray(JSON.parse(upd.A2A_AGENT_SKILLS))) throw 0; } catch { die("--agent-skills must be a JSON array of A2A AgentSkill objects"); }
 	}
+	// Report local input errors before Node guidance, but never save or deploy on unsupported Node.
+	checkNode();
 	C.saveConfig(upd);
 	return switched;
 }
@@ -561,13 +566,23 @@ function deployedBase() {
 	return base;
 }
 
+/** Preserve an explicit/saved hint; default hints carry this deployment's config directory. */
+function configureWakeCommand(o) {
+	const saved = C.get("WAKE_CLI_COMMAND");
+	if (o["cli-command"] === undefined && (!saved || saved === C.DEFAULT_CLI_COMMAND) && C.NON_DEFAULT_CONFIG)
+		C.saveConfig({ WAKE_CLI_COMMAND: C.CLI_COMMAND });
+	const fromPath = pathNode();
+	if (!sameExecutable(fromPath, process.execPath))
+		console.error(`Node runtime: ${process.execPath}; PATH node: ${fromPath || "not found"}. Pinned wake command: ${pinnedCommand()}. To save it, pass --cli-command with that command.`);
+}
+
 export async function init(o) {
-	checkNode();
 	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
 	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
 	const dir = workerDir(o);
-	C.saveConfig({ A2A_WORKER_DIR: dir, A2A_WORKER_NAME: workerName() });
+	C.saveConfig({ A2A_WORKER_DIR: dir, A2A_WORKER_NAME: workerName(), A2A_NODE_EXEC_PATH: process.execPath });
+	configureWakeCommand(o);
 	if (workersDevMode()) {
 		if (!WD.LABEL_RE.test(workerName())) die("on workers.dev the --worker-name must be a DNS label (lowercase letters, digits, hyphens)");
 		if (!C.get("A2A_HOSTNAME")) console.error(`note: no --hostname, deploying to https://${workerName()}.<account subdomain>.workers.dev (${WD.DOCS})`);
@@ -702,7 +717,6 @@ export async function upstreamTokenCheck(o, { upstreamChanged = false } = {}) {
 }
 
 export async function deploy(o) {
-	checkNode();
 	if (!C.get("A2A_D1_ID")) die(`no saved deployment; run \`${CLI} init\` first`);
 	// init saves A2A_WORKER_NAME before it creates the D1 database, so a saved D1 without a name is a hand-edited config:
 	// refuse rather than guess, so a redeploy never creates a second Worker next to the one this config deployed.
@@ -710,6 +724,7 @@ export async function deploy(o) {
 		die(`${C.CONFIG_FILE} has a saved deployment (A2A_D1_ID) but no A2A_WORKER_NAME; rerun with --worker-name <the Worker it deployed> (saved for next time)`);
 	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
+	configureWakeCommand(o);
 	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
 	const dir = workerDir(o);
 	if (workersDevMode() && !WD.LABEL_RE.test(workerName())) die("on workers.dev the worker name must be a DNS label (lowercase letters, digits, hyphens)");
@@ -744,7 +759,35 @@ function guardTunnelUrl() {
 	if (host !== th) die(`this deployment wakes through the tunnel https://${th} (tunnel create); unset WAKE_WEBHOOK_URL, or run \`${CLI} tunnel rm\` first`);
 }
 
+/** Delivery diagnostic only: a test wake has no task or execution receipt. */
+export async function checkWake(o, { request = fetch, callOwner = owner } = {}) {
+	if (C.get("WAKE_PRESET") !== "hermes") die("wake check requires the hermes preset; inspect wake preview first, then use wake set --preset hermes");
+	const local = o["local-url"] || `${C.get("A2A_TUNNEL_ORIGIN", "http://127.0.0.1:8644")}${C.get("A2A_TUNNEL_PATH", "/webhooks/a2a-wake")}`;
+	let url;
+	try { url = new URL(local); } catch { die("--local-url must be a loopback HTTP(S) webhook URL"); }
+	if (!["http:", "https:"].includes(url.protocol) || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) || url.username || url.password || url.search || url.hash)
+		die("--local-url must be a loopback HTTP(S) webhook URL without credentials, query or fragment");
+	let status;
+	try {
+		const response = await request(url, { method: "POST", headers: { "content-type": "application/json", "user-agent": "a2a-exposed-cli" },
+			body: JSON.stringify({ event_type: "a2a_wake", kind: "test" }), redirect: "manual", signal: AbortSignal.timeout(10_000) });
+		status = response.status;
+		await response.body?.cancel();
+	} catch { die("unsigned local check could not reach the webhook; start the Hermes gateway and check --local-url"); }
+	const result = { unsigned: { status, refused: status === 401 || status === 403 }, signed: null, receiverExecution: "not-verified" };
+	if (result.unsigned.refused) {
+		const signed = await callOwner("POST", "/owner/wake/test", {});
+		result.signed = { status: Number.isInteger(signed.status) ? signed.status : null, delivered: signed.configured !== false && Number.isInteger(signed.status) && signed.status >= 200 && signed.status < 300 };
+	}
+	console.log(JSON.stringify(result, null, 2));
+	if (!result.unsigned.refused || !result.signed?.delivered) {
+		process.exitCode = 1;
+		console.error(!result.unsigned.refused ? "unsigned local POST must return 401 or 403; check the route's HMAC secret. Signed delivery was skipped." : "signed Worker delivery failed; run wake preview and tunnel status, then retry after secrets propagate");
+	} else console.error("delivery checks passed; receiver execution is not verified. Test wakes create no inbox task; inspect the Hermes job output for execution.");
+}
+
 export async function wake(sub, o) {
+	if (sub === "check") return checkWake(o);
 	if (sub === "fingerprint") {
 		const fp = localFingerprints();
 		if (!Object.values(fp).some(Boolean)) die(`no ${WAKE_SECRETS.join(" / ")} in the environment`);
@@ -769,6 +812,7 @@ export async function wake(sub, o) {
 		console.log(JSON.stringify(r, null, 2));
 		if (!(r.status >= 200 && r.status < 300)) process.exitCode = 1;
 		else if (C.get("WAKE_PRESET") === "claude-code") console.error(CLAUDE_CODE_NOTE);
+		if (r.preset === "mausbot" || C.get("WAKE_PRESET") === "mausbot") console.error(MAUSBOT_NOTE);
 		return;
 	}
 	if (sub === "set") {
@@ -779,6 +823,7 @@ export async function wake(sub, o) {
 		await deploy(o); // wake set = save settings + upload secrets + redeploy, in one step
 		console.error(`wake settings deployed. Next: ${CLI} wake preview, then ${CLI} wake test`);
 		if (C.get("WAKE_PRESET") === "claude-code") console.error(CLAUDE_CODE_NOTE);
+		if (C.get("WAKE_PRESET") === "mausbot") console.error(MAUSBOT_NOTE);
 		return;
 	}
 	if (sub === "unset") {
@@ -796,5 +841,5 @@ export async function wake(sub, o) {
 		if (problems.length) die(`could not remove wake secrets:\n  ${problems.join("\n  ")}`);
 		return console.error("wake secrets removed (wake is now a no-op; use polling)");
 	}
-	die("usage: wake set|unset|test|preview|fingerprint");
+	die("usage: wake set|unset|test|check|preview|fingerprint");
 }

package/lib/hosted.mjs

@@ -36,17 +36,30 @@ function originFor(o = {}) {
 async function request(origin, path, { token = "", method = "GET", body, fetchImpl = fetch } = {}) {
 	let response, data;
 	const discovery = method === "GET" && path === "/api/v1/setup/capabilities";
+	const wakeRequest = /^\/api\/v1\/agents\/[^/]+\/wake(?:\/test)?$/.test(path);
 	try {
 		response = await fetchImpl(`${origin}${path}`, {
 			method, redirect: "error", signal: AbortSignal.timeout(30_000),
 			headers: { accept: "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}), ...(body === undefined ? {} : { "content-type": "application/json" }) },
 			...(body === undefined ? {} : { body: JSON.stringify(body) }),
 		});
-		if (!(discovery && response.status === 404)) data = await response.json();
+		if (!(discovery && response.status === 404)) {
+			try { data = await response.json(); }
+			catch (error) {
+				if (wakeRequest && [401, 403, 404].includes(response.status)) data = {};
+				else throw error;
+			}
+		}
 	} catch { fail("unavailable", "Hosted setup did not answer with JSON. Check the service and try again. Do not repeat a create request until hosted list confirms its result."); }
 	if (discovery && response.status === 404) fail("unsupported", SETUP_UNSUPPORTED);
 	if (!data || typeof data !== "object" || Array.isArray(data)) fail("invalid_response", "The hosted service returned an invalid setup response.");
 	if (!response.ok) {
+		if (wakeRequest && [401, 403, 404].includes(response.status)) {
+			const code = ["invalid_grant", "insufficient_scope"].includes(data.error) ? data.error : `http_${response.status}`;
+			fail(code, response.status === 404
+				? "This service does not expose the hosted wake API for this agent. Check --control-url and the selected agent; use dashboard Wake settings or hosted MCP set_wake. No settings were changed."
+				: "Hosted wake access was refused. Check that A2A_BASE_URL and A2A_OWNER_TOKEN belong to the same agent and service, or approve the required setup scopes. Use dashboard Wake settings or hosted MCP set_wake if needed. No settings were changed.");
+		}
 		if (response.status === 429 && data.error === "too_many_references") {
 			const seconds = retryAfter(response, data);
 			const next = seconds === undefined
@@ -198,8 +211,6 @@ export async function status(o = {}) {
 
 export async function wake(sub, o = {}) {
 	if (!["preview", "test", "set", "prepare", "remove", "unset"].includes(sub)) fail("usage", "Use wake preview|test|set|prepare|remove. List presets with hosted capabilities --json.");
-	if (sub === "set" && C.deploymentKind() === "hosted" && !o.agent)
-		fail("hosted_config", "This is a hosted config. Use dashboard Wake settings or hosted MCP set_wake; the human enters wake secrets on the confirmation page. For scoped CLI setup, run hosted capabilities --json, then hosted list --json to select an explicit --agent NAME before wake set --agent NAME --url URL --preset P --json. No wake settings were changed.");
 	const removing = sub === "remove" || sub === "unset";
  const preparingRemoval = sub === "prepare" && o.clear === true;
  if (o.clear && !preparingRemoval) fail("usage", "Use wake prepare --clear for an MCP removal reference, or wake remove --version N. Run wake preview --json to list the current version.");
@@ -226,7 +237,7 @@ export async function wake(sub, o = {}) {
 	const { origin, token, name } = wakeCredential(o, sub !== "prepare" && !o["reference-file"] && !o["reference-env"]), path = `/api/v1/agents/${encodeURIComponent(name)}/wake`;
 	const current = await request(origin, path, { token });
 	if (!Number.isSafeInteger(current.version)) fail("invalid_response", "The service did not return a valid wake version. Saved settings were not changed.");
-	if (sub === "preview") return { ok: true, code: "preview", next: "Test an explicit draft before saving.", version: current.version, preset: current.preset, configured: Boolean(current.url), key_header: ["hermes", "openbot"].includes(current.preset) ? "" : ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent"].includes(current.preset) ? "Authorization" : current.keyHeader || "Authorization", url: previewUrl(current.url) };
+	if (sub === "preview") return { ok: true, code: "preview", next: "Test an explicit draft before saving.", version: current.version, preset: current.preset, configured: Boolean(current.url), key_header: ["hermes", "openbot"].includes(current.preset) ? "" : ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "mausbot"].includes(current.preset) ? "Authorization" : current.keyHeader || "Authorization", url: previewUrl(current.url) };
  if (removing || preparingRemoval) {
   const version = Number(o.version);
   if (version !== current.version) fail("conflict", "Wake settings changed. Run wake preview --agent NAME --json, review them, then repeat removal with its explicit --version.");
@@ -249,6 +260,7 @@ export async function wake(sub, o = {}) {
 	}
 	const url = o.url || process.env.WAKE_WEBHOOK_URL || current.url;
 	const preset = o.preset || current.preset || "generic";
+	if (!url) fail("wake_unconfigured", "No hosted wake URL is configured. Run hosted capabilities --json to list presets, then wake set --preset P with WAKE_WEBHOOK_URL and protected wake credentials. Alternatively use dashboard Wake settings or hosted MCP set_wake; no settings were changed.");
 	const problem = upstreamUrlProblem(url);
 	if (problem) fail("url", "Pass --url with a public HTTPS webhook URL without credentials. Use polling if no public webhook is available.");
 	const available = await capabilities({ "control-url": origin });

package/lib/main.mjs

@@ -25,6 +25,7 @@ Usage: npx -y a2a-exposed@latest <command> [options]
        --help, -h                    print this help
 
 Setup options: --skip-install skips dependency installation when dependencies already exist.
+Local option and missing-deployment errors appear before Node version guidance; deployment still requires Node 22.18+.
 
 Hosted setup:
   hosted capabilities --json   list setup scopes, wake presets and service capabilities
@@ -73,6 +74,9 @@ npx cf auth login --no-browser; on a VPS where it fails with HTTP 403 before sho
 CLOUDFLARE_API_TOKEN instead: setup skill, Troubleshooting. a2a.exposed hosts the A2A endpoint and is open to everyone
 (https://a2a.exposed/pricing). When to use it:
 https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#hosted-inbox)
+  env [--json]                 print export A2A_CONFIG_DIR=<absolute dir> (no credentials; read-only).
+                                Pin scheduled jobs: mise exec node@22 -- npx -y a2a-exposed@latest
+                                --config-dir DIR inbox; use an absolute mise path outside your shell.
   init [--hostname <host> | --workers-dev [--workers-dev-subdomain NAME]]
        [--agent-name N] [--agent-description D] [--agent-skills JSON]
        [--provider-organization O --provider-url U] [--preset P] [--worker-name W] [--d1-name D]
@@ -136,15 +140,18 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                 --upstream-token-stdin  read UPSTREAM_TOKEN from stdin (hidden prompt on a terminal)
                                 --no-upstream-token  the upstream needs no bearer token: skip that check (saved)
                                 --cli-command  command shown in wake hints (default "npx -y a2a-exposed@latest";
-                                               e.g. "node /path/to/repo/cli/bin/a2a-exposed.mjs")
+                                               e.g. "node /path/to/repo/cli/bin/a2a-exposed.mjs"). Non-default config dirs
+                                               are included in default hints; init saves the Node path and prints
+                                               a pinned command if PATH selects another Node.
                                 --worker-dir   where the Worker project (template copy) lives (default
                                                <config dir>/worker). The config dir is --config-dir / A2A_CONFIG_DIR
   deploy [same flags]           redeploy with saved settings (secrets persist); tag the Worker version as a2a-exposed-<version>
   wake set [--preset P] [--agent-id A] [--key-header H] [--key-prefix X] [--body-template JSON]
            [--cli-command CMD] [--debounce S] [--busy S] [--max-per-hour N]
                                 self-hosted: save wake settings, upload wake secrets from env, and redeploy
-                                hosted config without --agent: stop with dashboard Wake settings / hosted MCP set_wake guidance
-                                hosted CLI: list hosted capabilities --json and hosted list --json, then select --agent NAME
+                                hosted config: use the saved address and owner token to test then save; no deploy
+                                hosted CLI: list hosted capabilities --json for presets; scoped setup selects --agent from hosted list --json
+                                mausbot: HTTPS /hooks/<endpointId> + WAKE_WEBHOOK_KEY Bearer auth from protected env
                                 openbot: human supplies WAKE_HMAC_SECRET via protected env/secret storage, never chat or argv
                                 the Worker refuses unsigned openbot wakes (a webhook key is not a signing secret)
                                 --busy S        seconds a conversation stays busy after a sent wake.
@@ -162,6 +169,9 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                 30 seconds and run it again
   wake fingerprint              fingerprints (first 12 hex of sha256) of WAKE_* exported in this shell
   wake test                     send a test wake now and print the HTTP status
+                                mausbot: verify and enable the first sample in MausBot, then test again
+  wake check [--local-url URL]   Hermes: require unsigned local 401/403, then Worker test 2xx (delivery only)
+                                Defaults to the saved tunnel origin/path; --json prints both checks
   wake unset                    remove wake secrets (fall back to polling)
                                 handler prompts save autonomous, review-all or escalate mode and owner notices;
                                 see docs/receiving-messages.md for setup and the every 6h webhook fallback
@@ -169,7 +179,7 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
 Tunnel (local-only webhooks: OpenClaw gateway, Hermes, ...; needs Zero Trust/Access and a Cloudflare zone
 anywhere on the account: the A2A endpoint itself can be on workers.dev or a custom hostname)
   tunnel create [--tunnel-zone Z | --tunnel-hostname H] [--tunnel-origin URL] [--tunnel-path /p] [--show-token]
-                [--zero-trust-org TEAM]
+                [--zero-trust-org TEAM] [--preset hermes --hermes-route a2a-wake --hmac-secret-stdin]
                                 named Cloudflare Tunnel + proxied DNS + Access app that admits ONE service token;
                                 the Worker sends that token (CF-Access-Client-Id/Secret) on every wake.
                                 Wake hostname: wake-<word>-<word>-<4 hex>.<zone>, on the A2A endpoint hostname's zone, else the
@@ -181,8 +191,11 @@ anywhere on the account: the A2A endpoint itself can be on workers.dev or a cust
                                 The connector machine needs cloudflared installed
                                 (https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/).
                                 Defaults: openclaw-* -> http://127.0.0.1:18789 /hooks/wake|agent, hermes -> :8644
-                                (pass --tunnel-path /webhooks/<name>). Token -> <config dir>/tunnel-token (chmod 600).
+                                /webhooks/a2a-wake (override with --hermes-route NAME). Token -> <config dir>/tunnel-token (chmod 600).
                                 Worker secrets show up in about 15 to 40 seconds. Wait about 30 seconds and check again
+                                Creation prints resource, connector, and optional persistent-service states.
+                                status reports connections and ephemeral/unknown persistence; macOS service install needs an admin terminal.
+  tunnel zones [--json]         list available Cloudflare zones before selecting --tunnel-zone
   tunnel status                 tunnel/Access/Worker state + probes (bare request blocked? connector up?)
                                 A network error says DNS may still be propagating; retry in 30 seconds
   tunnel rm                     delete the DNS record, the tunnel, the Access app, and the service token
@@ -214,7 +227,7 @@ Status
                                 mode (webhook / tunnel / none = no webhook), tunnel state, proxy mode (--upstream):
                                 upstream card, Access credential and upstream bearer configured (separately), the
                                 live upstream check, the last failed peer call, card-leak check; warnings for peer
-                                token variables shadowing saved tokens; and the next step to run.
+                                token variables shadowing saved tokens; Node version/path and wake runtime mismatch; the next step.
                                 Older Workers need deploy (exit 1); npm latest hints use the local update cache.
                                 When GET /owner/mcp reports enabled and the agent card is reachable, prints
                                 \`claude mcp add --transport http a2a-exposed <base URL>/mcp\`.
@@ -260,8 +273,11 @@ Inbox (owner side)
   reply <taskId> (--text T | --stdin) [--state completed|input-required|rejected|failed|working]
         [--artifact] [--artifact-name N] [--force]
                                            delivery waits at most 18 s; identical retries read the first result
+                                           --force changes a terminal task again; peers see every change
+                                           push results show role/host/URL fingerprint; task state saved confirms storage
   history <contextId> [--from PEER] [-n 50] [--json]
-                                           conversation log. --from is one peer (the wake hint includes it)
+                                           conversation log with forced transitions and current state per task.
+                                           --from is one peer (the wake hint includes it)
   contexts                                 recent conversations
   export [--sql]                       JSON dump of this A2A endpoint on stdout (peer-token hashes and
                                        encrypted peer tokens are in the dump; the owner token stays
@@ -360,24 +376,32 @@ Feedback
                                 polling), and hosted or self-hosted. --connection overrides
                                 that detection. Remove tokens from the message and from --logs.
 
-Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
+Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | mausbot | generic
          Clients and how to load them:
          https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#clients
 Config: ${C.CONFIG_FILE}  (override dir with --config-dir DIR or A2A_CONFIG_DIR; env vars override file values)
 Update notice: at most a daily background check of the npm registry; off with A2A_NO_UPDATE_CHECK=1 (or DO_NOT_TRACK=1)`;
 
-const HELP_TUNNEL = `tunnel create|status|rm
+const HELP_TUNNEL = `tunnel create|zones|status|rm
 
 Self-hosted only. Hosted configs use hosted webhook settings or polling. Check status --json first.
 
   tunnel create [--tunnel-zone Z | --tunnel-hostname H] [--tunnel-origin URL] [--tunnel-path /p]
                 [--show-token] [--zero-trust-org TEAM] [--dir DIR | --worker-dir DIR]
+                [--preset hermes --hermes-route a2a-wake --hmac-secret-stdin]
+                                Hermes defaults to :8644/webhooks/a2a-wake. --hermes-route selects another route.
+                                --preset must match the deployed preset (configure with wake set --preset first).
+                                --hmac-secret-stdin reads the existing subscription secret from protected stdin,
+                                never prompts or saves it in config.env. See docs/hermes.md for the receiver recipe.
                                 Named Cloudflare Tunnel, proxied DNS, and an Access app that admits one service token.
                                 The tunnel, the Access app, and the service token are named "a2a-exposed wake <worker>".
                                 The DNS host is wake-<word>-<word>-<4 hex>.<zone> unless --tunnel-hostname is set.
                                 A finished tunnel creates nothing when you run it again. A partial tunnel stops and
                                 asks for tunnel rm. Prints the Access application name and ids, then how to undo it
                                 with tunnel rm. Worker secrets show up in about 15 to 40 seconds. Wait about 30 seconds.
+                                Creation prints resource, connector, and optional persistent-service states.
+                                status reports connections and ephemeral/unknown persistence; macOS service install needs an admin terminal.
+  tunnel zones [--json]         List active zones before choosing --tunnel-zone; no resource changes.
   tunnel status                 Tunnel, Access, and Worker state, plus two probes.
                                 A network error says DNS may still be propagating; retry in 30 seconds.
                                 Warns about Access only when the bare request returns an HTTP status other than 401 or 403.
@@ -412,7 +436,7 @@ const deployOpts = {
 const SPEC = {
 	hosted: { url: S, version: S, "upstream-token-file": S, "upstream-token-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S, name: S, json: B, agent: S, hostname: S, origin: S, path: S, preset: S, "control-url": S, "secret-file": S, "secret-env": S, "secret-from": S, "hermes-home": S, route: S, "token-file": S, "no-run": B },
 	init: { ...deployOpts, ...tunnelOpts, tunnel: B }, deploy: deployOpts,
-	wake: { ...deployOpts, json: B, url: S, "reference-file": S, "reference-env": S, clear: B, version: S, agent: S, "control-url": S, "key-header": S, "key-file": S, "key-env": S, "key-stdin": B, "hmac-secret-file": S, "hmac-secret-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S }, tunnel: tunnelOpts,
+	wake: { ...deployOpts, "local-url": S, json: B, url: S, "reference-file": S, "reference-env": S, clear: B, version: S, agent: S, "control-url": S, "key-header": S, "key-file": S, "key-env": S, "key-stdin": B, "hmac-secret-file": S, "hmac-secret-env": S, "access-client-id-file": S, "access-client-id-env": S, "access-client-secret-file": S, "access-client-secret-env": S }, tunnel: { ...tunnelOpts, preset: S, "hermes-route": S, "hmac-secret-stdin": B, json: B },
 	inbox: { context: S, from: S, all: B, json: B },
 	reply: { text: S, stdin: B, state: { type: "string", default: "completed" }, artifact: B, "artifact-name": { type: "string", default: "response" }, force: B },
 	history: { from: S, n: { type: "string", short: "n", default: "50" }, json: B },
@@ -422,6 +446,7 @@ const SPEC = {
 	send: { to: S, text: S, context: S, task: S, push: B, proto: S },
 	poll: { to: S, proto: S },
 	status: { json: B, agent: S, "control-url": S },
+	env: { json: B },
 	export: { sql: B },
 	upstream: { json: B },
 	connect: { alias: S, name: S, json: B, "no-wait": B, replace: B, force: B, "card-url": S },
@@ -465,7 +490,7 @@ export async function main(argv) {
 		if (extra.length && !ok)
 			throw new CliError("`pair set-password` takes no password argument: it reads the password from the terminal, without echo (never from argv, stdin or the environment). For a one-time web link instead: `pair set-password --web [--ttl MIN] [--json]`");
 	}
-	upd.check(VERSION);
+	if (name !== "env") upd.check(VERSION);
 	let parsed;
 	try {
 		parsed = parseArgs({ args: rest, options: SPEC[name] || {}, allowPositionals: true, strict: true });
@@ -482,6 +507,9 @@ export async function main(argv) {
 	const { values: o, positionals: p } = parsed;
 	if (o["worker-dir"] !== undefined) o.dir = o["worker-dir"];
 	switch (name) {
+		case "env":
+			if (p.length) throw new CliError("env takes no arguments; use --config-dir DIR to select a directory");
+			return console.log(o.json ? JSON.stringify({ A2A_CONFIG_DIR: C.CONFIG_DIR }) : `export A2A_CONFIG_DIR=${C.shellQuote(C.CONFIG_DIR)}`);
 		case "init":
 			if (o.tunnel) tun.preflight(o); // refuse early (hosted preset, missing --tunnel-path) before anything is deployed
 			await dep.init(o);
@@ -491,7 +519,7 @@ export async function main(argv) {
 				throw e;
 			}
 		case "tunnel": {
-			const sub = need(p[0], "tunnel create|status|rm");
+			const sub = need(p[0], "tunnel create|zones|status|rm");
 			if (p.length > 1) throw new CliError(`tunnel ${sub} takes no arguments (${p.slice(1).join(" ")}). Run \`${CLI} tunnel --help\`.`);
 			return tun.tunnel(sub, o);
 		}

package/lib/pair.mjs

@@ -142,7 +142,7 @@ export async function setOidc(o, extra = []) {
 	console.error("The client secret was not written there and was not printed.");
 	if (sawStdin && !(process.env.APPROVAL_OIDC_CLIENT_SECRET || "").trim())
 		console.error(`Export APPROVAL_OIDC_CLIENT_SECRET in the environment you use for deploy. This command did not store it.`);
-	console.error(`The next \`npx -y a2a-exposed@latest deploy\` uploads APPROVAL_OIDC_CLIENT_SECRET only when that variable is set in the environment. A line from --secret-stdin is discarded.`);
+	console.error(`The next \`${CLI} deploy\` uploads APPROVAL_OIDC_CLIENT_SECRET only when that variable is set in the environment. A line from --secret-stdin is discarded.`);
 	console.error("Password approval stays available unless --methods oidc (and only once the issuer, client id, secret and allowlist are all set).");
 }
 
@@ -290,7 +290,7 @@ async function discover(target) {
 			ep = { device: m.data.device_authorization_endpoint, token: m.data.token_endpoint };
 	}
 	if (!ep) die(`${base} does not offer device-flow pairing (no OAuth2 deviceCode flow on its agent card, no ${u.origin}/.well-known/oauth-authorization-server).
-Ask its owner for a token instead: they run \`${CLI} token issue <label>\` and send it to you privately; then \`${CLI} peers add <alias> ${base} --token-stdin\`.`);
+Ask its owner for a token instead: they run \`${C.DEFAULT_CLI_COMMAND} token issue <label>\` and send it to you privately; then \`${CLI} peers add <alias> ${base} --token-stdin\`.`);
 	for (const x of [ep.device, ep.token]) {
 		const e = new URL(x);
 		if (e.protocol !== "https:" && !["127.0.0.1", "localhost", "[::1]"].includes(e.hostname)) die(`refusing a non-https pairing endpoint: ${x}`);
@@ -378,7 +378,7 @@ A different agent at the same URL? Pass another --alias.`);
 		const mins = Math.round((st.expiresAt - Date.now()) / 60000);
 		const swap = !st.replacing ? "" : st.replacesLabel
 			? ` On approval the peer replaces our token "${st.replacesLabel}" (the old one stops working).`
-			: ` This peer does not swap tokens: our old token${oldLabel ? ` (label "${oldLabel}" on its side)` : ""} stays active until its owner revokes it${oldLabel ? ` (\`${CLI} token revoke ${oldLabel}\`)` : ""}; tell them.`;
+			: ` This peer does not swap tokens: our old token${oldLabel ? ` (label "${oldLabel}" on its side)` : ""} stays active until its owner revokes it${oldLabel ? ` (\`${C.DEFAULT_CLI_COMMAND} token revoke ${oldLabel}\`)` : ""}; tell them.`;
 		emit({ status: "authorization_pending", alias, user_code: st.userCode, verification_uri: st.verificationUri, verification_uri_complete: st.verificationUriComplete, expires_in: Math.round((st.expiresAt - Date.now()) / 1000), interval: st.interval,
 			...(st.replacing ? { replaces_label: st.replacesLabel } : {}),
 			instructions: `Show the code and the link to your human. They confirm the code with the owner of ${peerName}, who approves it on that page.${swap}` },
@@ -399,7 +399,7 @@ Show this code and link to your human. They confirm the code with the owner of $
 		dropState(alias);
 		const orphan = st.replacing && !r.data.replaced ? (st.replacesLabel || oldLabel || null) : null;
 		const note = r.data.replaced ? ` It replaced our previous token there (label "${label}").`
-			: st.replacing ? ` Our previous token${orphan ? ` ("${orphan}")` : ""} is still active on the peer until its owner revokes it${orphan ? `: \`${CLI} token revoke ${orphan}\`` : ""}.` : "";
+			: st.replacing ? ` Our previous token${orphan ? ` ("${orphan}")` : ""} is still active on the peer until its owner revokes it${orphan ? `: \`${C.DEFAULT_CLI_COMMAND} token revoke ${orphan}\`` : ""}.` : "";
 		emit({ status: "connected", alias, url: base, token_env: tokenEnv, ...(label ? { peer_label: label } : {}), ...(st.replacing ? { replaced: !!r.data.replaced } : {}), ...(envOverrides ? { env_overrides_token: true } : {}) },
 			`connected: peer "${alias}" -> ${base}${label ? ` (we are "${label}" there)` : ""}; token stored in ${C.CONFIG_FILE} as ${tokenEnv} (not printed).${note}
 Send a message: ${CLI} send --to ${alias} --text "..."`);

package/lib/runtime.mjs

@@ -0,0 +1,54 @@
+// Runtime diagnostics only: inspect paths, never execute a saved wake command.
+import fs from "node:fs";
+import path from "node:path";
+import * as C from "./config.mjs";
+
+const canonical = (file) => { try { return fs.realpathSync(file); } catch { return path.resolve(file); } };
+export const sameExecutable = (a, b) => !!a && !!b && canonical(a) === canonical(b);
+
+export function pathNode(env = process.env) {
+	for (const dir of (env.PATH || "").split(path.delimiter)) {
+		const file = path.resolve(dir || ".", process.platform === "win32" ? "node.exe" : "node");
+		try {
+			fs.accessSync(file, fs.constants.X_OK);
+			if (fs.statSync(file).isFile()) return file;
+		} catch { /* try the next PATH entry */ }
+	}
+	return null;
+}
+
+/** Pin env-based Node shebangs (including npx and its children) to this runtime. */
+export function pinnedCommand(execPath = process.execPath) {
+	return `env PATH=${C.shellQuote(path.dirname(execPath))}:"$PATH" ${C.CLI_COMMAND}`;
+}
+
+// Read the first shell word without evaluating expansions, substitutions or commands.
+function firstWord(text) {
+	text = text.trim();
+	let word = "", quote = "";
+	for (let i = 0; i < text.length; i++) {
+		const c = text[i];
+		if (quote) {
+			if (c === quote) quote = "";
+			else if (c === "\\" && quote === '"') word += text[++i] || "";
+			else word += c;
+		} else if (c === "'" || c === '"') quote = c;
+		else if (/\s/.test(c)) break;
+		else if (c === "\\") word += text[++i] || "";
+		else word += c;
+	}
+	return quote ? "" : word;
+}
+
+export function runtimeInfo({ execPath = process.execPath, node = process.versions.node,
+	pathExecPath = pathNode(), initExecPath = C.get("A2A_NODE_EXEC_PATH"), command = C.get("WAKE_CLI_COMMAND", C.CLI_COMMAND) } = {}) {
+	const first = firstWord(command);
+	let wakeExecPath = null;
+	if (command === pinnedCommand(execPath)) wakeExecPath = execPath;
+	else if (initExecPath && command === pinnedCommand(initExecPath)) wakeExecPath = initExecPath;
+	else if (/^(node|npx|a2a-exposed)(\.exe|\.cmd)?$/.test(first)) wakeExecPath = pathExecPath;
+	else if (/^node(\.exe)?$/.test(path.basename(first)) && path.isAbsolute(first)) wakeExecPath = first;
+	const warning = wakeExecPath && !sameExecutable(wakeExecPath, execPath)
+		? `WAKE_CLI_COMMAND selects a different Node (${wakeExecPath}); this process uses ${execPath}. Pin the wake runtime with --cli-command (see env --help).` : null;
+	return { node, execPath, initExecPath: initExecPath || null, pathExecPath, wakeExecPath, warning };
+}