kojee-mcp 0.7.4 → 0.7.5-beta.1

package/README.md

@@ -11,7 +11,7 @@ There are three ways to connect Kojee to an MCP-capable agent:
 
 1. **Mobile, web & desktop (recommended for chat clients)** — paste the Kojee MCP URL into the app's "Add custom connector" dialog. The app handles OAuth login and consent. No local install. Works on Claude (web/desktop/iOS/Android) and ChatGPT (web/desktop/iOS/Android with Developer Mode enabled).
 2. **Claude Code / Codex / Cursor — the local stdio proxy.** Run `kojee-mcp` locally; it holds a `gw_` gateway token + ES256 keypair and signs every request with DPoP (RFC 9449). The runtime-aware [`init` wizard](#quick-start-claude-code--tandem) wires it into your harness and sets up the wake path so an idle agent is woken by Tandem messages between turns. **This is the recommended path for agentic runtimes** and the focus of this README.
-3. **OpenClaw / Hermes — native Tandem channel plugins.** On those runtimes Tandem is a first-class channel (peer to Telegram/Discord), wired through a plugin that wraps the same gateway client — **not** MCP. See [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes).
+3. **OpenClaw / Hermes — native gateway runtimes.** On those runtimes kojee is registered as the agent's MCP server (so the agent can explore + call kojee tools), and Tandem is a first-class channel wired through the gateway (an in-gateway MCP wake injector on OpenClaw; a sidecar daemon + channel plugin on Hermes). See [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes).
 
 ## Mobile, Web & Desktop (Recommended)
 
@@ -189,8 +189,11 @@ Per-runtime config-path / hooks-path overrides: `--config-path`, `--hooks-path`.
   injector — no webhook receiver, no `--webhook-url`.
 - **hermes** — a **daemon** feeding a webhook receiver. `init --runtime hermes`
   (or `connect --runtime hermes`) validates the webhook env and prints + records
-  the env to export (secret redacted) into a source-able `~/.kojee/hermes.env`.
-  `--webhook-url` is optional (defaults to the hermes-plugin loopback receiver).
+  the env (secret redacted) into a single-quoted `~/.kojee/hermes.env`, loaded
+  with `set -a; . ~/.kojee/hermes.env; set +a` (the installed service unit's
+  `ExecStart` uses this exact wrapper so every var is exported to the daemon on
+  both Linux and macOS). `--webhook-url` is optional (defaults to the
+  hermes-plugin loopback receiver).
 
 `kojee-mcp init --uninstall` is runtime-aware (uses the recorded runtime when
 `--runtime` is omitted). `kojee-mcp doctor` is runtime-aware too.

package/dist/{cc-session-id-RURNIHHC.js → cc-session-id-NNCZCHZZ.js}

@@ -1,10 +1,12 @@
 import {
   SESSION_ID_ENV_VARS,
+  STABLE_RUNTIMES,
   resolveInstanceKey,
   resolveSharedSessionId
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SRLD2UY7.js";
 export {
   SESSION_ID_ENV_VARS,
+  STABLE_RUNTIMES,
   resolveInstanceKey,
   resolveSharedSessionId
 };

package/dist/{chunk-WBXU27BF.js → chunk-3P24YPR7.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-XJEBJIQE.js";
 import {
   resolveSharedSessionId
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SRLD2UY7.js";
 
 // src/hooks/discovery.ts
 async function resolveHookDiscovery(stdinSessionId, deps = {}) {

package/dist/{chunk-ZSHCHOPL.js → chunk-4ATSAH7H.js}

@@ -4,7 +4,7 @@ import {
 import {
   GatewayClient,
   applyStableSessionId
-} from "./chunk-247WFMCJ.js";
+} from "./chunk-TBVJOXIR.js";
 import {
   AuthModule
 } from "./chunk-I67C2HYA.js";
@@ -295,7 +295,7 @@ async function startProxy(config) {
   }
   console.error(`[kojee-mcp] Tandem memberships: ${tandemMembershipCount === -1 ? "unknown" : tandemMembershipCount}`);
   let server;
-  const { selectDelivery } = await import("./registry-XJ67EO22.js");
+  const { selectDelivery } = await import("./registry-DKWVVXJM.js");
   const delivery = selectDelivery(adapter.runtime, {
     supportsChannels: adapter.supportsChannels,
     // Per-window delivered mirror for the tandem_pending tool (codex only —
@@ -331,10 +331,22 @@ async function startProxy(config) {
     }
     for (const step of started.teardown) teardownSteps.push(step);
   } else {
+    if (process.env["KOJEE_WEBHOOK_EXPECTED"]) {
+      console.error(
+        "[kojee-mcp] webhook expected (KOJEE_WEBHOOK_EXPECTED=1) but no delivery configured \u2014 env injection likely failed; check the daemon env file (~/.kojee/hermes.env) / service wiring (ExecStart should be `/bin/sh -c 'set -a; . <envFile>; set +a; exec <bin>'`)."
+      );
+    }
     server = createMcpServer(registry, adapter, tandemMembershipCount);
   }
-  process.stdin.on("end", () => shutdown("stdin end"));
-  process.stdin.on("close", () => shutdown("stdin close"));
+  const isHeadlessDaemon = !!process.env["KOJEE_WEBHOOK_EXPECTED"];
+  if (!isHeadlessDaemon) {
+    process.stdin.on("end", () => shutdown("stdin end"));
+    process.stdin.on("close", () => shutdown("stdin close"));
+  } else {
+    console.error(
+      "[kojee-mcp] headless daemon (KOJEE_WEBHOOK_EXPECTED=1): stdin EOF ignored; lifecycle owned by the service manager (SIGTERM/SIGINT/SIGHUP)."
+    );
+  }
   process.on("SIGHUP", () => shutdown("SIGHUP"));
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));

package/dist/{chunk-XPIW4N55.js → chunk-CPOK642I.js}

@@ -10,6 +10,12 @@ import {
   removeOpenclawMcpServer,
   writeOpenclawMcpConfig
 } from "./chunk-E6WMFMM2.js";
+import {
+  HERMES_INSTANCE_KEY,
+  defaultHermesConfigPath,
+  removeHermesMcpServer,
+  writeHermesMcpConfig
+} from "./chunk-GEGUWQYT.js";
 import {
   WIZARD_RUNTIMES,
   isWizardRuntime
@@ -350,11 +356,11 @@ function writeWebhookSecretBothSides(opts) {
     ["KOJEE_RUNTIME", opts.runtime],
     ["KOJEE_WEBHOOK_URL", opts.webhookUrl],
     ["KOJEE_WEBHOOK_SECRET", secret],
-    ...opts.signatureEnv ?? []
+    ...opts.signatureEnv ?? [],
+    ...opts.daemonExtraEnv ?? []
   ];
   upsertEnvFile(opts.daemonEnvPath, daemonVars, {
-    exportPrefix: true,
-    header: `# kojee daemon env for runtime=${opts.runtime} (source this before starting the daemon)`
+    header: `# kojee daemon env for runtime=${opts.runtime} (load with: set -a; . <this file>; set +a)`
   });
   secureFile(opts.daemonEnvPath);
   const adapterVars = [
@@ -418,6 +424,13 @@ function installBundledPayload(opts) {
 // src/wizard/service.ts
 import fs5 from "fs";
 import path5 from "path";
+function daemonSourceExecCommand(spec) {
+  const target = spec.nodePath ? `${spec.nodePath} ${spec.binPath}` : spec.binPath;
+  return `set -a; . ${spec.envFile}; set +a; exec ${target}`;
+}
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
 function systemdUnit(spec) {
   return [
     "[Unit]",
@@ -427,9 +440,14 @@ function systemdUnit(spec) {
     "",
     "[Service]",
     "Type=simple",
-    `EnvironmentFile=${spec.envFile}`,
-    `Environment=KOJEE_RUNTIME=${spec.runtime}`,
-    `ExecStart=${spec.binPath}`,
+    // §2b DISCRIMINATOR: KOJEE_WEBHOOK_EXPECTED lives in the WRAPPER env (this
+    // Environment= line), NOT in the sourced env file — a same-class drop would
+    // otherwise kill the marker too. It lets startProxy tell the "webhook was
+    // meant to be here" daemon apart from the tools-only child (which never sets
+    // it) when the sourced URL is absent → null delivery.
+    `Environment=KOJEE_RUNTIME=${spec.runtime} KOJEE_WEBHOOK_EXPECTED=1`,
+    // §2a: source the env file inside a shell wrapper (replaces EnvironmentFile=).
+    `ExecStart=/bin/sh -c '${daemonSourceExecCommand(spec)}'`,
     "Restart=always",
     "RestartSec=5",
     "StandardOutput=journal",
@@ -450,11 +468,19 @@ function launchdPlist(spec, label) {
     '<plist version="1.0">',
     "<dict>",
     "  <key>Label</key>",
-    `  <string>${label}</string>`,
+    `  <string>${xmlEscape(label)}</string>`,
+    // §2a: same source-wrapper as the systemd unit so macOS actually loads the
+    // env file (the plist historically never did). The secret is never inlined
+    // here — it stays in the 0o600 sourced file.
     "  <key>ProgramArguments</key>",
-    `  <array><string>${spec.binPath}</string></array>`,
+    "  <array>",
+    "    <string>/bin/sh</string>",
+    "    <string>-c</string>",
+    `    <string>${xmlEscape(daemonSourceExecCommand(spec))}</string>`,
+    "  </array>",
+    // §2b: KOJEE_WEBHOOK_EXPECTED in the wrapper env (NOT the sourced file).
     "  <key>EnvironmentVariables</key>",
-    `  <dict><key>KOJEE_RUNTIME</key><string>${spec.runtime}</string></dict>`,
+    `  <dict><key>KOJEE_RUNTIME</key><string>${xmlEscape(spec.runtime)}</string><key>KOJEE_WEBHOOK_EXPECTED</key><string>1</string></dict>`,
     "  <key>RunAtLoad</key><true/>",
     "  <key>KeepAlive</key><true/>",
     "</dict>",
@@ -529,11 +555,14 @@ function installHermes(inp) {
     adapterEnvPath: adapterEnv,
     webhookUrl: inp.webhookUrl,
     runtime: "hermes",
+    daemonExtraEnv: [["KOJEE_INSTANCE", HERMES_INSTANCE_KEY]],
     ...inp.mcpDir ? { mcpDir: inp.mcpDir } : {},
     ...inp.allowAllUsers ? { allowAllUsers: true } : {},
     ...inp.signatureEnv && inp.signatureEnv.length > 0 ? { signatureEnv: inp.signatureEnv } : {},
     ...inp.webhookSecret ? { existingSecret: inp.webhookSecret } : {}
   });
+  const hermesConfig = defaultHermesConfigPath(inp.homeDir);
+  const mcp = writeHermesMcpConfig(hermesConfig, { binPath: inp.binPath });
   const staged = inp.skipPayload ? [] : installBundledPayload({
     runtime: "hermes",
     baseDir: inp.payloadBaseDir,
@@ -543,6 +572,7 @@ function installHermes(inp) {
   const svc = writeService(inp.platform, {
     serviceName: "kojee-hermes",
     binPath: inp.binPath,
+    ...inp.nodePath ? { nodePath: inp.nodePath } : {},
     envFile: daemonEnv,
     runtime: "hermes",
     homeDir: inp.homeDir
@@ -552,6 +582,8 @@ function installHermes(inp) {
     `  secret:      ${sec.reused ? "reused existing" : "generated"} (matched on daemon + adapter env)`,
     `  daemon env:  ${daemonEnv}`,
     `  adapter env: ${adapterEnv}`,
+    `  mcp config:  ${hermesConfig} (mcp_servers.kojee \u2014 agent explores kojee via mcp_kojee_*)`,
+    ...mcp.backedUp ? [`  NOTE: prior ${hermesConfig} was unparseable; backed up to ${mcp.backedUp} before writing.`] : [],
     inp.skipPayload ? `  plugin:      SKIPPED \u2014 no bundled payload (run \`npm run build\` to stage dist/plugins/hermes)` : `  plugin:      ${pluginDir} (${staged.length} files)`,
     svc.supported ? `  service:     ${svc.unitPath}` : `  service:     manual \u2014 ${svc.note ?? "unsupported platform"}`,
     // NB: the "Receiver contract" section is intentionally NOT printed here.
@@ -559,11 +591,18 @@ function installHermes(inp) {
     // every daemon runtime) on the same URL-present path before this output, so
     // emitting it here too would print the contract twice.
     "",
-    "Next:",
-    `  - start the daemon service:  ${svc.activateCmd}`,
-    "  - reload the Hermes gateway to load the plugin:  systemctl --user restart hermes-gateway (or: hermes gateway restart)",
-    "  - join a tandem once:  tandem_join <tandem_id>",
-    "  - verify:  kojee-mcp doctor"
+    "Next \u2014 ACTIVATE (owner steps; the receiver never binds until you do these, in order):",
+    "  1. enable the Tandem receiver plugin (WITHOUT this, the gateway restart loads nothing):",
+    "         hermes plugins enable kojee-tandem",
+    "  2. restart the gateway to bind the receiver (:8645) AND load the kojee MCP tools:",
+    "         hermes gateway restart   (or: systemctl --user restart hermes-gateway)",
+    `  3. start the pusher daemon:  ${svc.activateCmd}`,
+    "  4. verify end-to-end (should read HEALTHY):  kojee-mcp doctor --runtime hermes",
+    "",
+    "  Notes:",
+    "   - the agent joins rooms from its own tools:  mcp_kojee_tandem_join <tandem_id>",
+    "   - if tools don't register: ensure Hermes has the MCP extra",
+    '       (cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]") and re-check connect_timeout.'
   ];
   return {
     runtime: "hermes",
@@ -923,7 +962,7 @@ function buildDaemonEnvBlock(runtime, wh, envFile) {
     lines.push(`  export KOJEE_WEBHOOK_SECRET=<generated; in ${envFile}>`);
     for (const [k, v] of wh.signatureEnv) lines.push(`  export ${k}=${shellSingleQuote(v)}`);
     lines.push(`  (validated: ${wh.redactedSummary})`);
-    lines.push(`  source ${envFile}`);
+    lines.push(`  set -a; . ${envFile}; set +a`);
   } else {
     lines.push("Set the daemon env (no receiver URL supplied yet):");
     lines.push(`  export KOJEE_RUNTIME=${shellSingleQuote(runtime)}`);
@@ -941,7 +980,18 @@ function distDir() {
 }
 function resolveBinPath() {
   const entry = process.argv[1];
-  return entry && entry.length > 0 ? entry : "kojee-mcp";
+  if (!entry || entry.length === 0) return "kojee-mcp";
+  try {
+    return fs6.realpathSync(entry);
+  } catch {
+    return entry;
+  }
+}
+function resolveDaemonExec() {
+  const nodePath = process.execPath;
+  const binPath = resolveBinPath();
+  const ephemeral = /[\\/]_npx[\\/]/.test(binPath);
+  return { nodePath, binPath, ephemeral };
 }
 function configureHermes(opts) {
   const runtime = "hermes";
@@ -955,7 +1005,10 @@ function configureHermes(opts) {
   opts = effectiveOpts;
   const lines = [];
   lines.push(`Configured runtime: ${runtime}`);
-  lines.push("Wake mode: webhook sink (daemon-consumed). NO MCP-config file, NO hooks written.");
+  lines.push(
+    "Wake mode: webhook sink (daemon-consumed). ALSO registers kojee as the Hermes agent's",
+    "MCP server (mcp_servers.kojee) so the agent can explore kojee tools. NO hooks written."
+  );
   lines.push("");
   if (!suppliedUrl) {
     lines.push(
@@ -981,11 +1034,13 @@ function configureHermes(opts) {
     }
     const env = opts.env ?? process.env;
     const suppliedSecret = (opts.webhookSecret ?? env["KOJEE_WEBHOOK_SECRET"] ?? "").trim();
+    const daemonExec = resolveDaemonExec();
     const install = installHermes({
       homeDir: home,
       payloadBaseDir: base,
       platform: process.platform,
-      binPath: resolveBinPath(),
+      binPath: daemonExec.binPath,
+      nodePath: daemonExec.nodePath,
       webhookUrl: wh.url,
       ...suppliedSecret ? { webhookSecret: suppliedSecret } : {},
       ...wh.signatureEnv.length > 0 ? { signatureEnv: wh.signatureEnv } : {},
@@ -998,6 +1053,15 @@ function configureHermes(opts) {
       return { runtime, output: lines.join("\n"), exitCode: install.exitCode };
     }
     recordRuntime(runtime);
+    if (daemonExec.ephemeral) {
+      lines.push(
+        "\u26A0 DURABILITY: this ran from an ephemeral npx cache, so the daemon points at a",
+        "  path npx will eventually delete (the daemon would then fail to start).",
+        "  For a durable daemon, install globally and re-run init:",
+        "      npm i -g kojee-mcp && kojee-mcp init --runtime hermes",
+        ""
+      );
+    }
     const envFile = path7.join(home, ".kojee", "hermes.env");
     lines.push(...buildDaemonEnvBlock(runtime, wh, envFile));
     lines.push("");
@@ -1062,8 +1126,12 @@ async function runWizardUninstall(runtime, opts) {
     const un = uninstallOpenclaw({ openclawConfigPath: openclawConfigPath(opts) });
     lines.push(un.output);
   } else {
-    lines.push("  (hermes writes no MCP-config or hooks \u2014 nothing to tear down.");
-    lines.push("   Stop the daemon and unset KOJEE_WEBHOOK_URL/SECRET to disable the sink.)");
+    const hermesConfig = defaultHermesConfigPath(kojeeHomeDir());
+    const removedMcp = removeHermesMcpServer(hermesConfig);
+    lines.push(
+      removedMcp ? `  removed mcp_servers.kojee from ${hermesConfig} (operator config preserved)` : `  no mcp_servers.kojee in ${hermesConfig} \u2014 nothing to remove`
+    );
+    lines.push("  (stop the daemon service + reload the gateway to disable the webhook wake path.)");
     const envPath = path7.join(kojeeHomeDir(), ".kojee", `${effective}.env`);
     try {
       fs6.unlinkSync(envPath);
@@ -1109,7 +1177,11 @@ registerBuiltinInstaller(
     "webhook",
     "webhook-secret-both-sides",
     "plugin-payload-copy",
-    "service-install"
+    "service-install",
+    // kojee registered as the Hermes agent's MCP server (mcp_servers.kojee in
+    // ~/.hermes/config.yaml) so the agent can EXPLORE + call kojee tools —
+    // additive to the channel plugin, does not change the webhook wake path.
+    "mcp-config-write"
   ],
   (o) => configureHermes(o)
 );

package/dist/chunk-GEGUWQYT.js

@@ -0,0 +1,90 @@
+// src/wizard/capabilities/hermes-mcp-config.ts
+import fs from "fs";
+import path from "path";
+import { parseDocument, isMap } from "yaml";
+var HERMES_MCP_SERVER_NAME = "kojee";
+var HERMES_INSTANCE_KEY = "hermes-gateway";
+var HERMES_MCP_CONNECT_TIMEOUT_S = 120;
+function defaultHermesConfigPath(homeDir) {
+  return path.join(homeDir, ".hermes", "config.yaml");
+}
+function buildKojeeEntry(binPath) {
+  return {
+    command: binPath,
+    args: [],
+    env: {
+      KOJEE_RUNTIME: "hermes",
+      KOJEE_INSTANCE: HERMES_INSTANCE_KEY,
+      // Vanilla tools-only proxy: NEVER a second webhook delivery (see header).
+      KOJEE_WEBHOOK_URL: ""
+    },
+    connect_timeout: HERMES_MCP_CONNECT_TIMEOUT_S
+  };
+}
+function resolveMode(filePath) {
+  try {
+    return fs.statSync(filePath).mode & 511;
+  } catch {
+    return 384;
+  }
+}
+function atomicWrite(filePath, content, mode) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  fs.writeFileSync(tmp, content, { mode });
+  fs.renameSync(tmp, filePath);
+}
+function backupSuffix(now) {
+  return (now ? now() : /* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+function writeHermesMcpConfig(configPath, opts) {
+  let raw = null;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch {
+    raw = null;
+  }
+  let backedUp;
+  let doc = parseDocument("");
+  if (raw !== null && raw.trim() !== "") {
+    const parsed = parseDocument(raw);
+    if (parsed.errors.length > 0) {
+      backedUp = `${configPath}.corrupt-${backupSuffix(opts.now)}`;
+      fs.copyFileSync(configPath, backedUp);
+    } else {
+      doc = parsed;
+    }
+  }
+  if (doc.hasIn(["mcp_servers"]) && !isMap(doc.getIn(["mcp_servers"], true))) {
+    doc.deleteIn(["mcp_servers"]);
+  }
+  doc.setIn(["mcp_servers", HERMES_MCP_SERVER_NAME], buildKojeeEntry(opts.binPath));
+  atomicWrite(configPath, String(doc), resolveMode(configPath));
+  return { configPath, ...backedUp ? { backedUp } : {} };
+}
+function removeHermesMcpServer(configPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch {
+    return false;
+  }
+  const doc = parseDocument(raw);
+  if (doc.errors.length > 0) return false;
+  if (!doc.hasIn(["mcp_servers", HERMES_MCP_SERVER_NAME])) return false;
+  doc.deleteIn(["mcp_servers", HERMES_MCP_SERVER_NAME]);
+  const servers = doc.getIn(["mcp_servers"], true);
+  if (isMap(servers) && servers.items.length === 0) {
+    doc.deleteIn(["mcp_servers"]);
+  }
+  atomicWrite(configPath, String(doc), resolveMode(configPath));
+  return true;
+}
+
+export {
+  HERMES_MCP_SERVER_NAME,
+  HERMES_INSTANCE_KEY,
+  defaultHermesConfigPath,
+  writeHermesMcpConfig,
+  removeHermesMcpServer
+};

package/dist/{chunk-KNEJTD6G.js → chunk-SRLD2UY7.js}

@@ -1,6 +1,7 @@
 // src/runtime/cc-session-id.ts
 import { randomUUID } from "crypto";
 var SESSION_ID_ENV_VARS = ["CLAUDE_CODE_SESSION_ID"];
+var STABLE_RUNTIMES = /* @__PURE__ */ new Set(["openclaw", "open_claw"]);
 function sanitizeKey(value) {
   return value.replace(/[^A-Za-z0-9_-]/g, "");
 }
@@ -12,6 +13,8 @@ function resolveInstanceKey(deps = {}) {
   }
   const explicit = sanitizeKey((env.KOJEE_INSTANCE ?? "").trim());
   if (explicit) return `inst-${explicit}`;
+  const runtime = sanitizeKey((env.KOJEE_RUNTIME ?? "").trim().toLowerCase());
+  if (STABLE_RUNTIMES.has(runtime)) return `rt-${runtime}`;
   const mint = deps.randomUUID ?? randomUUID;
   return `mint-${mint()}`;
 }
@@ -26,6 +29,7 @@ function resolveSharedSessionId(deps = {}) {
 
 export {
   SESSION_ID_ENV_VARS,
+  STABLE_RUNTIMES,
   resolveInstanceKey,
   resolveSharedSessionId
 };

package/dist/{chunk-247WFMCJ.js → chunk-TBVJOXIR.js}

@@ -13,7 +13,7 @@ import {
 } from "./chunk-PPTKGWFF.js";
 import {
   resolveInstanceKey
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SRLD2UY7.js";
 
 // src/gateway-client.ts
 import crypto from "crypto";

package/dist/cli.js

@@ -4,12 +4,12 @@ import {
 } from "./chunk-EIAUW6KO.js";
 import {
   startProxy
-} from "./chunk-ZSHCHOPL.js";
+} from "./chunk-4ATSAH7H.js";
 import "./chunk-TCWIXG5C.js";
 import {
   pairedConfigPath
 } from "./chunk-5SZHXYPK.js";
-import "./chunk-247WFMCJ.js";
+import "./chunk-TBVJOXIR.js";
 import "./chunk-Z5LPNJQ6.js";
 import "./chunk-I67C2HYA.js";
 import "./chunk-MIEI4PLB.js";
@@ -25,7 +25,7 @@ import {
 import "./chunk-FJUAMJHU.js";
 import "./chunk-PPTKGWFF.js";
 import "./chunk-XJEBJIQE.js";
-import "./chunk-KNEJTD6G.js";
+import "./chunk-SRLD2UY7.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -48,7 +48,7 @@ program.command("pair <code>").description("Pair this machine against Kojee usin
 program.command("connect <code>").description(
   "Connect this runtime to Kojee with a per-agent pair code from the dashboard (claude-code | codex | openclaw | hermes). claude-code/codex/openclaw write a per-runtime paired slot (~/.kojee/agents/<runtime>/config.json) and point the runtime launcher at it via --paired-config; hermes writes the global ~/.kojee/config.json (its daemon + `kojee-mcp send` read that). Idempotent."
 ).requiredOption("--runtime <id>", "Target runtime: claude-code | codex | openclaw | hermes").option("--url <url>", "Broker base URL (default: the canonical staging broker)").action(async (code, opts) => {
-  const { runConnect } = await import("./connect-handler-NZINEMG3.js");
+  const { runConnect } = await import("./connect-handler-NCHC6WPU.js");
   const result = await runConnect({
     code,
     runtime: opts.runtime,
@@ -63,11 +63,11 @@ program.command("hook").description("Run a kojee MCP hook script (called by Clau
   "Hook type: stop, user-prompt-submit, codex-stop, or codex-prompt-submit"
 ).action(async (opts) => {
   if (opts.type === "stop") {
-    const { runStopHook } = await import("./stop-hook-N6TX4YQT.js");
+    const { runStopHook } = await import("./stop-hook-4MNOSDCB.js");
     await runStopHook();
     process.exit(0);
   } else if (opts.type === "user-prompt-submit") {
-    const { runUserPromptSubmitHook } = await import("./user-prompt-submit-hook-DTXXFDSD.js");
+    const { runUserPromptSubmitHook } = await import("./user-prompt-submit-hook-44N6SCNJ.js");
     await runUserPromptSubmitHook();
     process.exit(0);
   } else if (opts.type === "codex-stop") {
@@ -104,7 +104,7 @@ Restart Claude Code for hooks to take effect.`
 program.command("send <tandem_id>").description(
   "Send a Tandem message using this machine's paired credentials (~/.kojee). Prints one JSON envelope to stdout: {ok, message_id, cursor, text} on success, {ok:false, error:<typed code>, message} on failure (exit 1)."
 ).requiredOption("--body <text>", "Message body (required)").option("--reply-to <message_id>", "Message id this send replies to").option("--kind <kind>", "Message kind: message | status (default: backend default)").action(async (tandemId, opts) => {
-  const { runSendCli } = await import("./send-cli-45RLGYIC.js");
+  const { runSendCli } = await import("./send-cli-OLNEVSBI.js");
   const { exitCode, envelope } = await runSendCli({
     tandemId,
     body: opts.body,
@@ -124,7 +124,7 @@ program.command("tail <path>").description("Stream a file's contents and follow
   }
 });
 program.command("doctor").description("Diagnose the kojee wake path (proxy, hook-server, SSE stream, event log, Monitor) and print the exact wake recipe").action(async () => {
-  const { runDoctor } = await import("./doctor-WUU5BVPT.js");
+  const { runDoctor } = await import("./doctor-RKLXZR2B.js");
   const code = await runDoctor();
   process.exit(code);
 });
@@ -143,7 +143,7 @@ function addInstallOptions(cmd, runtimeHelp) {
 function makeInstallAction(verb) {
   return async (opts) => {
     const interactive = process.stdin.isTTY === true && opts.runtime === void 0;
-    const { runSetup, resolvePairCode } = await import("./setup-handler-44ASXYMS.js");
+    const { runSetup, resolvePairCode } = await import("./setup-handler-DA4465VH.js");
     const pairCode = resolvePairCode(opts);
     const result = await runSetup({
       verb,

package/dist/{connect-handler-NZINEMG3.js → connect-handler-NCHC6WPU.js}

@@ -2,9 +2,10 @@ import {
   DEFAULT_BROKER_URL,
   reconcileConnectPairSlot,
   runWizard
-} from "./chunk-XPIW4N55.js";
+} from "./chunk-CPOK642I.js";
 import "./chunk-6XWTUDWW.js";
 import "./chunk-E6WMFMM2.js";
+import "./chunk-GEGUWQYT.js";
 import "./chunk-77HWBSRH.js";
 import "./chunk-TMCNB4JH.js";
 import "./chunk-D6JKFJ6A.js";

package/dist/{doctor-WUU5BVPT.js → doctor-RKLXZR2B.js}

@@ -25,7 +25,7 @@ import {
 } from "./chunk-XJEBJIQE.js";
 import {
   resolveSharedSessionId
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SRLD2UY7.js";
 
 // src/doctor.ts
 import fs from "fs";
@@ -365,6 +365,12 @@ async function runDoctor() {
     console.error(formatOpenclawDoctorReport(report2));
     return report2.verdict === "broken" ? 1 : 0;
   }
+  const { hermesArtifactsPresent, collectHermesDoctorReport, formatHermesDoctorReport } = await import("./doctor-hermes-WLDI4R6P.js");
+  if (hermesArtifactsPresent()) {
+    const hermesReport = collectHermesDoctorReport();
+    console.error(formatHermesDoctorReport(hermesReport));
+    return hermesReport.verdict === "broken" ? 1 : 0;
+  }
   const report = await collectDoctorReport();
   console.error(formatDoctorReport(report));
   return report.verdict === "broken" ? 1 : 0;

package/dist/doctor-hermes-WLDI4R6P.js

@@ -0,0 +1,580 @@
+import {
+  HERMES_INSTANCE_KEY,
+  HERMES_MCP_SERVER_NAME
+} from "./chunk-GEGUWQYT.js";
+
+// src/doctor-hermes.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { execFileSync } from "child_process";
+import { parse } from "yaml";
+
+// src/reconcile/index.ts
+var FindingCollector = class {
+  items = [];
+  /** Append a pre-built Finding. */
+  add(finding) {
+    this.items.push(finding);
+  }
+  /** Append a Finding from its parts (the common call site). */
+  push(id, severity, detail) {
+    this.items.push({ id, severity, detail });
+  }
+  /** The findings in insertion order (read-only view). */
+  get findings() {
+    return this.items;
+  }
+  /**
+   * Roll the findings up into the doctor verdict: any `broken` ⇒ broken; else any
+   * `warn` ⇒ degraded; else healthy. `unknown` never fails the verdict (it is an
+   * "I couldn't determine this" signal, same as the doctor's `?` marks).
+   */
+  verdict() {
+    if (this.items.some((f) => f.severity === "broken")) return "broken";
+    if (this.items.some((f) => f.severity === "warn")) return "degraded";
+    return "healthy";
+  }
+};
+
+// src/doctor-hermes.ts
+var WIZARD_RERUN = "re-run `kojee-mcp init --runtime hermes`";
+var DEFAULT_LISTEN_HOST = "127.0.0.1";
+var DEFAULT_LISTEN_PORT = "8645";
+var DEFAULT_LISTEN_PATH = "/kojee-tandem";
+function serviceUnitPath(homeDir, platform) {
+  if (platform === "darwin") {
+    return path.join(homeDir, "Library", "LaunchAgents", "net.kojee.kojee-hermes.plist");
+  }
+  return path.join(homeDir, ".config", "systemd", "user", "kojee-hermes.service");
+}
+function hermesEnvPathFor(homeDir) {
+  return path.join(homeDir, ".kojee", "hermes.env");
+}
+function hermesArtifactsPresent(deps = {}) {
+  const homeDir = deps.homeDir ?? os.homedir();
+  const platform = deps.platform ?? process.platform;
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  return exists(hermesEnvPathFor(homeDir)) || exists(serviceUnitPath(homeDir, platform));
+}
+function unquoteEnvValue(raw) {
+  let v = raw.trim();
+  if (v.length >= 2 && (v.startsWith("'") && v.endsWith("'") || v.startsWith('"') && v.endsWith('"'))) {
+    v = v.slice(1, -1);
+  }
+  return v.replace(/'\\''/g, "'");
+}
+function parseEnvFile(text) {
+  const vars = /* @__PURE__ */ new Map();
+  const exportKeys = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const m = line.match(/^(export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!m) continue;
+    const key = m[2];
+    if (m[1] !== void 0) exportKeys.push(key);
+    vars.set(key, unquoteEnvValue(m[3]));
+  }
+  return { vars, exportKeys };
+}
+function readChildEnv(configText) {
+  if (configText === null) return null;
+  let doc;
+  try {
+    doc = parse(configText);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object") return null;
+  const servers = doc["mcp_servers"];
+  if (!servers || typeof servers !== "object") return null;
+  const kojee = servers[HERMES_MCP_SERVER_NAME];
+  if (!kojee || typeof kojee !== "object") return null;
+  const env = kojee["env"];
+  if (!env || typeof env !== "object") return null;
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+function sha256(value) {
+  return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+function readPluginEnabled(configText) {
+  if (configText === null) return null;
+  let doc;
+  try {
+    doc = parse(configText);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object") return null;
+  const plugins = doc["plugins"];
+  if (!plugins || typeof plugins !== "object") return false;
+  const enabled = plugins["enabled"];
+  if (!Array.isArray(enabled)) return false;
+  return enabled.includes("kojee-tandem");
+}
+function parseExecTargets(unitText) {
+  if (unitText === null) return null;
+  const m = unitText.match(/exec\s+([^'"\n<]+)/);
+  if (!m) return null;
+  return m[1].trim().split(/\s+/).filter((tok) => tok.startsWith("/"));
+}
+function defaultReadText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function defaultProbeService(platform) {
+  return () => {
+    try {
+      if (platform === "darwin") {
+        const out2 = execFileSync("launchctl", ["list"], { encoding: "utf8" });
+        return { active: out2.includes("net.kojee.kojee-hermes") };
+      }
+      const out = execFileSync("systemctl", ["--user", "is-active", "kojee-hermes"], {
+        encoding: "utf8"
+      }).trim();
+      return { active: out === "active" };
+    } catch (err) {
+      const stdout = err.stdout;
+      if (stdout !== void 0) {
+        const s = (typeof stdout === "string" ? stdout : stdout.toString()).trim();
+        if (s.length > 0) return { active: s === "active" };
+      }
+      return null;
+    }
+  };
+}
+function defaultProbeReceiver(platform) {
+  return (_host, port) => {
+    try {
+      if (platform === "darwin") {
+        try {
+          execFileSync("lsof", [`-iTCP:${port}`, "-sTCP:LISTEN", "-n", "-P"], { encoding: "utf8" });
+          return true;
+        } catch (err) {
+          if (err.status === 1) return false;
+          return null;
+        }
+      }
+      const out = execFileSync("ss", ["-ltnH"], { encoding: "utf8" });
+      const re = new RegExp(`:${port}(\\s|$)`);
+      return out.split("\n").some((l) => re.test(l));
+    } catch {
+      return null;
+    }
+  };
+}
+function defaultReadDaemonEnv(platform) {
+  return () => {
+    if (platform !== "linux") return null;
+    try {
+      const pidStr = execFileSync(
+        "systemctl",
+        ["--user", "show", "-p", "MainPID", "--value", "kojee-hermes"],
+        { encoding: "utf8" }
+      ).trim();
+      const pid = Number.parseInt(pidStr, 10);
+      if (!Number.isFinite(pid) || pid <= 0) return null;
+      const raw = fs.readFileSync(`/proc/${pid}/environ`, "utf8");
+      const out = {};
+      for (const pair of raw.split("\0")) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0) continue;
+        out[pair.slice(0, eq)] = pair.slice(eq + 1);
+      }
+      return out;
+    } catch {
+      return null;
+    }
+  };
+}
+function okFromSeverity(sev) {
+  return sev === "ok" ? true : sev === "warn" ? "warn" : sev === "broken" ? false : "unknown";
+}
+function emit(checks, collector, id, severity, detail) {
+  checks.push({ name: id, ok: okFromSeverity(severity), detail });
+  collector.push(id, severity, detail);
+}
+function collectHermesDoctorReport(deps = {}) {
+  const homeDir = deps.homeDir ?? os.homedir();
+  const platform = deps.platform ?? process.platform;
+  const readText = deps.readText ?? defaultReadText;
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  const probeService = deps.probeService ?? defaultProbeService(platform);
+  const probeReceiver = deps.probeReceiver ?? defaultProbeReceiver(platform);
+  const readDaemonEnv = deps.readDaemonEnv ?? defaultReadDaemonEnv(platform);
+  const hermesEnvPath = hermesEnvPathFor(homeDir);
+  const adapterEnvPath = path.join(homeDir, ".hermes", ".env");
+  const configYamlPath = path.join(homeDir, ".hermes", "config.yaml");
+  const unitPath = serviceUnitPath(homeDir, platform);
+  const daemonEnvText = readText(hermesEnvPath);
+  const adapterEnvText = readText(adapterEnvPath);
+  const unitText = readText(unitPath);
+  const configText = readText(configYamlPath);
+  const daemonEnv = daemonEnvText !== null ? parseEnvFile(daemonEnvText) : null;
+  const adapterEnv = adapterEnvText !== null ? parseEnvFile(adapterEnvText) : null;
+  const childEnv = readChildEnv(configText);
+  const pluginEnabled = readPluginEnabled(configText);
+  const checks = [];
+  const collector = new FindingCollector();
+  if (daemonEnv === null) {
+    emit(checks, collector, "webhook.env-format", "unknown", `hermes.env unreadable at ${hermesEnvPath}`);
+  } else if (daemonEnv.exportKeys.length > 0) {
+    const unitUsesEnvFile = unitText !== null && /^\s*EnvironmentFile=/m.test(unitText);
+    const keys = daemonEnv.exportKeys.join(", ");
+    if (unitUsesEnvFile) {
+      emit(
+        checks,
+        collector,
+        "webhook.env-format",
+        "broken",
+        `hermes.env has export-prefixed line(s) [${keys}] AND the service unit uses EnvironmentFile= \u2014 systemd DROPS them, so the daemon boots with those vars UNSET (silent webhook-off + seat churn). ${WIZARD_RERUN} to rewrite the unit (source wrapper) + env (bare).`
+      );
+    } else {
+      emit(
+        checks,
+        collector,
+        "webhook.env-format",
+        "warn",
+        `hermes.env has legacy export-prefixed line(s) [${keys}] \u2014 harmless under the source-wrapper unit (set -a exports them) but ${WIZARD_RERUN} to normalize to bare form.`
+      );
+    }
+  } else {
+    emit(
+      checks,
+      collector,
+      "webhook.env-format",
+      "ok",
+      "hermes.env is bare single-quoted (no export-prefixed lines) \u2014 sources cleanly."
+    );
+  }
+  const daemonUrl = (daemonEnv?.vars.get("KOJEE_WEBHOOK_URL") ?? "").trim();
+  const listenHost = adapterEnv?.vars.get("KOJEE_TANDEM_LISTEN_HOST") ?? DEFAULT_LISTEN_HOST;
+  const listenPort = adapterEnv?.vars.get("KOJEE_TANDEM_LISTEN_PORT") ?? DEFAULT_LISTEN_PORT;
+  const listenPath = adapterEnv?.vars.get("KOJEE_TANDEM_LISTEN_PATH") ?? DEFAULT_LISTEN_PATH;
+  if (!daemonUrl) {
+    emit(
+      checks,
+      collector,
+      "webhook.url-receiver-align",
+      "broken",
+      `daemon KOJEE_WEBHOOK_URL is EMPTY \u2014 no event stream (null delivery); the daemon will not POST wakes. Set the receiver URL: ${WIZARD_RERUN}.`
+    );
+  } else {
+    let parsed = null;
+    try {
+      parsed = new URL(daemonUrl);
+    } catch {
+      parsed = null;
+    }
+    if (parsed === null) {
+      emit(
+        checks,
+        collector,
+        "webhook.url-receiver-align",
+        "broken",
+        `daemon KOJEE_WEBHOOK_URL is not a valid URL \u2014 ${WIZARD_RERUN}.`
+      );
+    } else {
+      const urlPort = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+      const aligned = parsed.hostname === listenHost && urlPort === listenPort && parsed.pathname === listenPath;
+      emit(
+        checks,
+        collector,
+        "webhook.url-receiver-align",
+        aligned ? "ok" : "broken",
+        aligned ? `daemon URL host/port/path aligns with the receiver bind (${listenHost}:${listenPort}${listenPath}).` : `daemon URL (${parsed.hostname}:${urlPort}${parsed.pathname}) != receiver bind (${listenHost}:${listenPort}${listenPath}) \u2014 POSTs miss the listener. Align them.`
+      );
+    }
+  }
+  const daemonSecret = daemonEnv?.vars.get("KOJEE_WEBHOOK_SECRET");
+  const adapterSecret = adapterEnv?.vars.get("KOJEE_WEBHOOK_SECRET");
+  if (!daemonSecret || !adapterSecret) {
+    const which = [!daemonSecret ? "daemon (hermes.env)" : null, !adapterSecret ? "adapter (~/.hermes/.env)" : null].filter((s) => s !== null).join(" and ");
+    emit(
+      checks,
+      collector,
+      "webhook.secret-match",
+      "broken",
+      `KOJEE_WEBHOOK_SECRET missing on ${which} \u2014 the receiver can't verify signed POSTs (401). ${WIZARD_RERUN}.`
+    );
+  } else {
+    const same = sha256(daemonSecret) === sha256(adapterSecret);
+    emit(
+      checks,
+      collector,
+      "webhook.secret-match",
+      same ? "ok" : "broken",
+      same ? "daemon + adapter secrets match (compared by sha256; values never printed)." : `daemon vs adapter KOJEE_WEBHOOK_SECRET DIFFER (compared by sha256; values never printed) \u2014 every POST is rejected 401. Resync one side: ${WIZARD_RERUN} (writes one secret both sides).`
+    );
+  }
+  const execTargets = parseExecTargets(unitText);
+  if (unitText === null) {
+    emit(checks, collector, "webhook.daemon-bin", "unknown", `service unit unreadable at ${unitPath}.`);
+  } else if (execTargets === null || execTargets.length === 0) {
+    emit(
+      checks,
+      collector,
+      "webhook.daemon-bin",
+      "warn",
+      "could not parse the ExecStart exec target from the unit \u2014 cannot verify the daemon binary."
+    );
+  } else {
+    const missing = execTargets.filter((p) => !exists(p));
+    const ephemeral = execTargets.find((p) => /[\\/]_npx[\\/]/.test(p));
+    if (missing.length > 0) {
+      emit(
+        checks,
+        collector,
+        "webhook.daemon-bin",
+        "broken",
+        `daemon ExecStart points at ${missing.join(", ")} which does NOT exist \u2014 the service fails to start (exit 127) and crash-loops. Install globally + ${WIZARD_RERUN}: \`npm i -g kojee-mcp && kojee-mcp init --runtime hermes\`.`
+      );
+    } else if (ephemeral) {
+      emit(
+        checks,
+        collector,
+        "webhook.daemon-bin",
+        "warn",
+        `daemon ExecStart runs from an EPHEMERAL npx cache (${ephemeral}) \u2014 it works now but npx will eventually delete it, then the daemon dies (exit 127). For durability: \`npm i -g kojee-mcp && kojee-mcp init --runtime hermes\`.`
+      );
+    } else {
+      emit(
+        checks,
+        collector,
+        "webhook.daemon-bin",
+        "ok",
+        `daemon ExecStart targets exist (${execTargets.join(" ")}) \u2014 node + CLI resolve without PATH.`
+      );
+    }
+  }
+  const svc = probeService();
+  if (svc === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.pusher-up",
+      "unknown",
+      "could not determine kojee-hermes service state (systemctl/launchctl unavailable)."
+    );
+  } else if (svc.active) {
+    emit(checks, collector, "webhook.pusher-up", "ok", "kojee-hermes service is active.");
+  } else {
+    const why = execTargets && execTargets.some((p) => !exists(p)) ? " (likely the missing ExecStart binary above \u2014 exit 127)" : "";
+    emit(
+      checks,
+      collector,
+      "webhook.pusher-up",
+      "broken",
+      `kojee-hermes service is NOT active${why} \u2014 no wakes are being pushed. Enable+start it (\`systemctl --user enable --now kojee-hermes\`) \u2014 shared infra, so the principal's call.`
+    );
+  }
+  if (pluginEnabled === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.plugin-enabled",
+      "unknown",
+      "could not read plugins.enabled from ~/.hermes/config.yaml."
+    );
+  } else if (pluginEnabled) {
+    emit(
+      checks,
+      collector,
+      "webhook.plugin-enabled",
+      "ok",
+      "kojee-tandem receiver plugin is enabled in Hermes (plugins.enabled)."
+    );
+  } else {
+    emit(
+      checks,
+      collector,
+      "webhook.plugin-enabled",
+      "broken",
+      "kojee-tandem receiver plugin is NOT enabled \u2014 the gateway loads no receiver, so wakes never arrive (a gateway restart alone can't fix this). Enable it, then restart the gateway: `hermes plugins enable kojee-tandem && hermes gateway restart`."
+    );
+  }
+  const receiver = probeReceiver(listenHost, Number.parseInt(listenPort, 10));
+  if (receiver === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.receiver-up",
+      "unknown",
+      `could not probe the receiver bind ${listenHost}:${listenPort} (ss/lsof unavailable).`
+    );
+  } else if (receiver) {
+    emit(
+      checks,
+      collector,
+      "webhook.receiver-up",
+      "ok",
+      `receiver is listening on ${listenHost}:${listenPort}.`
+    );
+  } else {
+    const fix = pluginEnabled === false ? "the kojee-tandem plugin is DISABLED (see webhook.plugin-enabled) \u2014 enable it, then restart the gateway" : "the Hermes gateway (kojee-tandem plugin) receiver is down \u2014 restart the gateway to load the plugin";
+    emit(
+      checks,
+      collector,
+      "webhook.receiver-up",
+      "warn",
+      `nothing is listening on ${listenHost}:${listenPort} \u2014 ${fix}.`
+    );
+  }
+  if (childEnv === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.no-duplicate",
+      "unknown",
+      `could not read mcp_servers.${HERMES_MCP_SERVER_NAME}.env from ~/.hermes/config.yaml.`
+    );
+  } else {
+    const childUrl = (childEnv["KOJEE_WEBHOOK_URL"] ?? "").trim();
+    emit(
+      checks,
+      collector,
+      "webhook.no-duplicate",
+      childUrl === "" ? "ok" : "broken",
+      childUrl === "" ? "mcp child KOJEE_WEBHOOK_URL is empty (hard-off) \u2014 no duplicate delivery." : `mcp_servers.${HERMES_MCP_SERVER_NAME} has a NON-EMPTY KOJEE_WEBHOOK_URL \u2014 the tools-only child would DOUBLE-DELIVER wakes for the seat. Clear it (keep the empty hard-off).`
+    );
+  }
+  const daemonInstance = (daemonEnv?.vars.get("KOJEE_INSTANCE") ?? "").trim();
+  const childInstance = (childEnv?.["KOJEE_INSTANCE"] ?? "").trim();
+  if (!daemonInstance) {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "broken",
+      `daemon KOJEE_INSTANCE is unset \u2014 daemon + MCP child may resolve to DIFFERENT sessions (split-brain seat). Expected '${HERMES_INSTANCE_KEY}'. ${WIZARD_RERUN}.`
+    );
+  } else if (childInstance && daemonInstance !== childInstance) {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "broken",
+      `daemon KOJEE_INSTANCE='${daemonInstance}' != mcp child KOJEE_INSTANCE='${childInstance}' \u2014 split-brain: a tandem_send from the agent lands on a different seat than the daemon streams wakes for. ${WIZARD_RERUN}.`
+    );
+  } else if (daemonInstance !== HERMES_INSTANCE_KEY) {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "warn",
+      `daemon KOJEE_INSTANCE='${daemonInstance}' != expected '${HERMES_INSTANCE_KEY}' (non-standard but self-consistent with the child).`
+    );
+  } else {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "ok",
+      `daemon + mcp child share KOJEE_INSTANCE='${HERMES_INSTANCE_KEY}' \u2014 one backend seat.`
+    );
+  }
+  if (platform !== "linux") {
+    emit(
+      checks,
+      collector,
+      "webhook.env-reaches-daemon",
+      "unknown",
+      "n/a \u2014 reads /proc/<pid>/environ (Linux only)."
+    );
+  } else {
+    const liveEnv = readDaemonEnv();
+    if (liveEnv === null) {
+      emit(
+        checks,
+        collector,
+        "webhook.env-reaches-daemon",
+        "unknown",
+        "daemon not running (no MainPID) or its /proc environ is unreadable."
+      );
+    } else {
+      const missing = ["KOJEE_WEBHOOK_URL", "KOJEE_WEBHOOK_SECRET", "KOJEE_INSTANCE"].filter(
+        (k) => !((liveEnv[k] ?? "").length > 0)
+      );
+      emit(
+        checks,
+        collector,
+        "webhook.env-reaches-daemon",
+        missing.length === 0 ? "ok" : "broken",
+        missing.length === 0 ? "live daemon env carries KOJEE_WEBHOOK_URL/SECRET/INSTANCE (injection reached the process; secret value never read)." : `live daemon env is MISSING ${missing.join(", ")} \u2014 env injection did NOT reach the running daemon (source wrapper not applied / stale unit). ${WIZARD_RERUN}, then restart the service.`
+      );
+    }
+  }
+  return { checks, findings: collector.findings, verdict: collector.verdict() };
+}
+var CHECK_GROUP = {
+  "webhook.env-format": "Config",
+  "webhook.url-receiver-align": "Config",
+  "webhook.secret-match": "Config",
+  "webhook.no-duplicate": "Config",
+  "webhook.instance-align": "Config",
+  "webhook.plugin-enabled": "Receiver",
+  "webhook.receiver-up": "Receiver",
+  "webhook.daemon-bin": "Pusher",
+  "webhook.pusher-up": "Pusher",
+  "webhook.env-reaches-daemon": "Pusher"
+};
+function formatHermesDoctorReport(report) {
+  const mark = (ok) => ok === true ? "\u2713" : ok === "warn" ? "\u26A0" : ok === "unknown" ? "?" : "\u2717";
+  const shortName = (name) => name.replace(/^webhook\./, "");
+  const nOk = report.checks.filter((c) => c.ok === true).length;
+  const nWarn = report.checks.filter((c) => c.ok === "warn").length;
+  const nBad = report.checks.filter((c) => c.ok === false).length;
+  const nUnknown = report.checks.filter((c) => c.ok === "unknown").length;
+  const verdictMark = report.verdict === "healthy" ? "\u2713" : report.verdict === "degraded" ? "\u26A0" : "\u2717";
+  const lines = [];
+  lines.push(`kojee-mcp doctor \xB7 hermes wake-path \xB7 ${verdictMark} ${report.verdict.toUpperCase()}`);
+  const tally = [
+    `${nOk} ok`,
+    nWarn ? `${nWarn} warning${nWarn > 1 ? "s" : ""}` : null,
+    nBad ? `${nBad} problem${nBad > 1 ? "s" : ""}` : null,
+    nUnknown ? `${nUnknown} unknown` : null
+  ].filter(Boolean).join(", ");
+  lines.push(`  ${tally}`);
+  lines.push("  path: daemon (SSE \u2192 HMAC POST) \u2192 :8645 receiver plugin \u2192 wakes the agent");
+  lines.push("");
+  for (const group of ["Config", "Receiver", "Pusher"]) {
+    const groupChecks = report.checks.filter((c) => CHECK_GROUP[c.name] === group);
+    if (groupChecks.length === 0) continue;
+    lines.push(`  ${group}:`);
+    for (const c of groupChecks) {
+      lines.push(`    ${mark(c.ok)} ${shortName(c.name)}: ${c.detail}`);
+    }
+    lines.push("");
+  }
+  const actionable = [
+    ...report.checks.filter((c) => c.ok === false),
+    ...report.checks.filter((c) => c.ok === "warn")
+  ];
+  if (actionable.length === 0) {
+    lines.push("\u2192 Wake-path is healthy. Nothing to do.");
+  } else {
+    lines.push("\u2192 Next steps (in order):");
+    actionable.forEach((c, i) => {
+      lines.push(`   ${i + 1}. [${shortName(c.name)}] ${c.detail}`);
+    });
+  }
+  lines.push("");
+  lines.push(
+    "  (read-only. Enabling/restarting the daemon, plugin, or gateway is an owner step \u2014 shared infra needs the principal's word.)"
+  );
+  return lines.join("\n");
+}
+export {
+  collectHermesDoctorReport,
+  formatHermesDoctorReport,
+  hermesArtifactsPresent
+};

package/dist/index.js

@@ -1,9 +1,9 @@
 import {
   listTandemIds,
   startProxy
-} from "./chunk-ZSHCHOPL.js";
+} from "./chunk-4ATSAH7H.js";
 import "./chunk-TCWIXG5C.js";
-import "./chunk-247WFMCJ.js";
+import "./chunk-TBVJOXIR.js";
 import "./chunk-Z5LPNJQ6.js";
 import "./chunk-I67C2HYA.js";
 import "./chunk-MIEI4PLB.js";
@@ -14,7 +14,7 @@ import "./chunk-5DHIUN73.js";
 import "./chunk-FJUAMJHU.js";
 import "./chunk-PPTKGWFF.js";
 import "./chunk-XJEBJIQE.js";
-import "./chunk-KNEJTD6G.js";
+import "./chunk-SRLD2UY7.js";
 export {
   listTandemIds,
   startProxy

package/dist/lib.js

@@ -13,7 +13,7 @@ import {
 import {
   GatewayClient,
   applyStableSessionId
-} from "./chunk-247WFMCJ.js";
+} from "./chunk-TBVJOXIR.js";
 import {
   deriveStableSessionId
 } from "./chunk-Z5LPNJQ6.js";
@@ -32,7 +32,7 @@ import {
 } from "./chunk-6G6YYST6.js";
 import "./chunk-U5HHHRXA.js";
 import "./chunk-PPTKGWFF.js";
-import "./chunk-KNEJTD6G.js";
+import "./chunk-SRLD2UY7.js";
 export {
   AuthModule,
   GatewayClient,

package/dist/plugins/hermes/adapter.py

@@ -154,8 +154,13 @@ class KojeeTandemAdapter(BasePlatformAdapter):
 
     # ── Connection lifecycle ────────────────────────────────────────────
 
-    async def connect(self) -> bool:
-        """Start the loopback webhook listener the kojee-mcp daemon POSTs to."""
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        """Start the loopback webhook listener the kojee-mcp daemon POSTs to.
+
+        ``is_reconnect`` is part of the BasePlatformAdapter.connect contract
+        (the gateway's reconnection watcher calls ``connect(is_reconnect=True)``);
+        this listener is stateless per-connect so the flag is accepted and ignored.
+        """
         if not self.webhook_secret:
             logger.error("kojee-tandem: KOJEE_WEBHOOK_SECRET must be set (signed-only inbound)")
             self._set_fatal_error(

package/dist/{registry-XJ67EO22.js → registry-DKWVVXJM.js}

@@ -129,7 +129,7 @@ function createClaudeCodeDelivery() {
       const { startEventStream } = await import("./event-stream-ATKYXDBV.js");
       const { createMcpServer } = await import("./server-DU3LFS32.js");
       const { deriveDiscoveryKey } = await import("./ancestry-A2F5KQ6A.js");
-      const { resolveSharedSessionId } = await import("./cc-session-id-RURNIHHC.js");
+      const { resolveSharedSessionId } = await import("./cc-session-id-NNCZCHZZ.js");
       sweepStaleDiscovery();
       sweepStaleEventLogs();
       const projectDir = process.env["CLAUDE_PROJECT_DIR"];

package/dist/{send-cli-45RLGYIC.js → send-cli-OLNEVSBI.js}

@@ -13,7 +13,7 @@ import {
 import {
   GatewayClient,
   applyStableSessionId
-} from "./chunk-247WFMCJ.js";
+} from "./chunk-TBVJOXIR.js";
 import "./chunk-Z5LPNJQ6.js";
 import "./chunk-MIEI4PLB.js";
 import {
@@ -22,7 +22,7 @@ import {
 } from "./chunk-6G6YYST6.js";
 import "./chunk-U5HHHRXA.js";
 import "./chunk-PPTKGWFF.js";
-import "./chunk-KNEJTD6G.js";
+import "./chunk-SRLD2UY7.js";
 
 // src/tandem/send-cli.ts
 import os from "os";

package/dist/{setup-handler-44ASXYMS.js → setup-handler-DA4465VH.js}

@@ -3,9 +3,10 @@ import {
   pairSlotFor,
   reconcileConnectPairSlot,
   runWizard
-} from "./chunk-XPIW4N55.js";
+} from "./chunk-CPOK642I.js";
 import "./chunk-6XWTUDWW.js";
 import "./chunk-E6WMFMM2.js";
+import "./chunk-GEGUWQYT.js";
 import {
   isWizardRuntime
 } from "./chunk-77HWBSRH.js";

package/dist/{stop-hook-N6TX4YQT.js → stop-hook-4MNOSDCB.js}

@@ -1,7 +1,7 @@
 import "./chunk-XLKGPGZT.js";
 import {
   resolveHookDiscovery
-} from "./chunk-WBXU27BF.js";
+} from "./chunk-3P24YPR7.js";
 import {
   readHookStdin
 } from "./chunk-LSUB6QMP.js";
@@ -21,7 +21,7 @@ import {
   buildMonitorNudge
 } from "./chunk-FJUAMJHU.js";
 import "./chunk-XJEBJIQE.js";
-import "./chunk-KNEJTD6G.js";
+import "./chunk-SRLD2UY7.js";
 
 // src/hooks/stop-hook.ts
 import fs from "fs";

package/dist/{user-prompt-submit-hook-DTXXFDSD.js → user-prompt-submit-hook-44N6SCNJ.js}

@@ -1,6 +1,6 @@
 import {
   resolveHookDiscovery
-} from "./chunk-WBXU27BF.js";
+} from "./chunk-3P24YPR7.js";
 import {
   readHookStdin
 } from "./chunk-LSUB6QMP.js";
@@ -13,7 +13,7 @@ import {
 import "./chunk-67F67AQ6.js";
 import "./chunk-U5HHHRXA.js";
 import "./chunk-XJEBJIQE.js";
-import "./chunk-KNEJTD6G.js";
+import "./chunk-SRLD2UY7.js";
 
 // src/hooks/user-prompt-submit-hook.ts
 async function runUserPromptSubmitHook() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kojee-mcp",
-  "version": "0.7.4",
+  "version": "0.7.5-beta.1",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -35,6 +35,7 @@
     "ps-list": "^8.1.1",
     "ulidx": "^2.3.0",
     "undici": "^8.5.0",
+    "yaml": "^2.9.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {