agent-rooms 0.11.0 → 0.12.0

package/dist/normalize.js

@@ -40,6 +40,21 @@ export function createNormalizer(host, runId) {
         }
         return [ev];
     };
+    const finalize = (exitCode, forcedOutcome) => {
+        if (state.finished)
+            return null;
+        state.finished = true;
+        const outcome = forcedOutcome ?? (state.sawTurnFailed || exitCode !== 0 ? "failed" : "ok");
+        return next({
+            kind: "run_finished",
+            outcome,
+            summary: { actions: state.actions, files: state.files, commands: state.commands }
+        });
+    };
+    // The vendors' own terminal events end the RUN, not the process: codex exec can
+    // linger long after `turn.completed` (its card must not sit on "Working"), and
+    // claude emits a final `result` before exit. Process exit is only the fallback.
+    const done = (outcome) => finalize(outcome === "ok" ? 0 : 1, outcome);
     const mapLine = host === "codex" ? codexLine : claudeLine;
     return {
         start() {
@@ -57,7 +72,7 @@ export function createNormalizer(host, runId) {
                 return [];
             }
             try {
-                return mapLine(obj, state, next).flatMap((e) => emit(e));
+                return mapLine(obj, state, next, done).flatMap((e) => emit(e));
             }
             catch (error) {
                 // Never crash the run on a weird event; surface it generically.
@@ -66,15 +81,9 @@ export function createNormalizer(host, runId) {
             }
         },
         finish(exitCode, forcedOutcome) {
-            if (state.finished)
-                return null;
-            state.finished = true;
-            const outcome = forcedOutcome ?? (state.sawTurnFailed || exitCode !== 0 ? "failed" : "ok");
-            return next({
-                kind: "run_finished",
-                outcome,
-                summary: { actions: state.actions, files: state.files, commands: state.commands }
-            });
+            // Vendor terminal event already closed the run -> the process-exit call
+            // no-ops (finished guard) and never overwrites the vendor's outcome.
+            return finalize(exitCode, forcedOutcome);
         }
     };
 }
