kojee-mcp 0.7.5-staging.1 → 0.7.5-staging.10

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.
@@ -428,12 +431,14 @@ constant beside it):
   ```
   { type, id, tandem_id, cursor, time,
     from{ member_id, principal, agent_id?, session_id?, displayname },
-    kind, content{ body, format? }, mentions?, reply_to?, severity? }
+    kind, content{ body, format? }, mentions?, reply_to?, severity?, wake?, wake_reason? }
   ```
 
   `from.session_id` and `severity` are present only when the wire carried them.
-  There is no `sender` object — the body is fully normalized and carries
-  `from.principal`.
+  `wake` is the backend's per-subscriber wake stamp (always `true` here — the sink
+  fires only for delivered wakes) and `wake_reason` names why it woke (e.g.
+  `direct`/`mention`), present when the backend stamped it. There is no `sender`
+  object — the body is fully normalized and carries `from.principal`.
 - **Verify** the `X-Kojee-Signature` header: it is the hex-encoded SHA-256 HMAC
   of the **raw request-body bytes**, keyed by `KOJEE_WEBHOOK_SECRET`. Recompute
   over the received bytes (before any re-serialization) and timing-safe compare;
@@ -571,6 +576,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/{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-CUOJHP2S.js → chunk-5XOO52G5.js}

@@ -11,6 +11,7 @@ var STALE_FLOOR_MS = 9e4;
 var STALE_INTERVAL_MULTIPLIER = 3;
 var STALE_CHECK_INTERVAL_MS = 5e3;
 var UNARMED_FALLBACK_MS = 12 * 6e4;
