agent-rooms 0.11.0 → 0.12.0

package/dist/commands/init.js

@@ -5,7 +5,9 @@ import { platform } from "node:os";
 import { listenerInventory, pairPoll, pairStart } from "../api.js";
 import { loadConfig, saveConfig, upsertBinding } from "../config.js";
 import { detectInstalledHosts, getAdapter } from "../hosts.js";
-import { installBundledSkill } from "../skill.js";
+import { installNativePlugin, isNativePluginHost } from "../plugins.js";
+import { installHostedSkill } from "../skill.js";
+import { resolveSpawnCommand } from "../spawn.js";
 import { log, out } from "../log.js";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function initCommand(args) {
@@ -21,7 +23,7 @@ export async function initCommand(args) {
         out("Usage: agent-rooms init --agent <BRNL-AGT-...> (--room <room_id> ... | --all-rooms)");
         out("       [--include-cross-owner] [--api-base <url>] [--host claude_code|codex|openclaw|hermes] [--workspace <path>] [--no-connector]");
         out("");
-        out("--all-rooms binds every room this agent is already in (your own rooms; add");
+        out("--all-rooms follows this agent's current and future rooms (your own rooms; add");
         out("--include-cross-owner to also auto-wake in cross-owner rooms). Find ids in the app.");
         return 1;
     }
@@ -43,29 +45,47 @@ export async function initCommand(args) {
             log.warn(`Agent ${agent} isn't in any ${includeCross ? "" : "same-owner "}rooms yet — nothing to bind. Add it to a room in the app, then re-run.`);
             return 1;
         }
-        log.info(`--all-rooms: binding ${rooms.length} room(s) this agent is already in.`);
+        log.info(`--all-rooms: following live membership (currently ${rooms.length} room(s)).`);
+    }
+    const explicitHost = args.host;
+    const host = resolveHost(explicitHost);
+    if (explicitHost && !host) {
+        log.error(`Unknown or non-wakeable host '${explicitHost}'. Expected claude_code, codex, openclaw, hermes, gemini, or cursor.`);
+        return 1;
     }
-    const host = resolveHost(args.host);
     if (!host) {
         log.warn("No supported host CLI (claude / codex / openclaw / hermes) detected on PATH. Recording the binding anyway; install one before `watch`.");
     }
     const hostName = args.host || host?.name || "unknown";
     if (host && !args["no-connector"]) {
-        registerConnector(host, apiBase);
+        if (!(await installHostIntegration(host, apiBase)))
+            return 1;
     }
     else if (!args["no-connector"]) {
         out("");
-        out(`To connect manually, add this remote MCP server to your client: ${apiBase}/mcp`);
-        out(`  Claude Code:  claude mcp add --transport http --scope user agent-rooms ${apiBase}/mcp`);
-        out(`  Codex:        codex mcp add agent-rooms --url ${apiBase}/mcp --bearer-token-env-var AGENT_ROOMS_TOKEN`);
+        out("To connect manually, use the exact resource for your host:");
+        out(`  Claude Code:  claude mcp add --transport http --scope user agent-rooms ${apiBase}/mcp/claude`);
+        out(`  Codex:        codex mcp add agent-rooms --url ${apiBase}/mcp/codex --bearer-token-env-var AGENT_ROOMS_TOKEN`);
+        out(`  OpenClaw:     openclaw mcp add agent-rooms --transport streamable-http --url ${apiBase}/mcp/openclaw --auth oauth`);
+        out(`  Hermes:       hermes mcp add agent-rooms --url ${apiBase}/mcp/hermes --auth oauth`);
     }
     if (host && !args["no-skill"]) {
-        installSkill(host);
+        if (!(await installSkill(host)))
+            return 1;
     }
-    const binding = { agent, workspace, host: hostName, rooms };
+    const binding = {
+        agent,
+        workspace,
+        host: hostName,
+        rooms,
+        roomScope: allRooms ? "all" : "exact",
+        includeCrossOwner: allRooms ? includeCross : undefined
+    };
     const next = upsertBinding(config, binding);
     saveConfig(next);