@@ -85,7 +94,7 @@ export function createNormalizer(host, runId) {
 // {"type":"assistant","message":{"content":[{"type":"text","text":…}|{"type":
 // "tool_use","id":…,"name":…,"input":{…}}]}} and {"type":"user","message":
 // {"content":[{"type":"tool_result","tool_use_id":…,"is_error":…}]}}.
-function claudeLine(obj, state, next) {
+function claudeLine(obj, state, next, done) {
     const type = obj.type;
     if (type === "assistant" || type === "user") {
         const message = obj.message;
@@ -153,8 +162,9 @@ function claudeLine(obj, state, next) {
         return out;
     }
     if (type === "result") {
-        // handled by finish(); the final text already streamed as assistant text
-        return [];
+        // Claude's own terminal event — freeze the card now; the final text already
+        // streamed as assistant text. subtype "success" = ok, anything else failed.
+        return [done(obj.subtype === "success" ? "ok" : "failed")];
     }
     if (type === "system" || type === "rate_limit_event")
         return [];
@@ -164,13 +174,18 @@ function claudeLine(obj, state, next) {
 // item.* events with item.type ∈ agent_message | reasoning | command_execution |
 // file_change | todo_list | mcp_tool_call | web_search | error. Transient
 // "Reconnecting…" errors are non-fatal. turn.failed → failed outcome.
-function codexLine(obj, state, next) {
+function codexLine(obj, state, next, done) {
     const type = String(obj.type ?? "");
-    if (type === "thread.started" || type === "turn.started" || type === "turn.completed")
+    if (type === "thread.started" || type === "turn.started")
         return [];
+    if (type === "turn.completed") {
+        // codex's terminal event. The exec process can LINGER long after this (MCP
+        // keep-alive) — the card must freeze here, not at process exit.
+        return [done("ok")];
+    }
     if (type === "turn.failed") {
         state.sawTurnFailed = true;
-        return [];
+        return [done("failed")];
     }
     if (type === "error") {
         const message = String(obj.message ?? "");

package/dist/plugins.js

@@ -0,0 +1,266 @@
+// Spec 35 §13 — four thin native integrations. The shared manifest is the
+// compatibility/source-of-truth layer; host-native wrappers contain only MCP
+// wiring, auth mode, and the hosted skill pointer. No coordination logic and no
+// bundled skill copy live in any plugin.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { configHome } from "./config.js";
+import { getAdapter, hostVersionGate, MIN_HOST_VERSIONS, readHostVersion, versionAtLeast } from "./hosts.js";
+import { resolveSpawnCommand } from "./spawn.js";
+import { DEFAULT_SKILL_BASE_URL } from "./skill.js";
+export const NATIVE_PLUGIN_VERSION = "0.1.0";
+export const NATIVE_PLUGIN_MARKETPLACE = "agent-rooms";
+export const NATIVE_PLUGIN_HOSTS = ["claude_code", "codex", "openclaw", "hermes"];
+const TESTED_HOST_VERSIONS = {
+    claude_code: "2.1.214",
+    codex: "0.144.5",
+    openclaw: "2026.7.1",
+    hermes: "0.18.2"
+};
+const MAX_EXCLUSIVE = {
+    claude_code: "2.2.0",
+    codex: "0.145.0",
+    openclaw: "2026.8.0",
+    hermes: "0.19.0"
+};
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+function writeOwned(path, body) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body, { encoding: "utf8", mode: 0o600 });
+}
+function resourceHost(host) {
+    return host === "claude_code" ? "claude" : host;
+}
+function normalizedBase(apiBase) {
+    return apiBase.replace(/\/$/, "");
+}
+export function pluginCompatibility(host, installed = readHostVersion(getAdapter(host).bin)) {
+    const min = MIN_HOST_VERSIONS[host] ?? "0.0.0";
+    const maxExclusive = MAX_EXCLUSIVE[host];
+    if (!installed) {
+        return { ok: false, installed: null, min, maxExclusive, message: `Could not read ${getAdapter(host).bin} --version. Install ${min}+ and re-run agent-rooms init.` };
+    }
+    if (!versionAtLeast(installed, min) || versionAtLeast(installed, maxExclusive)) {
+        return {
+            ok: false, installed, min, maxExclusive,
+            message: `${host} ${installed} is outside the tested plugin range ${min} <= version < ${maxExclusive}. Only this integration is disabled; update agent-rooms before enabling it.`
+        };
+    }
+    return { ok: true, installed, min, maxExclusive, message: null };
+}
+export function nativePluginRoot(host, home = configHome()) {
+    return join(home, "native-plugins", host);
+}
+export function nativePluginManifest(host, apiBase) {
+    const auth = host === "codex" ? "bearer_env" : "oauth";
+    return {
+        schema_version: 1,
+        id: "agent-rooms",
+        version: NATIVE_PLUGIN_VERSION,
+        host,
+        mcp: {
+            name: "agent-rooms",
+            url: `${normalizedBase(apiBase)}/mcp/${resourceHost(host)}`,
+            auth,
+            ...(auth === "bearer_env" ? { bearer_env: "AGENT_ROOMS_TOKEN" } : {})
+        },
+        hosted_skill_url: `${DEFAULT_SKILL_BASE_URL}/SKILL.md`,
+        compatibility: {
+            min: MIN_HOST_VERSIONS[host] ?? "0.0.0",
+            max_exclusive: MAX_EXCLUSIVE[host],
+            tested: TESTED_HOST_VERSIONS[host]
+        }
+    };
+}
+/** Render one host-native plugin into Agent Rooms-owned state. Returns the path
+ * passed to that host's native installer. */
+export function stageNativePlugin(host, apiBase, home = configHome()) {
+    const root = nativePluginRoot(host, home);
+    const manifest = nativePluginManifest(host, apiBase);
+    mkdirSync(root, { recursive: true });
+    writeOwned(join(root, "agent-rooms.integration.json"), json(manifest));
+    const mcpServer = {
+        type: "http",
+        url: manifest.mcp.url,
+        ...(manifest.mcp.auth === "bearer_env"
+            ? { bearer_token_env_var: manifest.mcp.bearer_env }
+            : { oauth_resource: manifest.mcp.url })
+    };
+    const readme = `# Agent Rooms\n\nMCP resource: ${manifest.mcp.url}\n\nHosted skill: ${manifest.hosted_skill_url}\n`;
+    if (host === "claude_code") {
+        const plugin = join(root, "plugins", "agent-rooms");
+        writeOwned(join(root, ".claude-plugin", "marketplace.json"), json({
+            name: NATIVE_PLUGIN_MARKETPLACE,
+            description: "Exact Agent Rooms MCP and hosted skill wiring",
+            owner: { name: "Beronel" },
+            plugins: [{ name: "agent-rooms", source: "./plugins/agent-rooms", description: "Agent Rooms MCP wiring", version: NATIVE_PLUGIN_VERSION }]
+        }));
+        writeOwned(join(plugin, ".claude-plugin", "plugin.json"), json({
+            name: "agent-rooms", version: NATIVE_PLUGIN_VERSION,
+            description: "Exact Agent Rooms MCP and hosted skill wiring", author: { name: "Beronel" }
+        }));
+        writeOwned(join(plugin, ".mcp.json"), json({ mcpServers: { "agent-rooms": mcpServer } }));
+        writeOwned(join(plugin, "README.md"), readme);
+        return { root, installPath: root, manifest };
+    }
+    if (host === "codex") {
+        const plugin = join(root, "plugins", "agent-rooms");
+        writeOwned(join(root, ".agents", "plugins", "marketplace.json"), json({
+            name: NATIVE_PLUGIN_MARKETPLACE,
+            interface: { displayName: "Agent Rooms" },
+            plugins: [{
+                    name: "agent-rooms", source: { source: "local", path: "./plugins/agent-rooms" },
+                    policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: "Communication"
+                }]
+        }));
+        writeOwned(join(plugin, ".codex-plugin", "plugin.json"), json({
+            name: "agent-rooms", version: NATIVE_PLUGIN_VERSION,
+            description: "Exact Agent Rooms MCP and hosted skill wiring",
+            author: { name: "Beronel" }, homepage: "https://tryagentroom.com", license: "Proprietary",
+            keywords: ["agent-rooms", "mcp", "collaboration"], mcpServers: "./.mcp.json",
+            interface: {
+                displayName: "Agent Rooms", shortDescription: "Collaborate with other agents",
+                longDescription: "Connect Codex to private Agent Rooms through the exact host-bound MCP resource.",
+                developerName: "Beronel", category: "Communication", capabilities: ["Interactive", "Read", "Write"],
+                websiteURL: "https://tryagentroom.com", defaultPrompt: ["Check my Agent Rooms"]
+            }
+        }));
+        writeOwned(join(plugin, ".mcp.json"), json({ mcpServers: { "agent-rooms": mcpServer } }));
+        writeOwned(join(plugin, "README.md"), readme);
+        return { root, installPath: root, manifest };
+    }
+    if (host === "openclaw") {
+        writeOwned(join(root, "package.json"), json({
+            name: "openclaw-plugin-agent-rooms", version: NATIVE_PLUGIN_VERSION, type: "module", private: true,
+            files: ["index.js", "openclaw.plugin.json", "agent-rooms.integration.json", "README.md"],
+            peerDependencies: { openclaw: ">=2026.3.0 <2027.0.0" }, openclaw: { extensions: ["./index.js"] }
+        }));
+        writeOwned(join(root, "openclaw.plugin.json"), json({
+            id: "agent-rooms", name: "Agent Rooms", description: "Exact Agent Rooms MCP and hosted skill wiring",
+            version: NATIVE_PLUGIN_VERSION, activation: { onStartup: true },
+            configSchema: { type: "object", additionalProperties: false, properties: {} }
+        }));
+        writeOwned(join(root, "index.js"), `export default { id: "agent-rooms", name: "Agent Rooms", register() {} };\n`);
+        writeOwned(join(root, "README.md"), readme);
+        return { root, installPath: root, manifest };
+    }
+    // Hermes' installed source requires plugin.yaml + __init__.py/register(ctx).
+    // It has no plugin API version field, so compatibility stays in our shared
+    // manifest and doctor disables only Hermes when the tested range is crossed.
+    writeOwned(join(root, "plugin.yaml"), [
+        "manifest_version: 1", "name: agent-rooms", `version: "${NATIVE_PLUGIN_VERSION}"`,
+        'description: "Exact Agent Rooms MCP and hosted skill wiring"', 'author: "Beronel"', "hooks: []", ""
+    ].join("\n"));
+    writeOwned(join(root, "__init__.py"), `"""Agent Rooms wiring marker; coordination stays server-side."""\n\ndef register(ctx):\n    return None\n`);
+    writeOwned(join(root, "README.md"), readme);
+    return { root, installPath: root, manifest };
+}
+function defaultRunner(command, args) {
+    const resolved = resolveSpawnCommand(command, args);
+    return spawnSync(resolved.command, resolved.args, { encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true });
+}
+function commandText(result) {
+    return `${result.stdout ?? ""}\n${result.stderr ?? ""}\n${result.error?.message ?? ""}`.trim();
+}
+function runRequired(runner, command, args, tolerate) {
+    const result = runner(command, args);
+    const output = commandText(result);
+    if (result.status === 0 || (tolerate && tolerate.test(output)))
+        return;
+    throw new Error(`${command} ${args.join(" ")} failed${output ? `: ${output}` : ""}`);
+}
+/** Install/update the host-native wrapper. Connector auth is reconciled by the
+ * host CLI immediately afterward in init/start; a plugin failure prevents wakes. */
+export async function installNativePlugin(host, apiBase, opts = {}) {
+    const compatibility = pluginCompatibility(host, opts.installedVersion === undefined ? readHostVersion(getAdapter(host).bin) : opts.installedVersion);
+    const home = opts.home ?? configHome();
+    if (!compatibility.ok) {
+        return { ok: false, host, root: nativePluginRoot(host, home), manifest: nativePluginManifest(host, apiBase), message: compatibility.message };
+    }
+    const staged = stageNativePlugin(host, apiBase, home);
+    const runner = opts.runner ?? defaultRunner;
+    try {
+        if (host === "claude_code") {
+            runRequired(runner, "claude", ["plugin", "marketplace", "add", staged.installPath, "--scope", "user"], /already/i);
+            runRequired(runner, "claude", ["plugin", "install", "agent-rooms@agent-rooms", "--scope", "user"], /already installed/i);
+        }
+        else if (host === "codex") {
+            runRequired(runner, "codex", ["plugin", "marketplace", "add", staged.installPath], /already/i);
+            runRequired(runner, "codex", ["plugin", "add", "agent-rooms@agent-rooms"], /already installed/i);
+        }
+        else if (host === "openclaw") {
+            runRequired(runner, "openclaw", ["plugins", "install", staged.installPath, "--force"]);
+        }
+        else {
+            const userHome = opts.userHome ?? homedir();
+            const destination = join(userHome, ".hermes", "plugins", "agent-rooms");
+            if (existsSync(destination)) {
+                const marker = join(destination, "agent-rooms.integration.json");
+                if (!existsSync(marker))
+                    throw new Error(`Refusing to overwrite non-Agent-Rooms Hermes plugin at ${destination}.`);
+                rmSync(destination, { recursive: true, force: true });
+            }
+            mkdirSync(destination, { recursive: true });
+            for (const file of ["agent-rooms.integration.json", "plugin.yaml", "__init__.py", "README.md"]) {
+                writeOwned(join(destination, file), readFileSync(join(staged.root, file), "utf8"));
+            }
+            runRequired(runner, "hermes", ["plugins", "enable", "agent-rooms", "--no-allow-tool-override"]);
+        }
+        return { ok: true, host, root: staged.root, manifest: staged.manifest, message: `${host} plugin ${NATIVE_PLUGIN_VERSION} installed.` };
+    }
+    catch (error) {
+        return { ok: false, host, root: staged.root, manifest: staged.manifest, message: error.message };
+    }
+}
+export function readNativePluginManifest(host, home = configHome()) {
+    try {
+        return JSON.parse(readFileSync(join(nativePluginRoot(host, home), "agent-rooms.integration.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function removeOwnedNativePluginState(host, home = configHome()) {
+    const root = nativePluginRoot(host, home);
+    if (!existsSync(join(root, "agent-rooms.integration.json")))
+        return false;
+    rmSync(root, { recursive: true, force: true });
+    return true;
+}
+export function isNativePluginHost(host) {
+    return NATIVE_PLUGIN_HOSTS.includes(host);
+}
+/** Existing host gate plus the narrower plugin API range. */
+export function nativePluginGate(host) {
+    const base = hostVersionGate(host);
+    if (!base.ok)
+        return pluginCompatibility(host, base.installed);
+    return pluginCompatibility(host, base.installed);
+}
+/** Fail-closed runtime gate used by direct `watch` as well as setup flows.
+ * A watcher must not spawn through a missing/stale wrapper after a host update. */
+export function nativePluginRuntimeGate(host, apiBase, opts = {}) {
+    const compatibility = pluginCompatibility(host, opts.installedVersion === undefined
+        ? readHostVersion(getAdapter(host).bin)
+        : opts.installedVersion);
+    if (!compatibility.ok)
+        return compatibility;
+    const actual = readNativePluginManifest(host, opts.home ?? configHome());
+    const expected = nativePluginManifest(host, apiBase);
+    if (!actual) {
+        return { ...compatibility, ok: false, message: `${host} integration is missing. Run agent-rooms init before watch.` };
+    }
+    if (actual.schema_version !== expected.schema_version
+        || actual.id !== expected.id
+        || actual.version !== expected.version
+        || actual.host !== expected.host
+        || actual.mcp.url !== expected.mcp.url
+        || actual.mcp.auth !== expected.mcp.auth
+        || actual.mcp.bearer_env !== expected.mcp.bearer_env
+        || actual.hosted_skill_url !== expected.hosted_skill_url) {
+        return { ...compatibility, ok: false, message: `${host} integration is stale or points at a different server. Re-run agent-rooms init before watch.` };
+    }
+    return compatibility;
+}

package/dist/probes.js

@@ -0,0 +1,220 @@
+// Spec 35 §14 — doctor probes. Every probe is token-free: it checks setup
+// (versions, endpoints, the pinned server key, spawn-command construction)
+// WITHOUT ever starting a harness or making a model/provider call. Each returns
+// a named, actionable result so a human or an agent reading `doctor` output
+// sees exactly what to run.
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { getAdapter, hostVersionGate } from "./hosts.js";
+import { publicKeyFromJwk, verifyWakeFrame } from "./envelope.js";
+import { isNativePluginHost, nativePluginManifest, pluginCompatibility, readNativePluginManifest } from "./plugins.js";
+import { HOSTED_SKILL_MARKER } from "./skill.js";
+import { resolveSpawnCommand } from "./spawn.js";
+function defaultProbeRunner(command, args) {
+    try {
+        const resolved = resolveSpawnCommand(command, args);
+        return spawnSync(resolved.command, resolved.args, { encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true });
+    }
+    catch (error) {
+        return { status: null, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}
+/** The exact host-bound MCP resource. The host segment is part of auth policy,
+ * not cosmetic routing, so doctor must never probe a shared fallback. */
+export function mcpEndpointFor(apiBase, host) {
+    const resourceHost = host === "claude_code" ? "claude" : host;
+    return `${apiBase}/mcp/${resourceHost}`;
+}
+/** §11/§14 version gate: is each bound host new enough? Token-free (`--version`). */
+export function probeHostVersions(bindings, gate = hostVersionGate) {
+    const hosts = [...new Set(bindings.map((b) => b.host))];
+    return hosts.map((host) => {
+        const result = gate(host);
+        if (result.ok) {
+            return { level: "pass", label: `Version (${host})`, detail: result.installed ? `${result.installed} ≥ ${result.min}` : "no minimum" };
+        }
+        return { level: "fail", label: `Version (${host})`, detail: result.installed ? `${result.installed} < ${result.min}` : "unreadable", hint: result.message ?? undefined };
+    });
+}
+/** §3/§14: is the server's message-verification key pinned and parseable? A
+ * listener can't act on wakes without it. Token-free. */
+export function probeServerKeys(serverKeys) {
+    if (!serverKeys?.length) {
+        return { level: "fail", label: "Server keys", detail: "not pinned", hint: "Re-run `agent-rooms start` while online to fetch the verification keyset from /.well-known/jwks.json." };
+    }
+    try {
+        const kids = new Set();
+        for (const key of serverKeys) {
+            if (!key.kid || kids.has(key.kid))
+                throw new Error("missing or duplicate kid");
+            kids.add(key.kid);
+            publicKeyFromJwk(key);
+        }
+        return { level: "pass", label: "Server keys", detail: `${serverKeys.length} pinned (${[...kids].join(", ")})` };
+    }
+    catch {
+        return { level: "fail", label: "Server keys", detail: "keyset has malformed, duplicate, or kid-less entries", hint: "Re-run `agent-rooms start` to refresh the verification keyset." };
+    }
+}
+/** Legacy single-key probe retained for API compatibility in downstream tests. */
+export function probeServerKey(serverKey) {
+    return probeServerKeys(serverKey ? [serverKey] : undefined);
+}
+/** §13/§14: validate the Agent Rooms-owned native manifest before asking a host
+ * to load it. This detects a stale URL/version without patching user config. */
+export function probePluginManifest(host, apiBase, opts = {}) {
+    if (!isNativePluginHost(host)) {
+        return { level: "warn", label: `Plugin (${host})`, detail: "legacy host uses direct MCP wiring" };
+    }
+    const actual = opts.manifest === undefined ? readNativePluginManifest(host) : opts.manifest;
+    if (!actual) {
+        return { level: "fail", label: `Plugin (${host})`, detail: "manifest missing", hint: `Run \`agent-rooms init --host ${host} ...\` to install it.` };
+    }
+    const expected = nativePluginManifest(host, apiBase);
+    if (actual.schema_version !== 1 || actual.id !== "agent-rooms" || actual.host !== host || actual.version !== expected.version) {
+        return { level: "fail", label: `Plugin (${host})`, detail: "manifest identity/schema mismatch", hint: `Re-run agent-rooms init for ${host}.` };
+    }
+    if (actual.mcp.url !== expected.mcp.url || actual.mcp.auth !== expected.mcp.auth || actual.hosted_skill_url !== expected.hosted_skill_url) {
+        return { level: "fail", label: `Plugin (${host})`, detail: "MCP/auth/hosted-skill wiring is stale", hint: `Re-run agent-rooms init for ${host}.` };
+    }
+    const compatibility = pluginCompatibility(host, opts.installedVersion === undefined ? undefined : opts.installedVersion);
+    if (!compatibility.ok) {
+        return { level: "fail", label: `Plugin (${host})`, detail: compatibility.message, hint: "Update agent-rooms, then re-run init." };
+    }
+    return { level: "pass", label: `Plugin (${host})`, detail: `v${actual.version}; exact MCP + hosted skill pointer loaded` };
+}
+/** Ask the host itself whether the installed plugin is loaded. This is a
+ * read-only native registry query, never a model/session command. */
+export function probeLoadedPlugin(host, runner = defaultProbeRunner) {
+    if (!isNativePluginHost(host))
+        return { level: "warn", label: `Plugin load (${host})`, detail: "legacy host has no native plugin" };
+    const command = getAdapter(host).bin;
+    const args = host === "claude_code" || host === "codex"
+        ? ["plugin", "list", "--json"]
+        : host === "openclaw"
+            ? ["plugins", "list", "--enabled", "--json"]
+            : ["plugins", "list", "--enabled", "--user", "--json"];
+    let result;
+    try {
+        result = runner(command, args);
+    }
+    catch (error) {
+        result = { status: null, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}\n${result.error?.message ?? ""}`.trim();
+    if (result.status !== 0) {
+        return { level: "fail", label: `Plugin load (${host})`, detail: `native list command failed${output ? `: ${output}` : ""}`, hint: `Run agent-rooms init --host ${host} ..., then re-run doctor.` };
+    }
+    if (!/agent-rooms/i.test(output)) {
+        return { level: "fail", label: `Plugin load (${host})`, detail: "host registry does not show agent-rooms as loaded", hint: `Run agent-rooms init --host ${host} ..., then re-run doctor.` };
+    }
+    return { level: "pass", label: `Plugin load (${host})`, detail: "host registry reports agent-rooms loaded" };
+}
+export function probeHostedSkill(host, adapter = getAdapter(host), fileExists = existsSync) {
+    if (!adapter?.skillDir)
+        return { level: "warn", label: `Skill (${host})`, detail: "host has no skill directory" };
+    const root = join(adapter.skillDir, "agent-rooms");
+    return fileExists(join(root, "SKILL.md")) && fileExists(join(root, HOSTED_SKILL_MARKER))
+        ? { level: "pass", label: `Skill (${host})`, detail: "hosted copy present" }
+        : { level: "fail", label: `Skill (${host})`, detail: "hosted copy or ownership marker missing", hint: `Re-run agent-rooms init for ${host} while online.` };
+}
+/** §14 server-side read-only probes plus a real server-signed envelope. */
+export function probeListenerDiagnostics(diagnostics, serverKeys) {
+    const results = [
+        diagnostics.handshake.reachable
+            ? { level: "pass", label: "Handshake", detail: `protocol v${diagnostics.protocol_version}; minimum listener ${diagnostics.min_listener_version}` }
+            : { level: "fail", label: "Handshake", detail: "listener handshake unavailable", hint: "Check /mcp/listener/diagnostics." },
+        diagnostics.registry.reachable
+            ? { level: "pass", label: "Registry", detail: `reachable; ${diagnostics.registry.active} active session(s)` }
+            : { level: "fail", label: "Registry", detail: "unreachable", hint: "Check the D1 session_registry migration and service health." },
+        diagnostics.queue.reachable
+            ? { level: "pass", label: "Queue", detail: `reachable; ${diagnostics.queue.pending} pending, ${diagnostics.queue.in_flight} in flight` }
+            : { level: "fail", label: "Queue", detail: "unreachable", hint: "Check the wakes migration and PresenceHub health." }
+    ];
+    const frame = diagnostics.envelope_probe;
+    const jwk = serverKeys.find((key) => key.kid === frame.kid);
+    const verified = jwk ? verifyWakeFrame(publicKeyFromJwk(jwk), frame) : null;
+    results.push(verified?.wake_id === frame.id
+        ? { level: "pass", label: "Envelope", detail: `server-signed probe verified with kid ${frame.kid}; not spawned` }
+        : { level: "fail", label: "Envelope", detail: `signed probe failed verification (kid ${frame.kid})`, hint: "Re-run agent-rooms start to refresh the server keyset." });
+    return results;
+}
+/** §14: probe the exact /mcp/<host> endpoint each bound host connects to. A
+ * healthy MCP endpoint answers 401/400 (needs auth) — NOT 500 and NOT a
+ * connection error. Token-free: an unauthenticated HEAD/GET, no model call. */
+export async function probeMcpEndpoint(apiBase, host, fetchImpl = fetch) {
+    const url = mcpEndpointFor(apiBase, host);
+    try {
+        const res = await fetchImpl(url, { method: "GET" });
+        if (res.status >= 500) {
+            return { level: "fail", label: `MCP (${host})`, detail: `HTTP ${res.status} from ${url}`, hint: "The service may be degraded — retry shortly." };
+        }
+        if (res.status === 404) {
+            return { level: "fail", label: `MCP (${host})`, detail: `wrong resource (HTTP 404) at ${url}`, hint: `Reinstall the ${host} integration so it uses ${url}.` };
+        }
+        if ([400, 401, 403, 405, 406].includes(res.status)) {
+            return { level: "pass", label: `MCP (${host})`, detail: `${url} reachable and enforcing MCP/auth (HTTP ${res.status})` };
+        }
+        if (res.ok) {
+            const contentType = res.headers.get("content-type") ?? "";
+            if (contentType.includes("text/event-stream") || contentType.includes("application/json")) {
+                return { level: "pass", label: `MCP (${host})`, detail: `${url} returned MCP-compatible ${contentType.split(";")[0]}` };
+            }
+            return { level: "fail", label: `MCP (${host})`, detail: `unexpected HTTP ${res.status} content-type '${contentType || "missing"}'`, hint: "Check that the URL points to the MCP route, not a web page or proxy fallback." };
+        }
+        return { level: "fail", label: `MCP (${host})`, detail: `unexpected HTTP ${res.status} from ${url}`, hint: "Check the exact host integration resource and service route." };
+    }
+    catch (error) {
+        return { level: "fail", label: `MCP (${host})`, detail: `unreachable at ${url}`, hint: `Check your network/firewall: ${error.message}` };
+    }
+}
+/** §14: confirm the wake command CONSTRUCTS cleanly for a host (the "envelope
+ * injection" dry check) without spawning it — the prompt rides stdin/argv, the
+ * resume flag is well-formed. Token-free by construction: buildWake only builds
+ * a command, it never runs one. */
+export function probeSpawnCommand(host) {
+    const adapter = getAdapter(host);
+    if (!adapter) {
+        return { level: "fail", label: `Spawn (${host})`, detail: "no adapter", hint: `No wake adapter for "${host}".` };
+    }
+    try {
+        const fresh = adapter.buildWake({ prompt: "doctor probe", workspace: process.cwd() });
+        const resumed = adapter.buildWake({ prompt: "doctor probe", workspace: process.cwd(), sessionId: "probe-session" });
+        const carriesPrompt = fresh.stdin === "doctor probe" || fresh.args.includes("doctor probe") || fresh.promptFile?.contents === "doctor probe";
+        const carriesResume = JSON.stringify(resumed.args).includes("probe-session");
+        if (!carriesPrompt) {
+            return { level: "fail", label: `Spawn (${host})`, detail: "prompt not carried", hint: `${host} buildWake dropped the prompt.` };
+        }
+        if (!carriesResume) {
+            return { level: "warn", label: `Spawn (${host})`, detail: "resume not encoded (fresh-session host)" };
+        }
+        return { level: "pass", label: `Spawn (${host})`, detail: `${fresh.command} command builds; resume encoded` };
+    }
+    catch (error) {
+        return { level: "fail", label: `Spawn (${host})`, detail: `build failed: ${error.message}` };
+    }
+}
+/** Named create/resume construction probes. These build argv only and never
+ * execute a harness, preserving doctor's zero-provider-call guarantee. */
+export function probeSessionCommands(host, adapter = getAdapter(host)) {
+    if (!adapter)
+        return [{ level: "fail", label: `Session create (${host})`, detail: "no adapter" }];
+    try {
+        const fresh = adapter.buildWake({ prompt: "doctor probe", workspace: process.cwd() });
+        const resumed = adapter.buildWake({ prompt: "doctor probe", workspace: process.cwd(), sessionId: "probe-session", sessionKey: "doctor-session-key" });
+        const carriesPrompt = fresh.stdin === "doctor probe" || fresh.args.includes("doctor probe") || fresh.promptFile?.contents === "doctor probe";
+        const carriesResume = JSON.stringify(resumed.args).includes("probe-session") || JSON.stringify(resumed.args).includes("doctor-session-key");
+        return [
+            carriesPrompt
+                ? { level: "pass", label: `Session create (${host})`, detail: "fresh native command constructed; not executed" }
+                : { level: "fail", label: `Session create (${host})`, detail: "prompt transport missing", hint: `Update the ${host} adapter.` },
+            carriesResume || !adapter.requiresSessionId
+                ? { level: "pass", label: `Session resume (${host})`, detail: carriesResume ? "resume identity encoded; not executed" : "host uses deterministic session key" }
+                : { level: "fail", label: `Session resume (${host})`, detail: "resume identity missing", hint: `Update the ${host} adapter.` }
+        ];
+    }
+    catch (error) {
+        return [{ level: "fail", label: `Session create (${host})`, detail: error.message }];
+    }
+}