kojee-mcp 0.7.5-staging.5 → 0.7.5-staging.7

package/README.md

@@ -574,6 +574,22 @@ npm run dev:stub
 # Stub listens on http://localhost:8765
 ```
 
+## Releases & staging versioning
+
+Two channels, and one rule that keeps them clean:
+
+- **`latest` (production)** — a **manual** release off `main` (`npm publish` → `latest`, or promote a verified staging build via `npm dist-tag add kojee-mcp@<ver> latest`).
+- **`staging` (pre-release)** — **automatic** on every merge to the `staging` branch, via `.github/workflows/publish-staging.yml`, published under the `staging` dist-tag (never touches `latest`).
+
+**How the staging version is computed** (`scripts/next-staging-version.mjs`):
+
+1. **base** = `package.json.version` with its **PATCH bumped once** — e.g. `0.7.4` → `0.7.5`.
+2. **counter** = `1 + highest existing <base>-staging.N on npm`. This is **per-base**, so it **RESETS to 1 automatically when the base progresses** (a brand-new base has no prior `-staging.N`).
+
+So a run yields e.g. `0.7.5-staging.6`, and once `0.7.5` ships to `latest` and `package.json` moves to `0.7.5`, the next staging build resets to `0.7.6-staging.1`.
+
+> ⚠️ **THE RULE: `package.json.version` must hold the LAST STABLE version — never a `-staging`/`-beta` pre-release.** The CI bumps the patch itself; if the file already carries the *next* version (or a `-beta` whose stable part is the next version), the base **double-bumps**. That is exactly how a `0.7.5-beta.1` base once published `0.7.6-staging.6` instead of the intended `0.7.5-staging.6`. Cutting a stable release is the *only* time `package.json.version` advances, and it advances to the version you just shipped to `latest`.
+
 ## How Approvals Work
 
 Some tools are governed by approval policies configured in the Kojee dashboard. When an agent calls a governed tool:

package/dist/{chunk-FJUAMJHU.js → chunk-O4JQY7IF.js}

@@ -1,7 +1,32 @@
+// src/version.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var FALLBACK_VERSION = "0.0.0-unknown";
+function resolveVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const parsed = JSON.parse(
+      fs.readFileSync(path.join(here, "..", "package.json"), "utf8")
+    );
+    return typeof parsed?.version === "string" && parsed.version ? parsed.version : FALLBACK_VERSION;
+  } catch (err) {
+    process.stderr.write(
+      `kojee-mcp: could not resolve version from package.json, falling back to ${FALLBACK_VERSION}: ${String(err)}
+`
+    );
+    return FALLBACK_VERSION;
+  }
+}
+var VERSION = resolveVersion();
+
 // src/tandem/recipe.ts
 var SEND_BODY_PARAM = "body";
+function monitorPackageSpec() {
+  return VERSION && VERSION !== "0.0.0-unknown" ? `kojee-mcp@${VERSION}` : "kojee-mcp";
+}
 function buildMonitorCommand(logPath) {
-  return `npx kojee-mcp tail "${logPath}"`;
+  return `npx ${monitorPackageSpec()} tail --wake-only "${logPath}"`;
 }
 function buildMonitorSpawn(logPath) {
   return `Monitor(command=\`${buildMonitorCommand(logPath)}\`, persistent=true, description="kojee Tandem events")`;
@@ -32,6 +57,7 @@ var CODEX_LISTEN_CAP_MS = 8e3;
 var CODEX_WAKE_BELL = "[kojee] Tandem events may be pending. Call tandem_pending now and drain each room it lists (tandem_messages(id, since=cursor)), then reply in the room with a normal message (kind=message \u2014 never status). If it returns none for you, ignore this.";
 
 export {
+  VERSION,
   buildMonitorSpawn,
   buildReplyRecipe,
   buildCatchUpNote,

package/dist/{chunk-4E6WMRTM.js → chunk-RTYRJAJO.js}

@@ -5,7 +5,7 @@ import {
   isPlaceholderWebhookUrl,
   removeCodexConfig,
   writeCodexConfig
-} from "./chunk-6XWTUDWW.js";
+} from "./chunk-T6QANUS2.js";
 import {
   removeOpenclawMcpServer,
   writeOpenclawMcpConfig
@@ -48,14 +48,12 @@ import {
   secureFile,
   unlinkSyncRetry
 } from "./chunk-U5HHHRXA.js";
-import {
-  VERSION
-} from "./chunk-5DHIUN73.js";
 import {
   CODEX_LISTEN_CAP_MS,
+  VERSION,
   buildCondensedTandemRules,
   buildWebhookReceiverNote
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 
 // src/wizard/pair-slot.ts
 import fs from "fs";
@@ -425,7 +423,8 @@ function installBundledPayload(opts) {
 import fs5 from "fs";
 import path5 from "path";
 function daemonSourceExecCommand(spec) {
-  return `set -a; . ${spec.envFile}; set +a; exec ${spec.binPath}`;
+  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;");
@@ -571,6 +570,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
@@ -589,15 +589,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 channel plugin AND the kojee MCP server:",
-    "      systemctl --user restart hermes-gateway   (or: hermes gateway restart, or /reload-mcp)",
-    "  - verify the MCP registered:  hermes mcp test kojee   (tools appear to the agent as mcp_kojee_*)",
-    "  - the agent can now join from its own tools:  mcp_kojee_tandem_join <tandem_id>",
-    "  - verify the daemon/channel:  kojee-mcp doctor",
-    "  - if tools don't register: ensure Hermes was installed with the MCP extra",
-    '      (cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]") and re-check connect_timeout.'
+    "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",
@@ -975,7 +978,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";
@@ -1018,11 +1032,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 } : {},
@@ -1035,6 +1051,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("");

package/dist/{chunk-A4IOKD4Z.js → chunk-S35ZIVOL.js}

@@ -1,12 +1,10 @@
 import {
-  VERSION
-} from "./chunk-5DHIUN73.js";
-import {
+  VERSION,
   buildCatchUpNote,
   buildCondensedTandemRules,
   buildMonitorSpawn,
   buildReplyRecipe
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 import {
   translateToolCallResult
 } from "./chunk-PPTKGWFF.js";

package/dist/{chunk-6XWTUDWW.js → chunk-T6QANUS2.js}

@@ -14,7 +14,7 @@ import {
 } from "./chunk-U5HHHRXA.js";
 import {
   VERSION
-} from "./chunk-5DHIUN73.js";
+} from "./chunk-O4JQY7IF.js";
 
 // src/wizard/codex-config.ts
 import fs from "fs";

package/dist/{chunk-526UIEAL.js → chunk-TUDC4GY5.js}

@@ -1,6 +1,6 @@
 import {
   claudeCodeAdapter
-} from "./chunk-TCWIXG5C.js";
+} from "./chunk-XYDNRVOU.js";
 import {
   GatewayClient,
   applyStableSessionId
@@ -11,7 +11,7 @@ import {
 import {
   createMcpServer,
   startMcpServer
-} from "./chunk-A4IOKD4Z.js";
+} from "./chunk-S35ZIVOL.js";
 import {
   findClaudeAncestorPid
 } from "./chunk-XJEBJIQE.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-DKWVVXJM.js");
+  const { selectDelivery } = await import("./registry-ACVPVDCS.js");
   const delivery = selectDelivery(adapter.runtime, {
     supportsChannels: adapter.supportsChannels,
     // Per-window delivered mirror for the tandem_pending tool (codex only —
@@ -338,8 +338,15 @@ async function startProxy(config) {
     }
     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-TCWIXG5C.js → chunk-XYDNRVOU.js}

@@ -1,6 +1,6 @@
 import {
   buildReplyRecipe
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 
 // src/adapters/claude-code.ts
 function computeSeverity(event) {

package/dist/cli.js

@@ -4,8 +4,8 @@ import {
 } from "./chunk-EIAUW6KO.js";
 import {
   startProxy
-} from "./chunk-526UIEAL.js";
-import "./chunk-TCWIXG5C.js";
+} from "./chunk-TUDC4GY5.js";
+import "./chunk-XYDNRVOU.js";
 import {
   pairedConfigPath
 } from "./chunk-5SZHXYPK.js";
@@ -18,11 +18,10 @@ import {
   deriveKeystorePath
 } from "./chunk-6G6YYST6.js";
 import "./chunk-U5HHHRXA.js";
-import "./chunk-A4IOKD4Z.js";
+import "./chunk-S35ZIVOL.js";
 import {
   VERSION
-} from "./chunk-5DHIUN73.js";
-import "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 import "./chunk-PPTKGWFF.js";
 import "./chunk-XJEBJIQE.js";
 import "./chunk-SRLD2UY7.js";
@@ -48,7 +47,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-YYBLFRDP.js");
+  const { runConnect } = await import("./connect-handler-W7EAIU4R.js");
   const result = await runConnect({
     code,
     runtime: opts.runtime,
@@ -63,7 +62,7 @@ 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-4MNOSDCB.js");
+    const { runStopHook } = await import("./stop-hook-Y34L3RCR.js");
     await runStopHook();
     process.exit(0);
   } else if (opts.type === "user-prompt-submit") {
@@ -71,11 +70,11 @@ program.command("hook").description("Run a kojee MCP hook script (called by Clau
     await runUserPromptSubmitHook();
     process.exit(0);
   } else if (opts.type === "codex-stop") {
-    const { runCodexStopHook } = await import("./codex-stop-hook-32W4BIOM.js");
+    const { runCodexStopHook } = await import("./codex-stop-hook-M3LEWCNP.js");
     await runCodexStopHook();
     process.exit(0);
   } else if (opts.type === "codex-prompt-submit") {
-    const { runCodexPromptSubmitHook } = await import("./codex-prompt-submit-hook-J5PZEJSK.js");
+    const { runCodexPromptSubmitHook } = await import("./codex-prompt-submit-hook-ACDZSHHC.js");
     await runCodexPromptSubmitHook();
     process.exit(0);
   } else {
@@ -114,17 +113,20 @@ program.command("send <tandem_id>").description(
   process.stdout.write(JSON.stringify(envelope) + "\n");
   process.exit(exitCode);
 });
-program.command("tail <path>").description("Stream a file's contents and follow appends (portable replacement for `tail -F`)").action(async (filePath) => {
-  const { runTail } = await import("./tail-stream-G4WGTXDS.js");
+program.command("tail <path>").description("Stream a file's contents and follow appends (portable replacement for `tail -F`)").option(
+  "--wake-only",
+  "Suppress routine heartbeat warn/recover telemetry; surface only a sustained stream outage"
+).action(async (filePath, opts) => {
+  const { runTail } = await import("./tail-stream-HG4BKJOG.js");
   try {
-    await runTail(filePath);
+    await runTail(filePath, { wakeOnly: opts.wakeOnly === true });
   } catch (err) {
     console.error("[kojee-mcp tail] Error:", err.message);
     process.exit(1);
   }
 });
 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-NHUPLM6O.js");
+  const { runDoctor } = await import("./doctor-O7MLJEMO.js");
   const code = await runDoctor();
   process.exit(code);
 });
@@ -143,7 +145,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-6BDICX5F.js");
+    const { runSetup, resolvePairCode } = await import("./setup-handler-6T7Q6DYQ.js");
     const pairCode = resolvePairCode(opts);
     const result = await runSetup({
       verb,

package/dist/{codex-prompt-submit-hook-J5PZEJSK.js → codex-prompt-submit-hook-ACDZSHHC.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-IZN7IZPW.js";
 import {
   CODEX_WAKE_BELL
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 
 // src/hooks/codex-prompt-submit-hook.ts
 function buildCodexPromptSubmitOutput() {

package/dist/{codex-stop-hook-32W4BIOM.js → codex-stop-hook-M3LEWCNP.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-IZN7IZPW.js";
 import {
   CODEX_WAKE_BELL
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 
 // src/hooks/codex-stop-hook.ts
 import fs from "fs";

package/dist/{connect-handler-YYBLFRDP.js → connect-handler-W7EAIU4R.js}

@@ -2,8 +2,8 @@ import {
   DEFAULT_BROKER_URL,
   reconcileConnectPairSlot,
   runWizard
-} from "./chunk-4E6WMRTM.js";
-import "./chunk-6XWTUDWW.js";
+} from "./chunk-RTYRJAJO.js";
+import "./chunk-T6QANUS2.js";
 import "./chunk-E6WMFMM2.js";
 import "./chunk-GEGUWQYT.js";
 import "./chunk-77HWBSRH.js";
@@ -30,8 +30,7 @@ import {
   deriveKeystorePath
 } from "./chunk-6G6YYST6.js";
 import "./chunk-U5HHHRXA.js";
-import "./chunk-5DHIUN73.js";
-import "./chunk-FJUAMJHU.js";
+import "./chunk-O4JQY7IF.js";
 
 // src/wizard/connect-handler.ts
 import os from "os";

package/dist/{doctor-NHUPLM6O.js → doctor-O7MLJEMO.js}

@@ -18,7 +18,7 @@ import "./chunk-U5HHHRXA.js";
 import {
   buildMonitorSpawn,
   buildReplyRecipe
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 import {
   deriveDiscoveryKey,
   findClaudeAncestorPid
@@ -354,7 +354,7 @@ function formatDoctorReport(report) {
 async function runDoctor() {
   const { readRecordedRuntime } = await import("./runtime-record-OXRLTOLC.js");
   if (readRecordedRuntime() === "codex") {
-    const { collectCodexDoctorReport, formatCodexDoctorReport } = await import("./doctor-codex-PJFWIABF.js");
+    const { collectCodexDoctorReport, formatCodexDoctorReport } = await import("./doctor-codex-D4BOWIAA.js");
     const report2 = collectCodexDoctorReport();
     console.error(formatCodexDoctorReport(report2));
     return report2.verdict === "broken" ? 1 : 0;
@@ -365,7 +365,7 @@ async function runDoctor() {
     console.error(formatOpenclawDoctorReport(report2));
     return report2.verdict === "broken" ? 1 : 0;
   }
-  const { hermesArtifactsPresent, collectHermesDoctorReport, formatHermesDoctorReport } = await import("./doctor-hermes-7N7O422Y.js");
+  const { hermesArtifactsPresent, collectHermesDoctorReport, formatHermesDoctorReport } = await import("./doctor-hermes-WLDI4R6P.js");
   if (hermesArtifactsPresent()) {
     const hermesReport = collectHermesDoctorReport();
     console.error(formatHermesDoctorReport(hermesReport));

package/dist/{doctor-codex-PJFWIABF.js → doctor-codex-D4BOWIAA.js}

@@ -2,7 +2,7 @@ import {
   defaultCodexConfigPath,
   defaultCodexHooksPath,
   isPlaceholderWebhookUrl
-} from "./chunk-6XWTUDWW.js";
+} from "./chunk-T6QANUS2.js";
 import "./chunk-TMCNB4JH.js";
 import "./chunk-D6JKFJ6A.js";
 import {
@@ -16,11 +16,9 @@ import {
 } from "./chunk-V5VZPYMZ.js";
 import "./chunk-U5HHHRXA.js";
 import {
+  CODEX_LISTEN_CAP_MS,
   VERSION
-} from "./chunk-5DHIUN73.js";
-import {
-  CODEX_LISTEN_CAP_MS
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 
 // src/doctor-codex.ts
 import fs from "fs";

package/dist/{doctor-hermes-7N7O422Y.js → doctor-hermes-WLDI4R6P.js}

@@ -103,6 +103,27 @@ function readChildEnv(configText) {
 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");
@@ -186,6 +207,7 @@ 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);
@@ -200,6 +222,7 @@ function collectHermesDoctorReport(deps = {}) {
   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) {
@@ -293,6 +316,46 @@ function collectHermesDoctorReport(deps = {}) {
       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(
@@ -305,12 +368,38 @@ function collectHermesDoctorReport(deps = {}) {
   } 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 \u2014 no wakes are being pushed. Enable+start it (`systemctl --user enable --now kojee-hermes`) \u2014 shared infra, so the principal's call."
+      `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));
@@ -331,12 +420,13 @@ function collectHermesDoctorReport(deps = {}) {
       `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 the Hermes gateway (kojee-tandem plugin) receiver may be down; restart the gateway to load the plugin.`
+      `nothing is listening on ${listenHost}:${listenPort} \u2014 ${fix}.`
     );
   }
   if (childEnv === null) {
@@ -425,20 +515,61 @@ function collectHermesDoctorReport(deps = {}) {
   }
   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 (hermes) \u2014 verdict: ${report.verdict.toUpperCase()}`);
-  lines.push("");
-  lines.push("  Wake mode: kojee-hermes daemon \u2192 HMAC-signed webhook \u2192 loopback receiver plugin.");
-  lines.push("  (Daemon streams the SSE + POSTs wakes; the tools-only MCP child never delivers.)");
+  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 c of report.checks) {
-    lines.push(`  ${mark(c.ok)} ${c.name}: ${c.detail}`);
+  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(
-    "NOTE: read-only. Enabling/bouncing the kojee-hermes service (or the gateway) is an owner step \u2014 shared infra needs the principal's word."
+    "  (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");
 }

package/dist/index.js

@@ -1,17 +1,16 @@
 import {
   listTandemIds,
   startProxy
-} from "./chunk-526UIEAL.js";
-import "./chunk-TCWIXG5C.js";
+} from "./chunk-TUDC4GY5.js";
+import "./chunk-XYDNRVOU.js";
 import "./chunk-TBVJOXIR.js";
 import "./chunk-Z5LPNJQ6.js";
 import "./chunk-I67C2HYA.js";
 import "./chunk-MIEI4PLB.js";
 import "./chunk-6G6YYST6.js";
 import "./chunk-U5HHHRXA.js";
-import "./chunk-A4IOKD4Z.js";
-import "./chunk-5DHIUN73.js";
-import "./chunk-FJUAMJHU.js";
+import "./chunk-S35ZIVOL.js";
+import "./chunk-O4JQY7IF.js";
 import "./chunk-PPTKGWFF.js";
 import "./chunk-XJEBJIQE.js";
 import "./chunk-SRLD2UY7.js";

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-DKWVVXJM.js → registry-ACVPVDCS.js}

@@ -13,12 +13,11 @@ import {
 } from "./chunk-IZN7IZPW.js";
 import {
   claudeCodeAdapter
-} from "./chunk-TCWIXG5C.js";
-import "./chunk-A4IOKD4Z.js";
+} from "./chunk-XYDNRVOU.js";
+import "./chunk-S35ZIVOL.js";
 import {
   VERSION
-} from "./chunk-5DHIUN73.js";
-import "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 import "./chunk-PPTKGWFF.js";
 
 // src/delivery/lib/fanout.ts
@@ -127,7 +126,7 @@ function createClaudeCodeDelivery() {
       const { resolveWebhookConfig } = await import("./webhook-config-O4WMQ532.js");
       const { createWebhookSink } = await import("./webhook-sink-N6AUTFL3.js");
       const { startEventStream } = await import("./event-stream-ATKYXDBV.js");
-      const { createMcpServer } = await import("./server-DU3LFS32.js");
+      const { createMcpServer } = await import("./server-RK4UK6SP.js");
       const { deriveDiscoveryKey } = await import("./ancestry-A2F5KQ6A.js");
       const { resolveSharedSessionId } = await import("./cc-session-id-NNCZCHZZ.js");
       sweepStaleDiscovery();
@@ -324,7 +323,7 @@ function createWebhookDelivery(name, pendingLedger) {
       const { createWebhookSink } = await import("./webhook-sink-N6AUTFL3.js");
       const { resubscribeMemberships } = await import("./resubscribe-G5OGDZJD.js");
       const { startEventStream } = await import("./event-stream-ATKYXDBV.js");
-      const { createMcpServer } = await import("./server-DU3LFS32.js");
+      const { createMcpServer } = await import("./server-RK4UK6SP.js");
       sweepStaleEventLogs();
       eventLog = startEventLog({
         key: ctx.instanceKey,
@@ -518,7 +517,7 @@ function createOpenclawDelivery(deps = {}) {
       const { startEventLog, sweepStaleEventLogs } = await import("./event-log-2NBJEIEP.js");
       const { resubscribeMemberships } = await import("./resubscribe-G5OGDZJD.js");
       const { startEventStream } = await import("./event-stream-ATKYXDBV.js");
-      const { createMcpServer } = await import("./server-DU3LFS32.js");
+      const { createMcpServer } = await import("./server-RK4UK6SP.js");
       sweepStaleEventLogs();
       eventLog = startEventLog({
         key: ctx.instanceKey,

package/dist/{server-DU3LFS32.js → server-RK4UK6SP.js}

@@ -5,9 +5,8 @@ import {
   executeToolCall,
   extractDrainCursor,
   startMcpServer
-} from "./chunk-A4IOKD4Z.js";
-import "./chunk-5DHIUN73.js";
-import "./chunk-FJUAMJHU.js";
+} from "./chunk-S35ZIVOL.js";
+import "./chunk-O4JQY7IF.js";
 import "./chunk-PPTKGWFF.js";
 export {
   buildChannelInstructions,

package/dist/{setup-handler-6BDICX5F.js → setup-handler-6T7Q6DYQ.js}

@@ -3,8 +3,8 @@ import {
   pairSlotFor,
   reconcileConnectPairSlot,
   runWizard
-} from "./chunk-4E6WMRTM.js";
-import "./chunk-6XWTUDWW.js";
+} from "./chunk-RTYRJAJO.js";
+import "./chunk-T6QANUS2.js";
 import "./chunk-E6WMFMM2.js";
 import "./chunk-GEGUWQYT.js";
 import {
@@ -26,8 +26,7 @@ import "./chunk-I67C2HYA.js";
 import "./chunk-MIEI4PLB.js";
 import "./chunk-6G6YYST6.js";
 import "./chunk-U5HHHRXA.js";
-import "./chunk-5DHIUN73.js";
-import "./chunk-FJUAMJHU.js";
+import "./chunk-O4JQY7IF.js";
 
 // src/wizard/setup-handler.ts
 var SETUP_SUPPORTED_RUNTIMES = ["claude-code", "codex"];

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

@@ -19,7 +19,7 @@ import "./chunk-67F67AQ6.js";
 import "./chunk-U5HHHRXA.js";
 import {
   buildMonitorNudge
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-O4JQY7IF.js";
 import "./chunk-XJEBJIQE.js";
 import "./chunk-SRLD2UY7.js";
 

package/dist/{tail-stream-G4WGTXDS.js → tail-stream-HG4BKJOG.js}

@@ -16,6 +16,7 @@ import "./chunk-U5HHHRXA.js";
 
 // src/tail-stream.ts
 import fs from "fs";
+import { spawn } from "child_process";
 var STATUS_LINE_RE = new RegExp(`^\\[[^\\]]*\\] ${STATUS_LINE_PREFIX} (.*)$`);
 var HEARTBEAT_FIELDS_RE = /(^|\s)status=heartbeat(\s|$)/;
 var ROTATED_FIELDS_RE = /(^|\s)status=rotated(\s|$)/;
@@ -29,6 +30,7 @@ var TAIL_STALE_FLOOR_MS = envInt(
 );
 var STALE_CHECK_INTERVAL_MS = envInt("KOJEE_TAIL_CHECK_MS", 5e3);
 var TAIL_REWARN_AFTER_MS = 30 * 6e4;
+var SUSTAINED_STALE_MS = envInt("KOJEE_TAIL_SUSTAINED_MS", TAIL_REWARN_AFTER_MS);
 var TAIL_HEALTHY_RESET_MS = 30 * 6e4;
 var TAIL_BACKOFF_CAP_CYCLES = 3;
 function envInt(name, fallback) {
@@ -99,9 +101,13 @@ function createStallDetector(startNow, options = {}) {
     }
   };
 }
-async function runTail(messagesPath) {
+async function runTail(messagesPath, opts = {}) {
+  const wakeOnly = opts.wakeOnly === true;
   const statusPath = statusLogPath(messagesPath);
-  const detector = createStallDetector(Date.now(), { floorMs: TAIL_STALE_FLOOR_MS });
+  const detector = createStallDetector(Date.now(), {
+    floorMs: TAIL_STALE_FLOOR_MS,
+    rewarnAfterMs: SUSTAINED_STALE_MS
+  });
   const heartbeatPath = monitorHeartbeatPath(messagesPath);
   const touchHeartbeat = () => {
     const now = /* @__PURE__ */ new Date();
@@ -116,7 +122,7 @@ async function runTail(messagesPath) {
   };
   let lastCursor = null;
   function onMessageLine(line) {
-    if (detector.onLife(Date.now())?.kind === "recovered") {
+    if (detector.onLife(Date.now())?.kind === "recovered" && !wakeOnly) {
       process.stdout.write(
         "[kojee] stream recovered \u2014 events flowing again (recovery is automatic; no action needed).\n"
       );
@@ -133,7 +139,7 @@ async function runTail(messagesPath) {
     if (HEARTBEAT_FIELDS_RE.test(fields)) {
       detector.onHeartbeat(now);
     }
-    if (detector.onLife(now)?.kind === "recovered") {
+    if (detector.onLife(now)?.kind === "recovered" && !wakeOnly) {
       process.stdout.write(
         "[kojee] stream recovered \u2014 heartbeats resumed (the stall was transient, likely idle-period timing or brief host load; no action needed).\n"
       );
@@ -149,7 +155,12 @@ async function runTail(messagesPath) {
     }
   }
   const followers = [
-    makeFollower(messagesPath, onMessageLine, touchHeartbeat),
+    // MESSAGES (wake-critical) — prefer the OS `tail -F` follower where the
+    // platform has one; it delegates file-following to the battle-tested system
+    // binary instead of the Node fs.watch/poll tailer. STATUS (telemetry) stays
+    // on the Node follower: its startup-backlog seeding boundary (statusSeeded)
+    // is clean to detect only when we control the drain. See makeMessagesFollower.
+    makeMessagesFollower(messagesPath, onMessageLine, touchHeartbeat),
     makeFollower(statusPath, onStatusLine, touchHeartbeat)
   ];
   void Promise.all([
@@ -171,6 +182,7 @@ async function runTail(messagesPath) {
       );
       return;
     }
+    if (wakeOnly) return;
     const thresholdS = Math.round((signal.thresholdMs ?? 0) / 1e3);
     process.stdout.write(
       `[kojee] WARNING: no events or heartbeat for ${silentS}s (threshold ${thresholdS}s) \u2014 stream may be dead, but this is often benign (idle stream, or brief host load delaying heartbeats) and recovery is automatic; if it persists, run \`npx kojee-mcp doctor\`.
@@ -273,11 +285,99 @@ function makeFollower(filePath, onLine, onActivity) {
     }
   };
 }
+function osTailAvailable() {
+  const override = (process.env.KOJEE_TAIL_IMPL ?? "").trim().toLowerCase();
+  if (override === "os") return true;
+  if (override === "node") return false;
+  return process.platform !== "win32";
+}
+function makeMessagesFollower(filePath, onLine, onActivity) {
+  if (!osTailAvailable()) return makeFollower(filePath, onLine, onActivity);
+  return makeTailFollower(
+    filePath,
+    onLine,
+    onActivity,
+    () => makeFollower(filePath, onLine, onActivity)
+  );
+}
+function makeTailFollower(filePath, onLine, onActivity, fallback) {
+  let child = null;
+  let heir = null;
+  let hbTimer = null;
+  let buffer = "";
+  let stopped = false;
+  let handedOff = false;
+  function emit(chunk) {
+    onActivity();
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      onLine(buffer.slice(0, nl));
+      buffer = buffer.slice(nl + 1);
+    }
+  }
+  function handOff() {
+    if (stopped || handedOff) return;
+    handedOff = true;
+    if (hbTimer) {
+      clearInterval(hbTimer);
+      hbTimer = null;
+    }
+    if (child) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+      child = null;
+    }
+    heir = fallback();
+    void heir.start().catch(() => {
+    });
+  }
+  return {
+    async start() {
+      try {
+        child = spawn("tail", ["-n", "+1", "-F", filePath], {
+          stdio: ["ignore", "pipe", "ignore"]
+        });
+      } catch {
+        handOff();
+        return;
+      }
+      child.on("error", () => handOff());
+      child.on("exit", () => {
+        if (!stopped) handOff();
+      });
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (d) => emit(d));
+      onActivity();
+      hbTimer = setInterval(onActivity, 1e3);
+    },
+    stop() {
+      stopped = true;
+      if (hbTimer) {
+        clearInterval(hbTimer);
+        hbTimer = null;
+      }
+      if (child) {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+        }
+        child = null;
+      }
+      if (heir) heir.stop();
+    }
+  };
+}
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 export {
   createStallDetector,
   makeFollower,
+  makeMessagesFollower,
+  makeTailFollower,
+  osTailAvailable,
   runTail
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kojee-mcp",
-  "version": "0.7.5-staging.5",
+  "version": "0.7.5-staging.7",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/dist/chunk-5DHIUN73.js

@@ -1,25 +0,0 @@
-// src/version.ts
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-var FALLBACK_VERSION = "0.0.0-unknown";
-function resolveVersion() {
-  try {
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    const parsed = JSON.parse(
-      fs.readFileSync(path.join(here, "..", "package.json"), "utf8")
-    );
-    return typeof parsed?.version === "string" && parsed.version ? parsed.version : FALLBACK_VERSION;
-  } catch (err) {
-    process.stderr.write(
-      `kojee-mcp: could not resolve version from package.json, falling back to ${FALLBACK_VERSION}: ${String(err)}
-`
-    );
-    return FALLBACK_VERSION;
-  }
-}
-var VERSION = resolveVersion();
-
-export {
-  VERSION
-};