-    log.info(`Bound agent ${agent} in ${workspace} -> rooms [${rooms.join(", ")}] (host ${hostName}).`);
+    log.info(allRooms
+        ? `Bound agent ${agent} in ${workspace} -> all ${includeCross ? "member" : "same-owner"} rooms (currently [${rooms.join(", ")}]) (host ${hostName}).`
+        : `Bound agent ${agent} in ${workspace} -> rooms [${rooms.join(", ")}] (host ${hostName}).`);
     out("");
     out("Done. Two ways to receive mentions:");
     out("  - Tier 0 (already on): your agent pulls mentions via the MCP connector during its own runs.");
@@ -156,35 +176,87 @@ function resolveHost(explicit) {
     }
     return null;
 }
-export function registerConnector(host, apiBase) {
-    const { command, args } = host.buildMcpAdd(apiBase);
-    log.info(`Registering MCP connector with ${host.name}: ${command} ${args.join(" ")}`);
-    const result = spawnSync(command, args, { encoding: "utf8", shell: process.platform === "win32" });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+export function registerConnector(host, apiBase, runner) {
+    const run = runner ?? ((command, args) => {
+        const resolved = resolveSpawnCommand(command, args);
+        return spawnSync(resolved.command, resolved.args, {
+            encoding: "utf8",
+            shell: false,
+            windowsHide: true
+        });
+    });
+    const add = host.buildMcpAdd(apiBase);
+    log.info(`Registering MCP connector with ${host.name}: ${add.command} ${add.args.join(" ")}`);
+    let result = run(add.command, add.args);
+    let output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
     if (output)
         out(output);
     if (result.status === 0) {
         log.info(`Connector registered with ${host.name}.`);
+        return true;
     }
     else if (/already (exists|configured|registered)/i.test(output)) {
-        log.info(`Connector already present in ${host.name} config - leaving it as-is.`);
+        // Never trust an existing connector by name: older releases used shared
+        // routes/auth modes. Replace the Agent Rooms-owned entry idempotently so an
+        // upgrade cannot preserve stale wiring.
+        const remove = host.buildMcpRemove();
+        log.info(`Reconciling existing ${host.name} connector to the exact host resource.`);
+        const removed = run(remove.command, remove.args);
+        if (removed.status !== 0) {
+            const removeOutput = `${removed.stdout ?? ""}${removed.stderr ?? ""}`.trim();
+            log.warn(`Could not replace stale connector${removeOutput ? `: ${removeOutput}` : "."}`);
+            return false;
+        }
+        result = run(add.command, add.args);
+        output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+        if (output)
+            out(output);
+        if (result.status === 0) {
+            log.info(`Connector reconciled with ${host.name}.`);
+            return true;
+        }
+        log.warn(`Could not re-register the exact connector (exit ${result.status ?? "?"}).`);
+        return false;
     }
     else {
-        log.warn(`Could not auto-register the connector (exit ${result.status ?? "?"}). Add it manually: ${apiBase}/mcp`);
+        const resourceHost = host.name === "claude_code" ? "claude" : host.name;
+        log.warn(`Could not auto-register the connector (exit ${result.status ?? "?"}). Re-run init after checking ${apiBase}/mcp/${resourceHost}.`);
+        return false;
+    }
+}
+/** Install the native wrapper before enabling its connector. Claude/Codex MCP
+ * wiring is loaded from the plugin itself; OpenClaw/Hermes also reconcile their
+ * native MCP registries because those plugin APIs do not ingest MCP manifests. */
+export async function installHostIntegration(host, apiBase) {
+    if (isNativePluginHost(host.name)) {
+        const result = await installNativePlugin(host.name, apiBase);
+        if (!result.ok) {
+            log.error(`${host.name} integration disabled: ${result.message}`);
+            return false;
+        }
+        log.info(result.message);
+        if (host.name === "claude_code" || host.name === "codex")
+            return true;
     }
+    return registerConnector(host, apiBase);
 }
-export function installSkill(host) {
+export async function installSkill(host) {
     try {
-        const result = installBundledSkill(host);
+        // Spec 35 §13 (T13.3): the hosted URL is the only runtime source. Offline
+        // installation fails explicitly instead of reading a bundled fallback.
+        const result = await installHostedSkill(host);
         if (result.installed) {
             log.info(`${result.message} -> ${result.destination}`);
+            return true;
         }
         else {
-            out(`  (${result.message})`);
+            log.error(result.message);
+            return false;
         }
     }
     catch (err) {
-        log.warn(`Could not install the skill for ${host.name}: ${err.message}`);
+        log.error(`Could not install the skill for ${host.name}: ${err.message}`);
+        return false;
     }
 }
 function asArray(value) {

package/dist/commands/start.js

@@ -1,12 +1,12 @@
 // `agent-rooms start` - the one-command path. Pairs the device once (if needed),
-// binds every agent you own to the rooms it's ALREADY in, and runs the shared
+// binds every agent you own to its live room membership, and runs the shared
 // listener. Same-owner rooms by default; --include-cross-owner also auto-wakes in
 // cross-owner rooms (untrusted mentions, so it's opt-in). --agent <plate> limits
 // to one agent. Pull-based agents (web chat, etc.) are skipped — they don't wake.
 import { listenerInventory } from "../api.js";
 import { loadConfig, saveConfig, upsertBinding } from "../config.js";
 import { getAdapter } from "../hosts.js";
-import { installSkill, pairDevice, registerConnector } from "./init.js";
+import { installHostIntegration, installSkill, pairDevice } from "./init.js";
 import { watchCommand } from "./watch.js";
 import { log, out } from "../log.js";
 export async function startCommand(args) {
@@ -52,15 +52,22 @@ export async function startCommand(args) {
             continue;
         }
         if (!hostsSetup.has(adapter.name)) {
-            if (!noConnector)
-                registerConnector(adapter, apiBase);
-            if (!noSkill)
-                installSkill(adapter);
+            if (!noConnector && !(await installHostIntegration(adapter, apiBase)))
+                return 1;
+            if (!noSkill && !(await installSkill(adapter)))
+                return 1;
             hostsSetup.add(adapter.name);
         }
-        next = upsertBinding(next, { agent: a.plate, workspace, host: adapter.name, rooms: roomIds });
+        next = upsertBinding(next, {
+            agent: a.plate,
+            workspace,
+            host: adapter.name,
+            rooms: roomIds,
+            roomScope: "all",
+            includeCrossOwner: includeCross
+        });
         bound += 1;
-        log.info(`Bound ${a.name} (${a.plate}) -> ${roomIds.length} room(s) [host ${adapter.name}].`);
+        log.info(`Bound ${a.name} (${a.plate}) -> all ${includeCross ? "member" : "same-owner"} rooms (currently ${roomIds.length}) [host ${adapter.name}].`);
     }
     saveConfig(next);
     if (bound === 0) {

package/dist/commands/status.js

@@ -3,6 +3,9 @@
 // the paired device, whether the singleton watcher is alive, and every bound agent
 // (host · rooms · workspace), so a missing or paused binding is obvious.
 import { loadConfig, runningWatch } from "../config.js";
+import { listenerDiagnostics } from "../api.js";
+import { getAdapter, isSkillInstalled } from "../hosts.js";
+import { isNativePluginHost, pluginCompatibility, readNativePluginManifest } from "../plugins.js";
 import { out } from "../log.js";
 export async function statusCommand() {
     const config = loadConfig();
@@ -24,6 +27,32 @@ export async function statusCommand() {
             out(`    - ${b.agent}  host=${b.host}  rooms=[${b.rooms.join(", ")}]  cwd=${b.workspace}${tag}`);
         }
     }
+    out(`  reports:  ${(config.pendingReports ?? []).length} queued session report(s)`);
+    for (const host of [...new Set(config.bindings.map((binding) => binding.host))]) {
+        const adapter = getAdapter(host);
+        const skill = adapter ? (isSkillInstalled(adapter) ? "hosted skill present" : "hosted skill missing") : "no skill adapter";
+        if (isNativePluginHost(host)) {
+            const plugin = readNativePluginManifest(host);
+            const gate = pluginCompatibility(host);
+            out(`  ${host}: plugin=${plugin ? `v${plugin.version}` : "missing"} compatibility=${gate.ok ? "OK" : "DISABLED"} skill=${skill}`);
+            if (!gate.ok)
+                out(`    recovery: ${gate.message}`);
+        }
+        else {
+            out(`  ${host}: direct integration; ${skill}`);
+        }
+    }
+    if (config.device) {
+        try {
+            const diagnostic = await listenerDiagnostics(config.apiBase, config.device.token);
+            out(`  registry: reachable (${diagnostic.registry.active} active session(s))`);
+            out(`  queue:    reachable (${diagnostic.queue.pending} pending, ${diagnostic.queue.in_flight} in flight)`);
+            out(`  protocol: v${diagnostic.protocol_version}; server requires listener >= ${diagnostic.min_listener_version}`);
+        }
+        catch (error) {
+            out(`  registry: UNREACHABLE (${error.message})`);
+        }
+    }
     if (!watch) {
         out("");
         out("No watcher running — wakes won't fire until you run:  agent-rooms watch");

package/dist/commands/uninstall.js

@@ -7,10 +7,30 @@ import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { listenerPost } from "../api.js";
 import { configFilePath, loadConfig, removeConfig } from "../config.js";
-import { claudeAdapter, codexAdapter, getAdapter } from "../hosts.js";
+import { claudeAdapter, codexAdapter, openclawAdapter, hermesAdapter, getAdapter } from "../hosts.js";
+import { isNativePluginHost, removeOwnedNativePluginState } from "../plugins.js";
+import { removeHostedSkill } from "../skill.js";
+import { resolveSpawnCommand } from "../spawn.js";
 import { log, out } from "../log.js";
+function defaultRunCommand(command, args) {
+    try {
+        const resolved = resolveSpawnCommand(command, args);
+        return spawnSync(resolved.command, resolved.args, {
+            cwd: process.cwd(), encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true
+        });
+    }
+    catch (error) {
+        return { status: null, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}
+const DEFAULT_DEPS = {
+    runCommand: defaultRunCommand,
+    removeOwnedNativePluginState,
+    removeHostedSkill,
+    removeConfig
+};
 const HELP = `Usage: agent-rooms uninstall [--yes] [--dry-run]
-                              [--host all|claude_code|codex|none]
+                              [--host all|claude_code|codex|openclaw|hermes|none]
                               [--keep-config] [--local-only] [--no-connector]
 
 Removes the Agent Rooms listener setup from this machine.
@@ -23,7 +43,8 @@ Options:
   --local-only    skip remote device revocation
   --no-connector  skip host MCP connector removal
 `;
-export async function uninstallCommand(args) {
+export async function uninstallCommand(args, overrides = {}) {
+    const deps = { ...DEFAULT_DEPS, ...overrides };
     if (args.help || args.h || args["--help"]) {
         out(HELP);
         return 0;
@@ -74,11 +95,22 @@ export async function uninstallCommand(args) {
     if (config.device && !localOnly) {
         await revokeRemoteDevice(config.apiBase, config.device.token);
     }
+    const failedHosts = [];
     for (const host of hosts) {
-        unregisterConnector(host);
+        const pluginRemoved = unregisterNativePlugin(host, deps.runCommand);
+        const connectorRemoved = unregisterConnector(host, deps.runCommand);
+        if (!pluginRemoved || !connectorRemoved) {
+            failedHosts.push(host.name);
+            log.warn(`Preserving ${host.name} owned state so uninstall can be retried safely.`);
+            continue;
+        }
+        if (isNativePluginHost(host.name))
+            deps.removeOwnedNativePluginState(host.name);
+        if (deps.removeHostedSkill(host))
+            log.info(`Removed the Agent Rooms hosted skill from ${host.name}.`);
     }
-    if (!keepConfig) {
-        const removed = removeConfig();
+    if (!keepConfig && failedHosts.length === 0) {
+        const removed = deps.removeConfig();
         if (removed) {
             log.info("Deleted local Agent Rooms config.");
         }
@@ -86,6 +118,11 @@ export async function uninstallCommand(args) {
             log.warn("No local Agent Rooms config file was found.");
         }
     }
+    if (failedHosts.length > 0) {
+        out("");
+        log.error(`Uninstall incomplete for: ${failedHosts.join(", ")}. Config and failed host state were kept for retry.`);
+        return 1;
+    }
     out("");
     out("Uninstall complete.");
     out("If you installed the package globally, also run: npm uninstall -g agent-rooms");
@@ -101,28 +138,68 @@ async function revokeRemoteDevice(apiBase, token) {
         log.warn(`Could not revoke the paired device remotely (${message}). Revoke it from the Agent Rooms app if it still appears there.`);
     }
 }
-function unregisterConnector(host) {
+function unregisterConnector(host, runner) {
     const { command, args } = host.buildMcpRemove();
     log.info(`Removing MCP connector from ${host.name}: ${command} ${args.join(" ")}`);
-    const result = spawnSync(command, args, {
-        cwd: process.cwd(),
-        encoding: "utf8",
-        stdio: "pipe",
-        shell: process.platform === "win32"
-    });
+    let result;
+    try {
+        result = runner(command, args);
+    }
+    catch (error) {
+        result = { status: null, error: error instanceof Error ? error : new Error(String(error)) };
+    }
     if (result.status === 0) {
         log.info(`Connector removed from ${host.name}.`);
-        return;
+        return true;
     }
     const stderr = String(result.stderr || result.error?.message || "").trim();
+    if (/not (?:installed|found|configured)|does not exist|unknown server/i.test(stderr))
+        return true;
     log.warn(`Could not remove connector from ${host.name}${stderr ? `: ${stderr}` : "."}`);
+    return false;
+}
+export function nativePluginRemovalCommands(host) {
+    if (!isNativePluginHost(host.name))
+        return [];
+    return host.name === "claude_code"
+        ? [
+            { command: "claude", args: ["plugin", "uninstall", "agent-rooms@agent-rooms", "--scope", "user", "--yes"] },
+            { command: "claude", args: ["plugin", "marketplace", "remove", "agent-rooms", "--scope", "user"] }
+        ]
+        : host.name === "codex"
+            ? [
+                { command: "codex", args: ["plugin", "remove", "agent-rooms@agent-rooms"] },
+                { command: "codex", args: ["plugin", "marketplace", "remove", "agent-rooms"] }
+            ]
+            : host.name === "openclaw"
+                ? [{ command: "openclaw", args: ["plugins", "uninstall", "agent-rooms", "--force"] }]
+                : [{ command: "hermes", args: ["plugins", "remove", "agent-rooms"] }];
+}
+function unregisterNativePlugin(host, runner) {
+    const commands = nativePluginRemovalCommands(host) ?? [];
+    let ok = true;
+    for (const command of commands) {
+        let result;
+        try {
+            result = runner(command.command, command.args);
+        }
+        catch (error) {
+            result = { status: null, error: error instanceof Error ? error : new Error(String(error)) };
+        }
+        const output = `${result.stdout ?? ""}${result.stderr ?? ""}${result.error?.message ?? ""}`.trim();
+        if (result.status === 0 || /not (?:installed|found|configured)|unknown marketplace/i.test(output))
+            continue;
+        ok = false;
+        log.warn(`Could not remove ${host.name} native plugin${output ? `: ${output}` : "."}`);
+    }
+    return ok;
 }
 function resolveHosts(value) {
     const raw = normalizeHost(String(value || "all"));
     if (raw === "none")
         return [];
     if (raw === "all")
-        return [claudeAdapter, codexAdapter];
+        return [claudeAdapter, codexAdapter, openclawAdapter, hermesAdapter];
     const adapter = getAdapter(raw);
     return adapter ? [adapter] : null;
 }

package/dist/commands/watch.js

@@ -1,7 +1,8 @@
 // `agent-rooms watch` - run the listener so idle local agents wake on mentions.
-import { clearWatchPid, loadConfig, runningWatch, writeWatchPid } from "../config.js";
+import { acquireWatchPid, clearWatchPid, loadConfig } from "../config.js";
 import { dryRunLines, ListenerRuntime } from "../listener.js";
 import { log, out } from "../log.js";
+import { isNativePluginHost, nativePluginRuntimeGate } from "../plugins.js";
 export async function watchCommand(args) {
     const config = loadConfig();
     const apiBase = args["api-base"] || config.apiBase;
@@ -12,11 +13,35 @@ export async function watchCommand(args) {
             out(line);
         return 0;
     }
+    // §14: each native integration is gated independently. A host that is not
+    // usable on this machine (e.g. a WSL-only host bound from Windows) is disabled
+    // on its own — it must not ground the hosts that ARE usable. Only bindings the
+    // listener would actually serve are gated, so a paused agent cannot block start.
+    const gatedHosts = [
+        ...new Set(config.bindings
+            .filter((binding) => !config.pausedAgents.includes(binding.agent))
+            .map((binding) => binding.host))
+    ];
+    const disabledHosts = [];
+    for (const host of gatedHosts) {
+        if (!isNativePluginHost(host))
+            continue;
+        const gate = nativePluginRuntimeGate(host, apiBase);
+        if (!gate.ok) {
+            log.warn(`${gate.message ?? `${host} integration is disabled.`} Disabling ${host}; other hosts keep running.`);
+            disabledHosts.push(host);
+        }
+    }
+    if (gatedHosts.length > 0 && disabledHosts.length === gatedHosts.length) {
+        log.error("Every bound host's native integration is unavailable on this machine. Fix at least one, then re-run.");
+        return 1;
+    }
     // Singleton: one shared watcher per machine serves EVERY tool (all bindings) over
     // one device + one connection. If one is already running, don't start a second —
     // it hot-reloads any newly-added agent on its own.
-    const existing = runningWatch();
-    if (existing) {
+    const lock = acquireWatchPid();
+    if (!lock.acquired) {
+        const existing = lock.watch;
         out(`A listener is already running on this machine (pid ${existing.pid}).`);
         out("It's the single shared watcher for all your tools and will pick up this");
         out("agent automatically (hot reload). Check it with:  agent-rooms status");
@@ -26,6 +51,7 @@ export async function watchCommand(args) {
     const runtime = new ListenerRuntime({
         apiBase,
         maxTurns,
+        disabledHosts,
         onEvent(event) {
             if (event.level === "error")
                 log.error(event.message);
@@ -39,13 +65,13 @@ export async function watchCommand(args) {
         await runtime.start();
     }
     catch (error) {
+        clearWatchPid(process.pid);
         log.error(error.message);
         return 1;
     }
     // Claim the singleton lock now that we're up; clear it however we exit so a crash
     // never leaves a stale lock that blocks the next watch.
-    writeWatchPid();
-    process.once("exit", clearWatchPid);
+    process.once("exit", () => clearWatchPid(process.pid));
     log.info("Listener running. Press Ctrl+C to stop.");
     await new Promise((resolve) => {
         let shuttingDown = false;
@@ -55,7 +81,7 @@ export async function watchCommand(args) {
             shuttingDown = true;
             log.info("Shutting down...");
             void runtime.stop().finally(() => {
-                clearWatchPid();
+                clearWatchPid(process.pid);
                 resolve();
             });
         };

package/dist/config.js

@@ -42,9 +42,29 @@ export function loadConfig() {
         hostTokens: raw.hostTokens ?? {},
         sessions: contaminated ? {} : (raw.sessions ?? {}),
         sessionsMeta: contaminated ? {} : (raw.sessionsMeta ?? {}),
-        sessionSchema: SESSION_SCHEMA
+        sessionSchema: SESSION_SCHEMA,
+        serverKey: raw.serverKey,
+        serverKeys: raw.serverKeys ?? (raw.serverKey ? [raw.serverKey] : []),
+        pendingReports: raw.pendingReports ?? [],
+        handledWakes: raw.handledWakes ?? {}
     };
 }
+const HANDLED_WAKE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+const PENDING_REPORT_CAP = 200;
+/** Spec 35 §4: remember a handled wake id (dedup for re-deliveries). */
+export function recordHandledWake(config, wakeId, now = Date.now()) {
+    const handledWakes = { ...(config.handledWakes ?? {}), [wakeId]: now };
+    for (const [id, at] of Object.entries(handledWakes)) {
+        if (now - at > HANDLED_WAKE_MAX_AGE_MS)
+            delete handledWakes[id];
+    }
+    return { ...config, handledWakes };
+}
+/** Spec 35 §2: queue a session report that could not reach the server. */
+export function queuePendingReport(config, report) {
+    const pendingReports = [...(config.pendingReports ?? []), report].slice(-PENDING_REPORT_CAP);
+    return { ...config, pendingReports };
+}
 /** Spec 19: record a task session id + its timestamp, then evict stale/excess
  *  sessions. Returns a new Config (does not write to disk). */
 export function recordSession(config, key, sessionId, now = Date.now()) {
@@ -163,8 +183,41 @@ export function writeWatchPid(pid = process.pid) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify({ pid, startedAt: Date.now() })}\n`);
 }
-export function clearWatchPid() {
+/** Atomically acquire the per-home singleton before any network connection or
+ * runtime setup. `wx` is the cross-platform O_EXCL primitive: concurrent watch
+ * processes cannot both pass it. A stale owner is removed and acquisition is
+ * retried once. */
+export function acquireWatchPid(pid = process.pid) {
+    const path = watchPidPath();
+    mkdirSync(dirname(path), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const watch = { pid, startedAt: Date.now() };
+        try {
+            writeFileSync(path, `${JSON.stringify(watch)}\n`, { flag: "wx", mode: 0o600 });
+            return { acquired: true, watch };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = readWatchPid();
+            if (existing && isProcessAlive(existing.pid))
+                return { acquired: false, watch: existing };
+            try {
+                rmSync(path, { force: true });
+            }
+            catch { /* another contender may own cleanup */ }
+        }
+    }
+    const existing = readWatchPid();
+    return { acquired: false, watch: existing ?? { pid: 0, startedAt: 0 } };
+}
+export function clearWatchPid(expectedPid) {
     try {
+        if (expectedPid !== undefined) {
+            const current = readWatchPid();
+            if (!current || current.pid !== expectedPid)
+                return;
+        }
         rmSync(watchPidPath(), { force: true });
     }
     catch {

package/dist/envelope.js

@@ -0,0 +1,83 @@
+// Spec 35 §3/§10 — the signed wake envelope, listener side. Mirrors
+// backend/contracts/envelope.ts (this package is standalone; shapes are the
+// wire contract). The listener NEVER trusts its own input: only server-signed
+// envelopes are acted on. Verification uses the server's Ed25519 public key,
+// pinned from /.well-known/jwks.json at pairing and refreshed on demand.
+import { createPublicKey, verify as nodeVerify } from "node:crypto";
+import { Buffer } from "node:buffer";
+const WAKE_SIGNATURE_DOMAIN = Buffer.from("agent-rooms:wake-envelope:v2\0", "utf8");
+const wakeSigningBytes = (serializedEnvelope) => Buffer.concat([WAKE_SIGNATURE_DOMAIN, Buffer.from(serializedEnvelope, "utf8")]);
+export const WAKE_PROTOCOL_VERSION = 2;
+export function publicKeyFromJwk(jwk) {
+    return createPublicKey({ key: jwk, format: "jwk" });
+}
+function base64UrlToBytes(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+    return Buffer.from(padded, "base64");
+}
+/** How stale a signed envelope may be before it's rejected as a replay (§16 C7).
+ * Generous vs. normal dispatch latency; a re-dispatched wake carries a FRESH
+ * issued_at per attempt, so legitimate re-dispatches always pass. */
+export const ENVELOPE_MAX_AGE_MS = 10 * 60 * 1000;
+/** Clock-skew tolerance for a future-dated issued_at. */
+export const ENVELOPE_MAX_FUTURE_MS = 2 * 60 * 1000;
+/** Verify a wake2 frame and parse its envelope. Returns null on ANY failure
+ * (bad signature, tampered bytes, malformed JSON, wrong version, or a stale/
+ * future-dated envelope) — the caller drops and reports, never trusts. The
+ * signature covers the exact transmitted bytes of `e`.
+ *
+ * Freshness (§16 C7 red-team): signature verification blocks FORGERY, not
+ * REPLAY of a genuine envelope. issued_at is inside the signed bytes, so it
+ * can't be altered; rejecting a stale issued_at closes the replay window that
+ * the wake_id dedup alone (only handled ids) doesn't cover. `now` is injectable
+ * for tests. */
+export function verifyWakeFrame(publicKey, frame, opts = {}) {
+    try {
+        const valid = nodeVerify(null, wakeSigningBytes(frame.e), publicKey, base64UrlToBytes(frame.sig));
+        if (!valid)
+            return null;
+        const envelope = JSON.parse(frame.e);
+        if (envelope.protocol_version !== WAKE_PROTOCOL_VERSION)
+            return null;
+        if (!envelope.wake_id || !envelope.room_id || !envelope.target)
+            return null;
+        const now = opts.now ?? Date.now();
+        const issued = typeof envelope.issued_at === "number" ? envelope.issued_at : 0;
+        if (!issued)
+            return null; // v2 always stamps issued_at; a missing one is suspect
+        if (issued > now + ENVELOPE_MAX_FUTURE_MS)
+            return null; // future-dated
+        if (now - issued > ENVELOPE_MAX_AGE_MS)
+            return null; // stale / replayed
+        return envelope;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The model input for a wake (Spec 35 §3): the FULL raw message body for
+ * mention wakes; the task payload for task wakes. NOTHING ELSE — no generated
+ * instructions, no room summary, no excerpt. Task rendering is mechanical
+ * labeling of server fields; the handoff note rides VERBATIM.
+ */
+export function wakePromptFor(envelope) {
+    if (envelope.event_kind === "mention" || envelope.body !== undefined) {
+        return envelope.body ?? "";
+    }
+    const task = envelope.task;
+    if (!task)
+        return "";
+    const lines = [
+        `Task: ${task.title}`,
+        ...(task.detail ? [`Detail: ${task.detail}`] : []),
+        ...(task.definition_of_done ? [`Definition of done: ${task.definition_of_done}`] : []),
+        `Task id: ${task.task_id}`,
+        `Assigned by: ${task.assigner_plate}`,
+        `Room: ${envelope.room_id}`
+    ];
+    if (task.handoff) {
+        lines.push("", `Handoff from ${task.handoff.author_plate}${task.handoff.summary ? ` — ${task.handoff.summary}` : ""}:`, task.handoff.notes, ...(task.handoff.artifacts.length ? [`Artifacts: ${task.handoff.artifacts.join(", ")}`] : []));
+    }
+    return lines.join("\n");
+}