+var CONNECT_TIMEOUT_MS = 3e4;
 var UNDICI_DEFAULT_BODY_TIMEOUT_MS = 3e5;
 function createAdaptiveWatchdog(options = {}) {
   const floorMs = options.floorMs ?? STALE_FLOOR_MS;
@@ -165,10 +166,16 @@ async function startEventStream(opts) {
 }
 async function connectAndConsume(opts, cursors, controller, isReconnect, state, dispatcher, onCursor, onOpen) {
   const mapSince = cursors.size > 0 ? serializeCursorMap(cursors) : null;
-  let res = await openStream(opts, controller, mapSince, dispatcher);
-  if (res.status === 400 && mapSince !== null) {
-    console.error("[event-stream] per-room ?since rejected (400) \u2014 falling back to bare cursor");
-    res = await openStream(opts, controller, String(Math.min(...cursors.values())), dispatcher);
+  const connectTimer = setTimeout(() => controller.abort(), CONNECT_TIMEOUT_MS);
+  let res;
+  try {
+    res = await openStream(opts, controller, mapSince, dispatcher);
+    if (res.status === 400 && mapSince !== null) {
+      console.error("[event-stream] per-room ?since rejected (400) \u2014 falling back to bare cursor");
+      res = await openStream(opts, controller, String(Math.min(...cursors.values())), dispatcher);
+    }
+  } finally {
+    clearTimeout(connectTimer);
   }
   if (!res.ok) throw new Error(`SSE connect failed: ${res.status}`);
   if (!res.body) throw new Error("SSE response has no body");
@@ -250,12 +257,14 @@ async function consumeSse(body, opts, controller, state, onCursor) {
           }
           continue;
         }
-        if (evt.event === "message" || evt.event === "state_change") {
+        {
           try {
             const raw = JSON.parse(evt.data);
             const parsed = normalizeBackendEvent(raw, evt.event);
-            onCursor(parsed.tandem_id, parsed.cursor);
-            if (parsed.wake === false) continue;
+            if (typeof parsed.cursor === "number") {
+              onCursor(parsed.tandem_id, parsed.cursor);
+            }
+            if (parsed.wake !== true) continue;
             if (opts.delivery) {
               try {
                 await opts.delivery.deliver(parsed);
@@ -448,6 +457,7 @@ function normalizeBackendEvent(raw, sseEventType) {
 export {
   undiciFetch,
   UNARMED_FALLBACK_MS,
+  CONNECT_TIMEOUT_MS,
   UNDICI_DEFAULT_BODY_TIMEOUT_MS,
   createAdaptiveWatchdog,
   createBackoffController,

package/dist/{chunk-FJUAMJHU.js → chunk-BAPFHC36.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")`;
@@ -21,17 +46,18 @@ function buildCondensedTandemRules() {
 function buildMonitorNudge(logPath) {
   return `[kojee] Tandem events are being logged but no Monitor is reading them \u2014 you may be missing wake notifications. Spawn the watcher once: ${buildMonitorSpawn(logPath)}. Then ${buildReplyRecipe()}.`;
 }
-var WEBHOOK_BODY_SHAPE = "{ type, id, tandem_id, cursor, time, from{ member_id, principal, agent_id?, session_id?, displayname }, kind, content{ body, format? }, mentions?, reply_to?, severity? }";
+var WEBHOOK_BODY_SHAPE = "{ type, id, tandem_id, cursor, time, from{ member_id, principal, agent_id?, session_id?, displayname }, kind, content{ body, format? }, mentions?, reply_to?, severity?, wake?, wake_reason? }";
 function buildWebhookReceiverNote(sig) {
   const header = sig?.header ?? "X-Kojee-Signature";
   const prefix = sig?.prefix ?? "";
   const digestDesc = prefix ? `the literal prefix \`${prefix}\` followed by the hex-encoded SHA-256 HMAC` : "the hex-encoded SHA-256 HMAC";
-  return "Webhook sink (optional, OFF unless KOJEE_WEBHOOK_URL + KOJEE_WEBHOOK_SECRET are set): the proxy POSTs every Tandem event as JSON to your endpoint. The body is the canonical normalized TandemEvent \u2014 " + WEBHOOK_BODY_SHAPE + ` \u2014 where from.session_id and severity are present only when the wire carried them (the body is fully normalized: it carries from.principal, never the raw backend sender envelope). To build a receiver: (1) verify the ${header} header \u2014 it is ${digestDesc} of the RAW request body bytes keyed by your KOJEE_WEBHOOK_SECRET; recompute over the received bytes and timing-safe compare, reject mismatches. (2) Dedupe by message_id \u2014 the body's \`id\`, also in the X-Kojee-Delivery header: delivery is AT-LEAST-ONCE (the proxy replays backlog from the cursor on restart), so the same event may arrive more than once \u2014 there is no exactly-once promise.`;
+  return "Webhook sink (optional, OFF unless KOJEE_WEBHOOK_URL + KOJEE_WEBHOOK_SECRET are set): the proxy POSTs every Tandem event as JSON to your endpoint. The body is the canonical normalized TandemEvent \u2014 " + WEBHOOK_BODY_SHAPE + ` \u2014 where from.session_id and severity are present only when the wire carried them (the body is fully normalized: it carries from.principal, never the raw backend sender envelope). \`wake\` is the backend's per-subscriber wake stamp (always true here \u2014 the sink fires only for delivered wakes) and \`wake_reason\` names WHY it woke (e.g. direct/mention), present when the backend stamped it. To build a receiver: (1) verify the ${header} header \u2014 it is ${digestDesc} of the RAW request body bytes keyed by your KOJEE_WEBHOOK_SECRET; recompute over the received bytes and timing-safe compare, reject mismatches. (2) Dedupe by message_id \u2014 the body's \`id\`, also in the X-Kojee-Delivery header: delivery is AT-LEAST-ONCE (the proxy replays backlog from the cursor on restart), so the same event may arrive more than once \u2014 there is no exactly-once promise.`;
 }
 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-COM6435C.js

@@ -0,0 +1,65 @@
+// src/hooks/hook-command.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function npxHookCommand(type) {
+  return `npx -y kojee-mcp hook --type=${type}`;
+}
+var NPX_CACHE_RE = /[\\/]_npx[\\/]/;
+function resolveCliEntry(moduleUrl = import.meta.url) {
+  try {
+    const here = fileURLToPath(moduleUrl);
+    const candidate = path.join(path.dirname(here), "cli.js");
+    if (!fs.existsSync(candidate)) return null;
+    if (NPX_CACHE_RE.test(candidate)) return null;
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+function stableExecPath(execPath = process.execPath) {
+  const m = /^(.*)\/Cellar\/node(?:@[^/]+)?\/[^/]+\/bin\/node$/.exec(execPath);
+  if (!m || !m[1]) return execPath;
+  const alias = path.join(m[1], "bin", "node");
+  try {
+    if (!fs.existsSync(alias)) return execPath;
+    const real = fs.realpathSync(alias);
+    return /[\\/]Cellar[\\/]node(@[^/]+)?[\\/]/.test(real) ? alias : execPath;
+  } catch {
+    return execPath;
+  }
+}
+function buildHookCommand(type, opts = {}) {
+  const cliEntry = opts.cliEntry !== void 0 ? opts.cliEntry : resolveCliEntry();
+  if (!cliEntry) return npxHookCommand(type);
+  const execPath = stableExecPath(opts.execPath ?? process.execPath);
+  return `"${execPath}" "${cliEntry}" hook --type=${type}`;
+}
+var PINNED_HOOK_RE = /^"[^"]+" "[^"]+" hook --type=(stop|user-prompt-submit|codex-stop|codex-prompt-submit)$/;
+function isKojeeHookCommand(command) {
+  if (command.startsWith("npx -y kojee-mcp hook --type=")) return true;
+  return PINNED_HOOK_RE.test(command);
+}
+function classifyHookCommand(command, deps = {}) {
+  if (command.startsWith("npx -y kojee-mcp hook --type=")) return "npx";
+  if (!PINNED_HOOK_RE.test(command)) return "foreign";
+  const paths = [...command.matchAll(/"([^"]+)"/g)].map((m) => m[1] ?? "");
+  const cliPath = paths[1] ?? "";
+  if (NPX_CACHE_RE.test(cliPath)) return "pinned-ephemeral";
+  const exists = deps.exists ?? ((p) => {
+    try {
+      return fs.existsSync(p);
+    } catch {
+      return true;
+    }
+  });
+  if (cliPath && !exists(cliPath)) return "pinned-broken";
+  return "pinned-durable";
+}
+
+export {
+  npxHookCommand,
+  buildHookCommand,
+  isKojeeHookCommand,
+  classifyHookCommand
+};

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-ZSHCHOPL.js → chunk-GLHA3DHU.js}

@@ -1,17 +1,17 @@
 import {
   claudeCodeAdapter
-} from "./chunk-TCWIXG5C.js";
+} from "./chunk-VEZJSFTM.js";
 import {
   GatewayClient,
   applyStableSessionId
-} from "./chunk-247WFMCJ.js";
+} from "./chunk-TBVJOXIR.js";
 import {
   AuthModule
 } from "./chunk-I67C2HYA.js";
 import {
   createMcpServer,
   startMcpServer
-} from "./chunk-A4IOKD4Z.js";
+} from "./chunk-MVGKYVZT.js";
 import {
   findClaudeAncestorPid
 } from "./chunk-XJEBJIQE.js";
@@ -295,9 +295,11 @@ async function startProxy(config) {
   }
   console.error(`[kojee-mcp] Tandem memberships: ${tandemMembershipCount === -1 ? "unknown" : tandemMembershipCount}`);
   let server;
-  const { selectDelivery } = await import("./registry-XJ67EO22.js");
+  const isHeadlessDaemon = !!process.env["KOJEE_HEADLESS"] || !!process.env["KOJEE_WEBHOOK_EXPECTED"];
+  const { selectDelivery } = await import("./registry-4S4YRGJY.js");
   const delivery = selectDelivery(adapter.runtime, {
     supportsChannels: adapter.supportsChannels,
+    headless: isHeadlessDaemon,
     // Per-window delivered mirror for the tandem_pending tool (codex only —
     // other runtimes' deliveries ignore this even when passed).
     ...pendingState ? { onDelivered: (e) => pendingState.noteDelivered(e.tandem_id, e.cursor) } : {}
@@ -331,10 +333,21 @@ 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"));
+  if (!isHeadlessDaemon) {
+    process.stdin.on("end", () => shutdown("stdin end"));
+    process.stdin.on("close", () => shutdown("stdin close"));
+  } else {
+    console.error(
+      "[kojee-mcp] headless daemon (KOJEE_HEADLESS / KOJEE_WEBHOOK_EXPECTED): 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"));
@@ -351,6 +364,33 @@ async function startProxy(config) {
       "[kojee-mcp] no resolvable Claude ancestor (Windows fallback) \u2014 parent-liveness watchdog not armed; stdin close/end + SIGHUP/SIGINT/SIGTERM cover shutdown, and per-window wake is preserved via the session-id discovery key."
     );
   }
+  if (isHeadlessDaemon && activeStreamHandle) {
+    const { createStreamWatchdog } = await import("./stream-watchdog-CLRS2VMV.js");
+    const { recordFlap } = await import("./flap-log-D4KG7RK4.js");
+    const handleForWatchdog = activeStreamHandle;
+    const bootAt = Date.now();
+    const streamWatchdog = createStreamWatchdog({
+      getState: () => {
+        const s = handleForWatchdog.getState();
+        return { connected: s.connected, lastEventAt: s.lastEventAt };
+      },
+      onUnhealthy: ({ disconnectedForMs, reason }) => {
+        recordFlap({
+          ts: Date.now(),
+          instanceKey,
+          reason,
+          disconnectedForMs,
+          uptimeMs: Date.now() - bootAt
+        });
+        console.error(
+          `[kojee-mcp] stream-liveness watchdog: ${reason} \u2014 self-exiting(1); the service manager (Restart=always) will start a fresh process. Repeated exits are recorded and surfaced by \`kojee-mcp doctor\` (flap detection).`
+        );
+        process.exit(1);
+      }
+    });
+    streamWatchdog.start();
+    teardownSteps.push(() => streamWatchdog.stop());
+  }
   await startMcpServer(server);
 }
 async function enrollAndDiscover(config, keystorePath, isRetry = false) {

package/dist/{chunk-NE2F5CKS.js → chunk-LKGKDZSO.js}

@@ -87,18 +87,22 @@ function createCachedOpenclawWakeResolver(opts = {}) {
     return resolution;
   };
 }
-async function postOpenclawWake(target, body, deps = {}) {
+function openclawAgentUrl(wakeUrl) {
+  return wakeUrl.replace(/\/wake$/, "/agent");
+}
+async function postOpenclawAgent(target, body, deps = {}) {
   const doFetch = deps.fetch ?? fetch;
+  const url = openclawAgentUrl(target.url);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? 4e3);
   try {
-    const res = await doFetch(target.url, {
+    const res = await doFetch(url, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${target.token}` },
-      body: JSON.stringify(body),
+      body: JSON.stringify({ name: "Kojee", wakeMode: "now", ...body }),
       signal: controller.signal
     });
-    return res.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: `wake POST ${res.status}` };
+    return res.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: `agent POST ${res.status}` };
   } catch (err) {
     return { ok: false, error: err.message };
   } finally {
@@ -109,5 +113,5 @@ async function postOpenclawWake(target, body, deps = {}) {
 export {
   resolveOpenclawWakeTarget,
   createCachedOpenclawWakeResolver,
-  postOpenclawWake
+  postOpenclawAgent
 };

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

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

package/dist/chunk-P64UR3SE.js

@@ -0,0 +1,86 @@
+import {
+  kojeeHomeDir
+} from "./chunk-SQL56SEB.js";
+
+// src/runtime/flap-log.ts
+import fs from "fs";
+import path from "path";
+var MAX_FLAP_ENTRIES = 25;
+function defaultFlapLogPath() {
+  return path.join(kojeeHomeDir(), ".kojee", "daemon-flaps.json");
+}
+function realRead(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+function realWrite(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content, "utf8");
+}
+function readFlaps(deps = {}) {
+  const p = deps.filePath ?? defaultFlapLogPath();
+  const raw = (deps.readFile ?? realRead)(p);
+  if (raw === null) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (e) => !!e && typeof e.ts === "number" && typeof e.instanceKey === "string"
+    );
+  } catch {
+    return [];
+  }
+}
+function recordFlap(entry, deps = {}) {
+  try {
+    const p = deps.filePath ?? defaultFlapLogPath();
+    const existing = readFlaps(deps);
+    const next = [...existing, entry].slice(-MAX_FLAP_ENTRIES);
+    (deps.writeFile ?? realWrite)(p, JSON.stringify(next, null, 2));
+  } catch {
+  }
+}
+function flapRateExceeds(flaps, opts) {
+  const cutoff = opts.now - opts.windowMs;
+  return flaps.filter((f) => f.ts >= cutoff).length >= opts.count;
+}
+function recentFlapCount(flaps, windowMs, now) {
+  const cutoff = now - windowMs;
+  return flaps.filter((f) => f.ts >= cutoff).length;
+}
+var FLAP_WINDOW_MS = 15 * 6e4;
+var FLAP_WARN_COUNT = 3;
+function buildFlapDoctorCheck(deps = {}) {
+  const name = deps.name ?? "daemon flapping";
+  const history = (deps.readFlaps ?? readFlaps)();
+  const now = deps.now?.() ?? Date.now();
+  const recent = recentFlapCount(history, FLAP_WINDOW_MS, now);
+  if (flapRateExceeds(history, { count: FLAP_WARN_COUNT, windowMs: FLAP_WINDOW_MS, now })) {
+    const last = history[history.length - 1];
+    return {
+      name,
+      ok: "warn",
+      detail: `the stream-liveness watchdog self-exited ${recent} times in the last 15min \u2014 the SSE reconnect loop is repeatedly wedging. This is a CHRONIC failure being masked by auto-restart; root-cause it (last reason: "${last?.reason ?? "unknown"}").`
+    };
+  }
+  return {
+    name,
+    ok: true,
+    detail: recent === 0 ? "no stream-liveness self-exits recently (healthy)" : `${recent} self-exit(s) in the last 15min \u2014 below the ${FLAP_WARN_COUNT}-in-15min chronic threshold`
+  };
+}
+
+export {
+  MAX_FLAP_ENTRIES,
+  defaultFlapLogPath,
+  readFlaps,
+  recordFlap,
+  flapRateExceeds,
+  recentFlapCount,
+  FLAP_WINDOW_MS,
+  FLAP_WARN_COUNT,
+  buildFlapDoctorCheck
+};

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

@@ -1,11 +1,11 @@
+import {
+  wrapNpxLauncher
+} from "./chunk-D6JKFJ6A.js";
 import {
   buildHookCommand,
   isKojeeHookCommand,
   npxHookCommand
-} from "./chunk-TMCNB4JH.js";
-import {
-  wrapNpxLauncher
-} from "./chunk-D6JKFJ6A.js";
+} from "./chunk-COM6435C.js";
 import {
   kojeeHomeDir
 } from "./chunk-SQL56SEB.js";
@@ -14,7 +14,7 @@ import {
 } from "./chunk-U5HHHRXA.js";
 import {
   VERSION
-} from "./chunk-5DHIUN73.js";
+} from "./chunk-BAPFHC36.js";
 
 // src/wizard/codex-config.ts
 import fs from "fs";
@@ -32,6 +32,7 @@ function defaultCodexConfigPath() {
 function defaultCodexHooksPath() {
   return win32DriveQualified(path.join(kojeeHomeDir(), ".codex", "hooks.json"), ".codex", "hooks.json");
 }
+var CODEX_TRUST_FIX_STEPS = 'to trust it, run `codex`, then type `/hooks` and press `t` on the entry \u2014 Codex only prints a "hooks need review" warning at startup, it does not auto-prompt';
 var CODEX_STOP_HOOK_COMMAND = npxHookCommand("codex-stop");
 function codexStopHookCommand() {
   return buildHookCommand("codex-stop");
@@ -345,6 +346,7 @@ function writeFile600(p, content) {
 export {
   defaultCodexConfigPath,
   defaultCodexHooksPath,
+  CODEX_TRUST_FIX_STEPS,
   buildCodexMcpServerTable,
   buildCodexStopHookBlock,
   buildCodexPromptSubmitHookBlock,

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";