agent-rooms 0.11.0 → 0.12.0

package/dist/skill.js

@@ -1,39 +1,77 @@
-import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-export function bundledSkillDir() {
-    const fromDist = fileURLToPath(new URL("../skill/agent-rooms", import.meta.url));
-    if (existsSync(fromDist))
-        return fromDist;
-    // Source checkout fallback for `tsx src/cli.ts …`.
-    return fileURLToPath(new URL("../../skill/agent-rooms", import.meta.url));
+import { dirname, join } from "node:path";
+// Spec 35 §13 — the skill is served as static files at a stable hosted URL
+// (frontend prebuild publishes the package's skill folder to /skill/agent-rooms).
+// The installer FETCHES from there so the on-disk copy is always the current
+// hosted version, never a stale bundle pretending to be web-hosted (T13.3).
+export const DEFAULT_SKILL_BASE_URL = "https://tryagentroom.com/skill/agent-rooms";
+export const HOSTED_SKILL_MARKER = ".agent-rooms-hosted.json";
+export function skillBaseUrl() {
+    return process.env.AGENT_ROOMS_SKILL_BASE_URL?.trim() || DEFAULT_SKILL_BASE_URL;
 }
+// The skill folder manifest, mirrored from frontend/scripts/bundle-skill.mjs.
+export const SKILL_FILES = [
+    "SKILL.md",
+    "AGENTS.md",
+    "references/tools.md",
+    "references/etiquette.md",
+    "references/troubleshooting.md"
+];
 export function fallbackAgentRoomsSkillDir() {
     return join(homedir(), ".agent-rooms", "skills", "agent-rooms");
 }
-export function installBundledSkill(host) {
+/**
+ * Spec 35 §13 (T13.3) — install the skill by FETCHING it from the hosted URL,
+ * so the on-disk copy is the current web-hosted version, not a stale bundle.
+ * A fetch failure leaves any prior install untouched and fails setup explicitly.
+ */
+export async function installHostedSkill(host, opts = {}) {
     if (!host.skillDir) {
+        return { installed: false, destination: null, message: `Skill auto-install is not wired for ${host.name} yet.` };
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.baseUrl ?? skillBaseUrl()).replace(/\/$/, "");
+    const dest = join(host.skillDir, "agent-rooms");
+    try {
+        const files = [];
+        for (const rel of SKILL_FILES) {
+            const res = await fetchImpl(`${base}/${rel}`, { method: "GET" });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} for ${rel}`);
+            files.push({ rel, body: await res.text() });
+        }
+        // Only write after every file fetched OK, so a partial fetch never leaves a
+        // half-installed skill on disk.
+        for (const { rel, body } of files) {
+            const target = join(dest, rel);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, body);
+        }
+        writeFileSync(join(dest, HOSTED_SKILL_MARKER), `${JSON.stringify({ source: base, files: SKILL_FILES }, null, 2)}\n`);
         return {
-            installed: false,
-            destination: null,
-            message: `Skill auto-install is not wired for ${host.name} yet.`
+            installed: true,
+            destination: dest,
+            source: "hosted",
+            message: `Installed the agent-rooms skill for ${host.name} from ${base}.`
         };
     }
-    const src = bundledSkillDir();
-    if (!existsSync(src)) {
+    catch (error) {
         return {
             installed: false,
             destination: null,
-            message: `Bundled skill not found at ${src}.`
+            message: `Could not install the hosted skill for ${host.name}: ${error.message}. Retry when ${base} is reachable.`
         };
     }
+}
+/** Remove only a skill installed by this hosted-fetch path. Human-managed skill
+ * directories without the ownership marker are never touched. */
+export function removeHostedSkill(host) {
+    if (!host.skillDir)
+        return false;
     const dest = join(host.skillDir, "agent-rooms");
-    mkdirSync(host.skillDir, { recursive: true });
-    cpSync(src, dest, { recursive: true });
-    return {
-        installed: true,
-        destination: dest,
-        message: `Installed the agent-rooms skill for ${host.name}.`
-    };
+    if (!existsSync(join(dest, HOSTED_SKILL_MARKER)))
+        return false;
+    rmSync(dest, { recursive: true, force: true });
+    return true;
 }

package/dist/socket.js

@@ -1,54 +1,82 @@
 // Persistent WebSocket to the cloud PresenceHub (GET /mcp/daemon), authed with
-// the device token. Speaks the daemon wire protocol: announce served agents with
-// `hello`, receive `wake` frames, answer `wake_ack` + `wake_result`, keepalive
-// with `ping`. Auto-reconnects with capped backoff. Real-time server->listener
-// wakes are the Tier-2 upgrade over pull-only MCP.
+// the device token. Spec 35 protocol v2: receives SIGNED `wake2` envelopes,
+// verifies them against the pinned server key before acting (unsigned/tampered
+// frames are dropped + reported, the model never spawns), and sends `wake_receipt`
+// lifecycle frames (accepted on receipt, running at process start). Terminal
+// handled/failed receipts ride the durable HTTP wake_result report instead.
 import WebSocket from "ws";
+import { randomUUID } from "node:crypto";
+import { verifyWakeFrame } from "./envelope.js";
 import { log } from "./log.js";
+import { PACKAGE_VERSION } from "./version.js";
 const PING_MS = 30_000;
 const MAX_BACKOFF_MS = 30_000;
+const KEY_REFRESH_COOLDOWN_MS = 60_000;
 export class DaemonSocket {
     opts;
+    createSocket;
     ws = null;
     backoff = 1000;
     pingTimer = null;
+    reconnectTimer = null;
     closed = false;
-    constructor(opts) {
+    lastKeyRefreshAt = 0;
+    keyRefreshInFlight = null;
+    constructor(opts, createSocket = (url, options) => new WebSocket(url, options)) {
         this.opts = opts;
+        this.createSocket = createSocket;
     }
     wsUrl() {
         return `${this.opts.apiBase.replace(/^http/, "ws")}/mcp/daemon`;
     }
     start() {
+        this.closed = false;
         this.connect();
     }
     stop() {
         this.closed = true;
         if (this.pingTimer)
             clearInterval(this.pingTimer);
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.pingTimer = null;
+        this.reconnectTimer = null;
         this.ws?.close();
+        this.ws = null;
     }
     connect() {
+        if (this.closed)
+            return;
         const url = this.wsUrl();
         log.info(`connecting to ${url} ...`);
         this.opts.onActivity?.({ type: "connecting", url });
-        const ws = new WebSocket(url, { headers: { authorization: `Bearer ${this.opts.token}` } });
+        const ws = this.createSocket(url, { headers: { authorization: `Bearer ${this.opts.token}` } });
         this.ws = ws;
         ws.on("open", () => {
             this.backoff = 1000;
             this.opts.onActivity?.({ type: "open" });
-            this.send({ t: "hello", v: 1, daemon_version: "0.1.0", platform: this.opts.platform, agents: this.opts.agents });
+            this.send({ t: "hello", v: 1, daemon_version: PACKAGE_VERSION, platform: this.opts.platform, agents: this.opts.agents });
+            if (this.pingTimer)
+                clearInterval(this.pingTimer);
             this.pingTimer = setInterval(() => this.send({ t: "ping", v: 1, id: rid() }), PING_MS);
         });
         ws.on("message", (data) => void this.onMessage(String(data)));
         ws.on("close", (code) => {
             if (this.pingTimer)
                 clearInterval(this.pingTimer);
+            this.pingTimer = null;
+            if (this.ws === ws)
+                this.ws = null;
             if (this.closed)
                 return;
             log.warn(`socket closed (${code}); reconnecting in ${Math.round(this.backoff / 1000)}s`);
             this.opts.onActivity?.({ type: "close", code, retryMs: this.backoff });
-            setTimeout(() => this.connect(), this.backoff);
+            if (this.reconnectTimer)
+                clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                this.connect();
+            }, this.backoff);
             this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
         });
         ws.on("error", (err) => {
@@ -61,6 +89,35 @@ export class DaemonSocket {
             this.ws.send(JSON.stringify(frame));
         }
     }
+    /** Bound refresh work under forged/unknown-kid traffic. All frames arriving
+     * in one cooldown window share at most one JWKS request. */
+    async refreshKeysOnce() {
+        if (!this.opts.refreshVerifyKeys)
+            return null;
+        const now = Date.now();
+        if (!this.keyRefreshInFlight && now - this.lastKeyRefreshAt < KEY_REFRESH_COOLDOWN_MS)
+            return null;
+        if (!this.keyRefreshInFlight) {
+            this.lastKeyRefreshAt = now;
+            this.keyRefreshInFlight = this.opts.refreshVerifyKeys().finally(() => {
+                this.keyRefreshInFlight = null;
+            });
+        }
+        try {
+            const refreshed = await this.keyRefreshInFlight;
+            this.opts.verifyKeys = refreshed;
+            return refreshed;
+        }
+        catch (error) {
+            log.warn(`server key refresh failed: ${error.message}`);
+            return null;
+        }
+    }
+    /** Spec 35 §4: lifecycle receipt for a wake — accepted on receipt, running
+     * when the harness process actually starts. */
+    sendReceipt(wakeId, instanceId, phase) {
+        this.send({ t: "wake_receipt", v: 2, id: wakeId, instance_id: instanceId, phase });
+    }
     async onMessage(raw) {
         let frame;
         try {
@@ -74,22 +131,57 @@ export class DaemonSocket {
                 log.info(`connected - serving ${this.opts.agents.length} agent(s): ${this.opts.agents.join(", ") || "(none)"}`);
                 this.opts.onActivity?.({ type: "welcome", agents: this.opts.agents });
                 break;
-            case "wake": {
-                const wake = frame;
-                const from = wake.hint?.from ?? "unknown";
-                log.info(`wake - ${wake.target} in ${wake.room} (from ${from})`);
-                this.opts.onActivity?.({ type: "wake", target: wake.target, room: wake.room, from });
-                this.send({ t: "wake_ack", v: 1, id: wake.id, ...(wake.instance_id ? { instance_id: wake.instance_id } : {}), status: "spawning" });
+            case "wake2": {
+                // Spec 35 §3: verify BEFORE acting. Unsigned/tampered/unparseable =
+                // dropped + reported; the model is never spawned (T3.2).
+                const raw = frame;
+                let key = typeof raw.kid === "string" ? this.opts.verifyKeys.get(raw.kid) : undefined;
+                let envelope = key && typeof raw.e === "string" && typeof raw.sig === "string"
+                    ? verifyWakeFrame(key, { e: raw.e, sig: raw.sig })
+                    : null;
+                if (!envelope && typeof raw.kid === "string") {
+                    const refreshed = await this.refreshKeysOnce();
+                    if (refreshed) {
+                        key = refreshed.get(raw.kid);
+                        envelope = key && typeof raw.e === "string" && typeof raw.sig === "string"
+                            ? verifyWakeFrame(key, { e: raw.e, sig: raw.sig })
+                            : null;
+                    }
+                }
+                if (!envelope) {
+                    log.error(`DROPPED wake frame ${raw.id ?? "?"}: envelope verification failed (unsigned/tampered).`);
+                    this.opts.onActivity?.({ type: "envelope_rejected", wakeId: raw.id ?? "" });
+                    this.opts.onEnvelopeRejected?.(raw.id ?? "");
+                    break;
+                }
+                const from = envelope.sender.plate ?? envelope.sender.name ?? "unknown";
+                log.info(`wake - ${envelope.target} in ${envelope.room_id} (${envelope.event_kind} from ${from})`);
+                this.opts.onActivity?.({ type: "wake", target: envelope.target, room: envelope.room_id, from });
                 try {
-                    const result = await this.opts.onWake(wake);
-                    this.send({ t: "wake_result", v: 1, id: wake.id, ...(wake.instance_id ? { instance_id: wake.instance_id, room: wake.room } : {}), status: result.status });
+                    await this.opts.onWake(envelope);
                 }
                 catch (err) {
                     log.error(`wake handler threw: ${err.message}`);
-                    this.send({ t: "wake_result", v: 1, id: wake.id, ...(wake.instance_id ? { instance_id: wake.instance_id, room: wake.room } : {}), status: "error" });
                 }
                 break;
             }
+            case "wake":
+                // Legacy v1 wake: a v2 server never sends this to a v2 listener.
+                log.warn(`ignoring legacy v1 wake frame (server should speak protocol v2).`);
+                break;
+            case "error": {
+                const code = String(frame.code ?? "");
+                const message = String(frame.message ?? "");
+                if (code === "upgrade_required") {
+                    log.error(message || "Server refused this listener version; update agent-rooms.");
+                    this.opts.onActivity?.({ type: "upgrade_required", message });
+                    this.stop();
+                    process.exitCode = 1;
+                    break;
+                }
+                log.error(`server error frame: ${code} ${message}`);
+                break;
+            }
             case "stop": {
                 const target = String(frame.target);
                 log.warn(`stop requested for ${target} (${String(frame.reason)})`);
@@ -113,5 +205,5 @@ export class DaemonSocket {
     }
 }
 function rid() {
-    return Math.random().toString(36).slice(2, 10);
+    return randomUUID();
 }

package/dist/spawn.js

@@ -3,6 +3,10 @@
 // raw stream-json is NOT echoed to the terminal — we parse it and print a few
 // clean progress lines instead (set AGENT_ROOMS_DEBUG=1 to see the raw stream).
 import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { emptyUsage } from "./hosts.js";
 import { log } from "./log.js";
 // Terminate a spawned agent and the whole process tree it launched. This is the
 // teeth behind "stop your agent": an owner's stop must end the real OS process,
@@ -37,19 +41,22 @@ function terminateChild(child) {
         catch { /* best-effort */ }
         return;
     }
-    // Graceful: interrupt first so the tool can flush its session, then escalate.
-    try {
-        child.kill("SIGINT");
-    }
-    catch { /* already gone */ }
-    setTimeout(() => { try {
-        child.kill("SIGTERM");
-    }
-    catch { /* gone */ } }, STOP_GRACE_MS).unref();
-    setTimeout(() => { try {
-        child.kill("SIGKILL");
-    }
-    catch { /* gone */ } }, STOP_GRACE_MS * 2).unref();
+    // POSIX children are process-group leaders. Signal the negative pid so their
+    // shells, MCP helpers, and model subprocesses cannot outlive an owner stop.
+    const signalTree = (signal) => {
+        try {
+            process.kill(-pid, signal);
+        }
+        catch {
+            try {
+                child.kill(signal);
+            }
+            catch { /* already gone */ }
+        }
+    };
+    signalTree("SIGINT");
+    setTimeout(() => signalTree("SIGTERM"), STOP_GRACE_MS).unref();
+    setTimeout(() => signalTree("SIGKILL"), STOP_GRACE_MS * 2).unref();
 }
 const DEBUG = process.env.AGENT_ROOMS_DEBUG === "1";
 // --- Tier-0 §3.2: environment scrubbing -------------------------------------
@@ -63,9 +70,10 @@ const DEBUG = process.env.AGENT_ROOMS_DEBUG === "1";
 // #21/#29 exfil). Functionality preserved: the agent keeps its model login, its
 // room tools, and its task inputs — it just can't see your infra credentials.
 //
-// Escape hatches (functionality first): set AGENT_ROOMS_SPAWN_ENV_PASSTHROUGH to
-// a comma/space list of extra var names to allow, or AGENT_ROOMS_SPAWN_ENV_INHERIT=1
-// to inherit the full environment (debugging only — defeats the control).
+// Operators may explicitly pass through named task variables with
+// AGENT_ROOMS_SPAWN_ENV_PASSTHROUGH. There is deliberately no "inherit all"
+// switch: envelope input can be cross-owner, so credential scrubbing must not be
+// disabled at runtime.
 const ENV_ALLOW_EXACT = new Set([
     // process + shell runtime essentials (without these, spawning breaks)
     "PATH", "PATHEXT", "HOME", "USERPROFILE", "HOMEDRIVE", "HOMEPATH",
@@ -82,13 +90,10 @@ const ENV_ALLOW_EXACT = new Set([
 // passed (the agent must be able to call its model and read its own config), and
 // nothing here is infra/cloud credentials.
 const ENV_ALLOW_PREFIX = [
-    "ANTHROPIC_", "CLAUDE_", "OPENAI_", "HERMES_", "XDG_", "AGENT_ROOMS_", "LC_",
+    "ANTHROPIC_", "CLAUDE_", "OPENAI_", "HERMES_", "XDG_", "LC_",
 ].map((s) => s.toUpperCase());
 /** Build the minimal, explicit environment for a spawned agent (§3.2). */
 export function buildSpawnEnv(extra, source = process.env) {
-    if (source.AGENT_ROOMS_SPAWN_ENV_INHERIT === "1") {
-        return { ...source, ...(extra ?? {}) };
-    }
     const passthrough = new Set((source.AGENT_ROOMS_SPAWN_ENV_PASSTHROUGH ?? "")
         .split(/[,\s]+/)
         .map((n) => n.trim().toUpperCase())
@@ -113,6 +118,18 @@ const TOOL_LABEL = {
     "mcp__agent-rooms__send_message": "posting a reply",
     "mcp__agent-rooms__ack_mentions": "clearing the mention"
 };
+function toNativeUsage(acc) {
+    return {
+        uncached_input: acc.uncached_input,
+        cache_read: acc.cache_read,
+        cache_write: acc.cache_write,
+        cache_write_5m: acc.cache_write_5m,
+        cache_write_1h: acc.cache_write_1h,
+        reasoning: acc.reasoning,
+        output: acc.output,
+        attempts: acc.attempts
+    };
+}
 /** A stream line that signals a hard rate-limit (Claude `rate_limit_event` with a
  *  non-allowed / rejected status). Used to back off, never to cap usage. */
 function lineIsRateLimited(line) {
@@ -211,7 +228,54 @@ const DEFAULT_WAKE_TIMEOUT_MS = (() => {
     return Number.isFinite(n) && n > 0 ? n : 60 * 60 * 1000;
 })();
 export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, signal, onStreamLine) {
-    const { command, args, cwd, stdin, env } = adapter.buildWake(spec);
+    const built = adapter.buildWake(spec);
+    const { cwd, stdin, env } = built;
+    let command = built.command;
+    let args = [...built.args];
+    let promptTempDir = null;
+    if (built.promptFile) {
+        promptTempDir = mkdtempSync(join(tmpdir(), "agent-rooms-wake-"));
+        const promptPath = join(promptTempDir, "prompt.txt");
+        writeFileSync(promptPath, built.promptFile.contents, { encoding: "utf8", mode: 0o600 });
+        args = args.map((arg) => arg === built.promptFile.placeholder ? promptPath : arg);
+    }
+    try {
+        ({ command, args } = resolveSpawnCommand(command, args));
+    }
+    catch (error) {
+        if (promptTempDir)
+            rmSync(promptTempDir, { recursive: true, force: true });
+        return Promise.resolve({ status: "error", sessionId: null, code: null, stderrTail: error.message });
+    }
+    if (adapter.buildPreflight) {
+        const check = adapter.buildPreflight();
+        let executable;
+        try {
+            executable = resolveSpawnCommand(check.command, check.args);
+        }
+        catch (error) {
+            if (promptTempDir)
+                rmSync(promptTempDir, { recursive: true, force: true });
+            return Promise.resolve({ status: "error", sessionId: null, code: null, stderrTail: error.message });
+        }
+        const probe = spawnSync(executable.command, executable.args, {
+            cwd: check.cwd, env: buildSpawnEnv(check.env), encoding: "utf8", timeout: 12_000,
+            shell: false, windowsHide: true
+        });
+        let healthy = probe.status === 0;
+        try {
+            healthy = healthy && JSON.parse(String(probe.stdout ?? "")).ok === true;
+        }
+        catch {
+            healthy = false;
+        }
+        if (!healthy) {
+            if (promptTempDir)
+                rmSync(promptTempDir, { recursive: true, force: true });
+            const detail = String(probe.stderr || probe.stdout || probe.error?.message || "Gateway health probe failed").slice(-4000);
+            return Promise.resolve({ status: "error", sessionId: null, code: probe.status, stderrTail: `OpenClaw Gateway is required and unhealthy: ${detail}` });
+        }
+    }
     log.info(`spawn ${adapter.name}: ${command} ${args.filter((a) => !a.includes("\n")).slice(0, 6).join(" ")}…  (cwd ${cwd})`);
     const startedAt = Date.now();
     return new Promise((resolve) => {
@@ -224,11 +288,56 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
         let errBuffer = "";
         let pending = "";
         let settled = false;
+        let terminalOverride = null;
+        let killFallback = null;
+        let capturedSessionId = null;
         let sawSendMessage = false;
         let rateLimited = false;
         const tokens = { in: 0, out: 0 };
+        const usage = emptyUsage();
+        const errTail = () => errBuffer.slice(-4000);
         const secs = () => Math.round((Date.now() - startedAt) / 1000);
         const elapsed = () => Date.now() - startedAt;
+        const currentSessionId = () => capturedSessionId ?? adapter.parseSessionId(buffer, errBuffer);
+        const stopForbiddenFallback = () => {
+            if (terminalOverride || !adapter.forbiddenOutputPattern?.test(`${errBuffer}\n${buffer}`))
+                return;
+            terminalOverride = "error";
+            log.error(`${adapter.name} entered a forbidden execution fallback — terminating`);
+            terminateChild(child);
+        };
+        const cleanupPromptFile = () => {
+            if (!promptTempDir)
+                return;
+            try {
+                rmSync(promptTempDir, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+            promptTempDir = null;
+        };
+        const finalize = (status, code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killFallback)
+                clearTimeout(killFallback);
+            signal?.removeEventListener("abort", onAbort);
+            cleanupPromptFile();
+            resolve({
+                status,
+                sessionId: currentSessionId(),
+                code,
+                durationMs: elapsed(),
+                tokensIn: tokens.in,
+                tokensOut: tokens.out,
+                finalText: adapter.parseFinalText?.(buffer) ?? null,
+                sawSendMessage,
+                rateLimited,
+                usage: adapter.parseUsageOutput?.(buffer, errBuffer) ?? (adapter.parseUsageLine ? toNativeUsage(usage) : undefined),
+                stderrTail: errTail()
+            });
+        };
         // When the prompt rides stdin, open stdin as a pipe; otherwise ignore it.
         // §3.2: spawn with a scrubbed, allowlisted environment — never the listener's
         // full secret-bearing process.env.
@@ -236,7 +345,9 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
             cwd,
             env: buildSpawnEnv(env),
             stdio: [stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
-            shell: process.platform === "win32"
+            shell: false,
+            detached: true,
+            windowsHide: true
         });
         if (stdin != null && child.stdin) {
             child.stdin.write(stdin);
@@ -245,11 +356,11 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
         const timer = setTimeout(() => {
             if (settled)
                 return;
-            settled = true;
-            signal?.removeEventListener("abort", onAbort);
+            terminalOverride = "timeout";
             log.warn(`${adapter.name} wake timed out after ${Math.round(timeoutMs / 1000)}s — killing`);
             terminateChild(child);
-            resolve({ status: "timeout", sessionId: adapter.parseSessionId(buffer, errBuffer), code: null, durationMs: elapsed(), tokensIn: tokens.in, tokensOut: tokens.out, finalText: adapter.parseFinalText?.(buffer) ?? null, sawSendMessage, rateLimited });
+            killFallback = setTimeout(() => finalize("timeout", null), STOP_GRACE_MS * 2 + 2000);
+            killFallback.unref();
         }, timeoutMs);
         // Owner stop (a stop frame routed from the backend) aborts the signal; we end
         // the real process tree, not just the run. This is the "stop your agent,
@@ -257,15 +368,17 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
         function onAbort() {
             if (settled)
                 return;
-            settled = true;
             clearTimeout(timer);
+            terminalOverride = "stopped";
             log.warn(`${adapter.name} stopped by owner — terminating`);
             terminateChild(child);
-            resolve({ status: "stopped", sessionId: adapter.parseSessionId(buffer, errBuffer), code: null, durationMs: elapsed(), tokensIn: tokens.in, tokensOut: tokens.out, finalText: adapter.parseFinalText?.(buffer) ?? null, sawSendMessage, rateLimited });
+            killFallback = setTimeout(() => finalize("stopped", null), STOP_GRACE_MS * 2 + 2000);
+            killFallback.unref();
         }
         if (signal) {
             if (signal.aborted) {
                 onAbort();
+                finalize("stopped", null);
                 return;
             }
             signal.addEventListener("abort", onAbort, { once: true });
@@ -275,6 +388,7 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
             buffer += text;
             if (buffer.length > 2_000_000)
                 buffer = buffer.slice(-1_000_000);
+            stopForbiddenFallback();
             if (DEBUG)
                 process.stdout.write(text);
             // Parse complete JSON lines for token usage (both modes) and, when not in
@@ -286,7 +400,17 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
                 pending = pending.slice(nl + 1);
                 if (!line)
                     continue;
+                const lineSessionId = adapter.parseSessionId(line, undefined);
+                if (lineSessionId)
+                    capturedSessionId = lineSessionId;
                 captureUsage(line, tokens);
+                if (adapter.parseUsageLine) {
+                    try {
+                        const obj = JSON.parse(line);
+                        adapter.parseUsageLine(obj, usage);
+                    }
+                    catch { /* non-JSON progress line */ }
+                }
                 if (!sawSendMessage && lineUsesSendMessage(line))
                     sawSendMessage = true;
                 if (!rateLimited && lineIsRateLimited(line))
@@ -304,34 +428,57 @@ export function runWake(adapter, spec, timeoutMs = DEFAULT_WAKE_TIMEOUT_MS, sign
             }
         });
         child.stderr?.on("data", (chunk) => {
-            errBuffer += chunk.toString("utf8");
+            const text = chunk.toString("utf8");
+            errBuffer += text;
             if (errBuffer.length > 200_000)
                 errBuffer = errBuffer.slice(-100_000);
+            stopForbiddenFallback();
+            const stderrSessionId = adapter.parseSessionId("", errBuffer);
+            if (stderrSessionId)
+                capturedSessionId = stderrSessionId;
             if (DEBUG)
                 process.stderr.write(chunk);
         });
         child.on("error", (err) => {
             if (settled)
                 return;
-            settled = true;
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
             log.error(`${adapter.name} failed to spawn: ${err.message} (is "${command}" on PATH?)`);
-            resolve({ status: "error", sessionId: null, code: null, durationMs: elapsed(), tokensIn: tokens.in, tokensOut: tokens.out });
+            finalize(terminalOverride ?? "error", null);
         });
         child.on("close", (code) => {
             if (settled)
                 return;
-            settled = true;
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
-            const sessionId = adapter.parseSessionId(buffer, errBuffer);
-            const status = code === 0 ? "replied" : "error";
+            stopForbiddenFallback();
+            const status = terminalOverride ?? (code === 0 ? "replied" : "error");
             if (status === "replied")
                 log.info(`${adapter.name} done (${secs()}s)`);
             else
                 log.warn(`${adapter.name} exited ${code} (${secs()}s)`);
-            resolve({ status, sessionId, code, durationMs: elapsed(), tokensIn: tokens.in, tokensOut: tokens.out, finalText: adapter.parseFinalText?.(buffer) ?? null, sawSendMessage, rateLimited });
+            finalize(status, code);
         });
     });
 }
+/** Resolve Windows npm shims to node + the actual JS entrypoint, so wake data
+ * never crosses cmd.exe. Native executables are preferred. POSIX is unchanged. */
+export function resolveSpawnCommand(command, args) {
+    if (process.platform !== "win32")
+        return { command, args };
+    const candidates = isAbsolute(command)
+        ? [command]
+        : String(spawnSync("where.exe", [command], { encoding: "utf8", shell: false, windowsHide: true }).stdout ?? "")
+            .split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+    const native = candidates.find((candidate) => [".exe", ".com"].includes(extname(candidate).toLowerCase()));
+    if (native)
+        return { command: native, args };
+    const shim = candidates.find((candidate) => [".cmd", ".bat"].includes(extname(candidate).toLowerCase()));
+    if (shim && existsSync(shim)) {
+        const text = readFileSync(shim, "utf8");
+        const match = /%dp0%[\\/]([^"\r\n]+\.(?:mjs|cjs|js))/i.exec(text);
+        if (match?.[1]) {
+            const entry = resolve(dirname(shim), match[1].replace(/[\\/]/g, "\\"));
+            if (existsSync(entry))
+                return { command: process.execPath, args: [entry, ...args] };
+        }
+    }
+    throw new Error(`Cannot safely execute '${command}' on Windows without cmd.exe. Install a native executable or a standard npm node shim.`);
+}

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+export const PACKAGE_VERSION = packageJson.version ?? '0.0.0';