kojee-mcp 0.4.0 → 0.5.2

package/README.md

@@ -1,5 +1,7 @@
 # kojee-mcp
 
+> **First time using Kojee Tandem in Claude Code?** See [docs/getting-started-tandem.md](docs/getting-started-tandem.md) for the 3-command setup + verification walkthrough.
+
 There are two ways to connect Kojee to an MCP-capable agent:
 
 1. **Mobile, web & desktop (recommended)** — 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).
@@ -89,14 +91,47 @@ To remove kojee from Claude:
 npx kojee-mcp init --uninstall
 ```
 
+## Runtime-aware setup wizard (`init` selects the runtime)
+
+`kojee-mcp init` is a runtime-aware wizard. The runtime selector is its core — one
+proxy adapts to four harnesses. Bare `init` with no flag and no TTY still defaults
+to `claude-code` (unchanged), so existing setups have zero regression.
+
+```bash
+npx kojee-mcp init                       # interactive (prompts when stdin is a TTY)
+npx kojee-mcp init --runtime claude-code # Claude Code (default): MCP entry + Stop/UserPromptSubmit hooks
+npx kojee-mcp init --runtime codex --webhook-url https://your-receiver/kojee
+                                         # Codex: writes ~/.codex/config.toml + a codex-stop hook
+npx kojee-mcp init --runtime hermes --webhook-url https://your-receiver/kojee
+npx kojee-mcp init --runtime openclaw --webhook-url https://your-receiver/kojee
+                                         # daemon runtimes: print/record the webhook-sink env to export
+```
+
+- **codex** — writes `[mcp_servers.kojee]` (with `env.KOJEE_RUNTIME="codex"` + the
+  webhook env) into `~/.codex/config.toml`, and a `codex-stop` Stop hook into
+  `~/.codex/hooks.json`. A `KOJEE_WEBHOOK_SECRET` is generated if you don't supply
+  one. Codex has no Claude-style channel injection, so its wake is the **webhook
+  sink + a stop-hook fast PEEK + a model-chosen bounded `tandem_listen` (cap 8s,
+  never a blanket long-poll)**. See `docs/RUNTIMES.md`.
+- **hermes / openclaw** — run the proxy as a daemon and consume the webhook sink;
+  the wizard writes no config/hooks of ours, validates the webhook env, and prints
+  + records the env to export (secret redacted).
+
+`kojee-mcp init --uninstall` is runtime-aware (uses the recorded runtime when
+`--runtime` is omitted). `kojee-mcp doctor` is runtime-aware too.
+
+> **Codex is build+PARK only:** there is no real Codex CLI on the build box, so the
+> adapter + wizard are unit/integration-tested only. Live-Codex end-to-end is
+> unverified — the wizard prints this note after a `--runtime codex` install.
+
 ## Claude Code Channels Support
 
 When this proxy detects it's running under Claude Code, it declares the `claude/channel` capability and pushes Tandem messages directly into the Claude session via `notifications/claude/channel`. Other MCP clients (Cursor, Codex, Openclaw, etc.) see no behavior change.
 
 **Runtime detection (3 tiers, first match wins):**
-1. `KOJEE_RUNTIME=claude-code` env var (set by `kojee-mcp init` in the MCP entry's `env` block — survives Claude.app's env strip)
-2. `CLAUDE_CODE_SESSION_ID` env var (set by the terminal `claude` CLI; **not** forwarded by Claude.app to MCP stdio servers)
-3. Process-ancestry walk for a parent process whose command line matches `\bclaude\b` (handles fresh installs where neither env var is present)
+1. `KOJEE_RUNTIME` env var — `claude-code` → CC, `codex` → Codex (set by `kojee-mcp init` in the MCP entry's `env` block — survives Claude.app's env strip). This is the **primary** path for Codex.
+2. `CLAUDE_CODE_SESSION_ID` env var (set by the terminal `claude` CLI; **not** forwarded by Claude.app to MCP stdio servers). CC only — Codex has no documented stable equivalent, so there is no Tier-2 Codex path.
+3. Process-ancestry walk for a parent process whose command line matches `\bclaude\b` (→ CC) or `\bcodex\b` (→ Codex) — low-confidence fallback for fresh installs where no env var is present.
 
 CC Channels are in research preview — you must launch CC with `claude --dangerously-load-development-channels server:kojee` until kojee is on the official allowlist.
 
@@ -126,26 +161,35 @@ If both Channels (dangerous-flag launched) and hooks are active, the proxy dedup
 
 ## Waiting on Tandem Peers
 
-When kojee-mcp is running under Claude Code, the proxy writes one line per Tandem message to a per-session log file. The agent watches this log via Claude Code's built-in `Monitor` tool.
-
-**You don't need to figure out the path yourself.** The proxy bakes the resolved path into the MCP server's `instructions` string at startup, so the agent gets the exact command to spawn:
+When kojee-mcp is running under Claude Code, the proxy writes one line per
+Tandem message to a per-session log file under the OS's temp directory
+(`os.tmpdir()` — `/tmp` on Linux, `/var/folders/…` on macOS, `%TEMP%` on
+Windows). The agent watches this log via Claude Code's built-in `Monitor`
+tool — spawned once at the start of each session:
 
 ```ts
 Monitor({
-  command: "tail -n +1 -F /tmp/kojee-events-<discoveryKey>.log",
+  command: `npx kojee-mcp tail "${eventLogPath}"`,
   persistent: true,
   description: "kojee Tandem events",
 });
 ```
 
-The `<discoveryKey>` is computed from `sha256(CLAUDE_PROJECT_DIR).slice(0,12) + '-' + <ccPid>` where `ccPid` is the parent Claude Code process. (This replaces the pre-v0.4 scheme that used `CLAUDE_CODE_SESSION_ID`, which Claude.app doesn't forward to MCP servers.) The matching `~/.kojee/sessions/cc-<discoveryKey>.json` discovery file lets the Stop / UserPromptSubmit hooks find this proxy via the same independent derivation.
+`kojee-mcp tail` is a portable line-streamer shipped with this proxy —
+works the same on macOS, Linux, and Windows. The proxy interpolates the
+resolved `eventLogPath` into the Channel-`instructions` string so the
+agent receives a ready-to-run command.
+
+The `<discoveryKey>` embedded in the log filename is computed from `sha256(CLAUDE_PROJECT_DIR).slice(0,12) + '-' + <ccPid>` where `ccPid` is the parent Claude Code process. (This replaces the pre-v0.4 scheme that used `CLAUDE_CODE_SESSION_ID`, which Claude.app doesn't forward to MCP servers.) The matching `~/.kojee/sessions/cc-<discoveryKey>.json` discovery file lets the Stop / UserPromptSubmit hooks find this proxy via the same independent derivation.
 
 Each appended event line arrives as a separate spontaneous wake notification. The agent stays free to chat with the user between events; CC delivers each event from idle as it arrives.
 
-**Stop hook is Monitor-aware** (v0.4+): when a Monitor is watching the log file, the Stop hook does an instant queue snapshot (~50ms) instead of a 30s long-poll, since events have already been delivered push-style. When no Monitor is running, the Stop hook long-polls for up to 30s AND emits a "spawn a Monitor" recommendation to the agent — self-healing if the session-start spawn was skipped.
+**Stop hook always long-polls** (up to 30s): the queue's `markMonitorDelivered` dedup ensures every event is delivered exactly once across the Channel / Monitor / Stop-hook paths, so the hook doesn't need to probe whether a Monitor is running. If the agent skipped the session-start Monitor spawn, the long-poll backstop still catches events; if Monitor is running, the dedup filters out anything already delivered push-style.
 
 Channel notifications (when available — see "Claude Code Channels Support" above) supplement this with mid-turn `<channel>` tag delivery, but Monitor is the default no-allowlist wake path that works for every user.
 
+**Cross-platform support:** the proxy core, the `kojee-mcp tail` Monitor command, and the Channel wake path are portable across macOS, Linux, and Windows — path resolution uses `os.homedir()` / `os.tmpdir()` and process-ancestry detection uses the pure-JS `ps-list` package. Claude Code hook invocation on Windows is pending end-to-end verification; on macOS and Linux it is exercised by CI.
+
 For one-shot blocking waits (return as soon as a single reply arrives), call `tandem_listen(tandem_id, since=cursor, timeout_ms=N)` instead.
 
 ## Backend SSE Wire Compatibility
@@ -163,6 +207,50 @@ The proxy normalizes incoming SSE events from `/api/v2/tandems/stream` so that t
 
 The normalizer also accepts canonical (spec-aligned) payloads unchanged, so the proxy works against either shape during any future backend migration.
 
+## Webhook Sink (daemonized wake)
+
+For runtimes that run the proxy as a daemon and inject Tandem events into a
+session via a **local HTTP receiver** (e.g. Hermes), the proxy can POST every
+Tandem event to a configured endpoint. It is a generic delivery sink — nothing
+in it is Hermes-specific — and it is **OFF by default**.
+
+| Env var | Meaning |
+|---|---|
+| `KOJEE_WEBHOOK_URL` | Receiver endpoint (http/https). **Unset ⇒ sink OFF** (zero behavior change). |
+| `KOJEE_WEBHOOK_SECRET` | HMAC-SHA256 key for the signature header. URL set but secret unset ⇒ sink **DISABLED with an error** (the proxy NEVER sends unsigned webhooks). |
+| `KOJEE_WEBHOOK_TIMEOUT_MS` | Per-attempt request timeout (default `5000`). |
+| `KOJEE_WEBHOOK_MAX_RETRIES` | Retries on a retryable failure — network / 5xx / 408 / 429 (default `4`). |
+
+**Receiver contract** (the single source of truth is `buildWebhookReceiverNote()`
+in `src/tandem/recipe.ts`, and the exact body shape is the `WEBHOOK_BODY_SHAPE`
+constant beside it):
+
+- **Body** — each POST carries the **canonical normalized `TandemEvent`** as JSON
+  (the real field names a receiver sees, *not* the backend wire shape):
+
+  ```
+  { type, id, tandem_id, cursor, time,
+    from{ member_id, principal, agent_id?, session_id?, displayname },
+    kind, content{ body, format? }, mentions?, reply_to?, severity? }
+  ```
+
+  `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`.
+- **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;
+  reject mismatches.
+- **Dedupe** by `message_id` (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. There is **no
+  exactly-once** promise; the receiver's dedupe is what makes redelivery safe.
+
+The sink is isolated and fire-and-forget: a slow, hanging, or failing webhook can
+never delay or break the Monitor (event-log) or Channel wake paths. The status
+log redacts the secret and strips any basic-auth credentials embedded in
+`KOJEE_WEBHOOK_URL`.
+
 ## Development
 
 Run tests:
@@ -188,7 +276,7 @@ Some tools are governed by approval policies configured in the Kojee dashboard.
 3. The proxy translates this into a clear MCP response telling the agent that the action is awaiting human approval.
 4. Once approved (via dashboard, Slack, or other configured channel), the agent can retry the call and it will succeed.
 
-Step-up re-authentication and nonce rotation are handled transparently -- the agent never needs to deal with auth mechanics.
+Nonce rotation is handled transparently -- the agent never needs to deal with auth mechanics. Step-up re-authentication is a **deprecated** feature (removed 2026-06-10): the proxy no longer polls for approval. Should a `step_up_required` response ever still occur, it surfaces immediately as a structured tool error carrying the reason, rather than a silent multi-minute wait.
 
 ## Troubleshooting
 

package/dist/chunk-2TUAFAIW.js

@@ -0,0 +1,244 @@
+import {
+  sessionDiscoveryDir
+} from "./chunk-DO42NPNR.js";
+import {
+  secureFile
+} from "./chunk-BLEGIR35.js";
+
+// src/tandem/event-log.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_DIR = os.tmpdir();
+var MAX_BODY_CHARS = 200;
+var DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+var DEFAULT_STATUS_MAX_BYTES = 1 * 1024 * 1024;
+var DEFAULT_MIN_AGE_MS = 6e4;
+var STATUS_LINE_PREFIX = "kojee-status";
+function statusLogPath(eventLogPath) {
+  const dir = path.dirname(eventLogPath);
+  const base = path.basename(eventLogPath);
+  const m = base.match(/^kojee-events-(.+)\.log$/);
+  return path.join(dir, m ? `kojee-status-${m[1]}.log` : `${base}.status`);
+}
+function startEventLog(opts) {
+  const dir = opts.dir ?? DEFAULT_DIR;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const statusMaxBytes = opts.statusMaxBytes ?? DEFAULT_STATUS_MAX_BYTES;
+  const filePath = path.join(dir, `kojee-events-${opts.key}.log`);
+  const statusPath = statusLogPath(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, "", { mode: 384 });
+  secureFile(filePath);
+  fs.writeFileSync(statusPath, "", { mode: 384 });
+  secureFile(statusPath);
+  let writtenIds = /* @__PURE__ */ new Set();
+  let bytesWritten = 0;
+  let linesWritten = 0;
+  let statusBytesWritten = 0;
+  let writingMsg = Promise.resolve();
+  function enqueueMsg(fn) {
+    writingMsg = writingMsg.then(fn, fn);
+    return writingMsg;
+  }
+  let writingStatus = Promise.resolve();
+  function enqueueStatus(fn) {
+    writingStatus = writingStatus.then(fn, fn);
+    return writingStatus;
+  }
+  async function writeStatusRaw(fields) {
+    const note = formatStatusLine(fields);
+    if (statusBytesWritten >= statusMaxBytes) {
+      try {
+        await fs.promises.truncate(statusPath, 0);
+        statusBytesWritten = 0;
+      } catch (err) {
+        console.error("[event-log] status rotate-truncate failed:", err.message);
+      }
+    }
+    await fs.promises.appendFile(statusPath, note + "\n", { encoding: "utf8" });
+    statusBytesWritten += Buffer.byteLength(note + "\n");
+  }
+  async function writeMsgRaw(line) {
+    if (bytesWritten >= maxBytes) {
+      const dropped = linesWritten;
+      try {
+        await fs.promises.truncate(filePath, 0);
+        bytesWritten = 0;
+        linesWritten = 0;
+        writtenIds = /* @__PURE__ */ new Set();
+        void enqueueStatus(() => writeStatusRaw(`status=rotated dropped=${dropped}`)).catch(() => {
+        });
+      } catch (err) {
+        console.error("[event-log] rotate-truncate failed:", err.message);
+      }
+    }
+    await fs.promises.appendFile(filePath, line + "\n", { encoding: "utf8" });
+    bytesWritten += Buffer.byteLength(line + "\n");
+    linesWritten += 1;
+  }
+  return {
+    path: filePath,
+    statusPath,
+    async append(event) {
+      if (event.id && writtenIds.has(event.id)) return;
+      if (event.id) writtenIds.add(event.id);
+      const line = formatLine(event);
+      await enqueueMsg(async () => {
+        try {
+          await writeMsgRaw(line);
+        } catch (err) {
+          console.error("[event-log] append failed:", err.message);
+          if (event.id) writtenIds.delete(event.id);
+        }
+      });
+    },
+    async appendStatus(fields) {
+      await enqueueStatus(async () => {
+        try {
+          await writeStatusRaw(fields);
+        } catch (err) {
+          console.error("[event-log] appendStatus failed:", err.message);
+        }
+      });
+    },
+    cleanup() {
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+      }
+      try {
+        fs.unlinkSync(statusPath);
+      } catch {
+      }
+    }
+  };
+}
+function formatStatusLine(fields) {
+  return `[${(/* @__PURE__ */ new Date()).toISOString()}] ${STATUS_LINE_PREFIX} ${fields}`;
+}
+function formatLine(event) {
+  const body = (event.content?.body ?? "").replace(/[\r\n]+/g, " ").slice(0, MAX_BODY_CHARS + 1);
+  const truncated = body.length > MAX_BODY_CHARS;
+  const safeBody = truncated ? body.slice(0, MAX_BODY_CHARS) + "\u2026" : body;
+  return `[${event.time}] tandem=${event.tandem_id} from=${event.from.displayname} (${event.from.principal}) kind=${event.kind} cursor=${event.cursor} msg=${event.id}: ${safeBody}`;
+}
+function monitorHeartbeatPath(eventLogPath) {
+  const dir = path.dirname(eventLogPath);
+  const base = path.basename(eventLogPath);
+  const m = base.match(/^kojee-events-(.+)\.log$/);
+  return path.join(dir, m ? `kojee-monitor-${m[1]}.alive` : `${base}.alive`);
+}
+function nudgeSentinelPath(eventLogPath) {
+  const dir = path.dirname(eventLogPath);
+  const base = path.basename(eventLogPath);
+  const m = base.match(/^kojee-events-(.+)\.log$/);
+  return path.join(dir, m ? `kojee-nudge-${m[1]}.touch` : `${base}.nudge`);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === "EPERM") return true;
+    return false;
+  }
+}
+function listActiveSessionIds() {
+  const dir = sessionDiscoveryDir();
+  const active = /* @__PURE__ */ new Set();
+  const livePaths = /* @__PURE__ */ new Set();
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return { active, livePaths };
+  }
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    const rawId = name.slice(0, -".json".length);
+    const sessionId = rawId.startsWith("cc-") ? rawId.slice("cc-".length) : rawId;
+    const filePath = path.join(dir, name);
+    try {
+      const data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      if (typeof data.pid === "number" && isProcessAlive(data.pid)) {
+        active.add(sessionId);
+        if (data.eventLogPath) livePaths.add(path.resolve(data.eventLogPath));
+      } else {
+        try {
+          fs.unlinkSync(filePath);
+        } catch {
+        }
+        if (data.eventLogPath) {
+          try {
+            fs.unlinkSync(data.eventLogPath);
+          } catch {
+          }
+          try {
+            fs.unlinkSync(statusLogPath(data.eventLogPath));
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return { active, livePaths };
+}
+function sweepStaleEventLogs(dir = DEFAULT_DIR, minAgeMs = DEFAULT_MIN_AGE_MS) {
+  try {
+    fs.unlinkSync(path.join(dir, "kojee-events-no-session.log"));
+  } catch {
+  }
+  const { active, livePaths } = listActiveSessionIds();
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const name of entries) {
+    if (!name.startsWith("kojee-events-") || !name.endsWith(".log")) continue;
+    const sessionId = name.slice("kojee-events-".length, -".log".length);
+    if (active.has(sessionId)) continue;
+    const filePath = path.join(dir, name);
+    if (livePaths.has(path.resolve(filePath))) continue;
+    try {
+      const stat = fs.statSync(filePath);
+      const ageMs = Math.max(0, now - stat.mtimeMs);
+      if (ageMs < minAgeMs) continue;
+      fs.unlinkSync(filePath);
+      try {
+        fs.unlinkSync(statusLogPath(filePath));
+      } catch {
+      }
+    } catch {
+    }
+  }
+  for (const name of entries) {
+    if (!name.startsWith("kojee-status-") || !name.endsWith(".log")) continue;
+    const statusFile = path.join(dir, name);
+    const key = name.slice("kojee-status-".length, -".log".length);
+    const messagesFile = path.join(dir, `kojee-events-${key}.log`);
+    if (active.has(key)) continue;
+    if (livePaths.has(path.resolve(messagesFile))) continue;
+    if (fs.existsSync(messagesFile)) continue;
+    try {
+      const stat = fs.statSync(statusFile);
+      const ageMs = Math.max(0, now - stat.mtimeMs);
+      if (ageMs < minAgeMs) continue;
+      fs.unlinkSync(statusFile);
+    } catch {
+    }
+  }
+}
+
+export {
+  STATUS_LINE_PREFIX,
+  statusLogPath,
+  startEventLog,
+  monitorHeartbeatPath,
+  nudgeSentinelPath,
+  sweepStaleEventLogs
+};

package/dist/{chunk-36DMIXH7.js → chunk-BJMASMKX.js}

@@ -1,36 +1,26 @@
 // src/runtime/ancestry.ts
-import childProcess from "child_process";
+import psList from "ps-list";
 import { createHash } from "crypto";
-function findClaudeAncestorPid(startPid = process.ppid) {
-  if (process.platform === "win32") return null;
+async function findClaudeAncestorPid(startPid = process.ppid) {
+  let processes;
+  try {
+    processes = await psList();
+  } catch {
+    return null;
+  }
+  const byPid = /* @__PURE__ */ new Map();
+  for (const p of processes) byPid.set(p.pid, p);
   let pid = startPid;
   for (let depth = 0; depth < 20 && pid !== void 0 && pid > 1; depth++) {
-    let row;
-    try {
-      row = readProcInfo(pid);
-    } catch {
-      return null;
-    }
+    const row = byPid.get(pid);
     if (!row) return null;
-    if (/\bclaude\b/.test(row.command)) return pid;
+    const haystack = `${row.name} ${row.cmd ?? ""}`;
+    if (/\bclaude\b/i.test(haystack)) return pid;
     if (row.ppid === void 0 || row.ppid === pid) return null;
     pid = row.ppid;
   }
   return null;
 }
-function readProcInfo(pid) {
-  const out = childProcess.execFileSync("ps", ["-ww", "-p", String(pid), "-o", "ppid=,command="], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"]
-  }).trim();
-  if (!out) return null;
-  const firstSpace = out.indexOf(" ");
-  if (firstSpace < 0) return null;
-  const ppid = Number.parseInt(out.slice(0, firstSpace).trim(), 10);
-  if (!Number.isFinite(ppid)) return null;
-  const command = out.slice(firstSpace + 1).trim();
-  return { command, ppid };
-}
 function deriveDiscoveryKey(projectDir, ccPid) {
   const hasProjectDir = typeof projectDir === "string" && projectDir.length > 0;
   if (!hasProjectDir && ccPid === null) {

package/dist/chunk-BLEGIR35.js

@@ -0,0 +1,43 @@
+// src/secure-file.ts
+import fs from "fs";
+import os from "os";
+import { execFileSync } from "child_process";
+function isWindows() {
+  return process.platform === "win32";
+}
+function secureFile(filePath) {
+  if (isWindows()) {
+    restrictAclToCurrentUser(filePath, "(F)");
+  } else {
+    try {
+      fs.chmodSync(filePath, 384);
+    } catch {
+    }
+  }
+}
+function secureDir(dirPath) {
+  if (isWindows()) {
+    restrictAclToCurrentUser(dirPath, "(OI)(CI)(F)");
+  } else {
+    try {
+      fs.chmodSync(dirPath, 448);
+    } catch {
+    }
+  }
+}
+function restrictAclToCurrentUser(target, permission) {
+  try {
+    const user = os.userInfo().username;
+    execFileSync(
+      "icacls",
+      [target, "/inheritance:r", "/grant:r", `${user}:${permission}`],
+      { stdio: "ignore" }
+    );
+  } catch {
+  }
+}
+
+export {
+  secureFile,
+  secureDir
+};

package/dist/chunk-C6GZ2L2W.js

@@ -0,0 +1,38 @@
+// src/tandem/recipe.ts
+var SEND_BODY_PARAM = "body";
+function buildMonitorCommand(logPath) {
+  return `npx kojee-mcp tail "${logPath}"`;
+}
+function buildMonitorSpawn(logPath) {
+  return `Monitor(command=\`${buildMonitorCommand(logPath)}\`, persistent=true, description="kojee Tandem events")`;
+}
+function buildReplyRecipe(event) {
+  if (event) {
+    return `reply directly with tandem_send(tandem_id="${event.tandem_id}", ${SEND_BODY_PARAM}="...", reply_to="${event.message_id}"); fetch context only if needed via tandem_messages(tandem_id, since=cursor-1)`;
+  }
+  return `reply directly with tandem_send(tandem_id, ${SEND_BODY_PARAM}, reply_to=<msg>); fetch context only if needed via tandem_messages(tandem_id, since=cursor-1)`;
+}
+function buildCatchUpNote() {
+  return "If the event line `cursor=<n>` ever jumps (a gap) or the log resets (the proxy caps and truncates the messages log in place on overflow \u2014 a `status=rotated` line is recorded in the status sibling), you may have missed messages: catch up with tandem_messages(tandem_id, since=<last cursor you saw>).";
+}
+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? }";
+function buildWebhookReceiverNote() {
+  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 X-Kojee-Signature header \u2014 it is the hex-encoded SHA-256 HMAC 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;
+function buildCodexWakeReason(cursor) {
+  return `[kojee] new Tandem event(s) pending (cursor=${cursor}). If relevant to your task, drain them now: call tandem_messages(tandem_id, since=${cursor - 1}) to read, then ` + buildReplyRecipe() + `. If you expect an imminent reply and want to wait for exactly one, call tandem_listen(tandem_id, since=${cursor}, timeout_ms<=${CODEX_LISTEN_CAP_MS}) \u2014 a BOUNDED wait, cap 8s, NEVER an unconditional long-poll. If not relevant, ignore.`;
+}
+
+export {
+  buildMonitorSpawn,
+  buildReplyRecipe,
+  buildCatchUpNote,
+  buildMonitorNudge,
+  buildWebhookReceiverNote,
+  CODEX_LISTEN_CAP_MS,
+  buildCodexWakeReason
+};

package/dist/{chunk-VZVGTHGF.js → chunk-DO42NPNR.js}

@@ -1,8 +1,14 @@
+import {
+  secureDir,
+  secureFile
+} from "./chunk-BLEGIR35.js";
+
 // src/tandem/session-discovery.ts
 import fs from "fs";
+import os from "os";
 import path from "path";
 function sessionDiscoveryDir() {
-  return path.join(process.env["HOME"] ?? "~", ".kojee", "sessions");
+  return path.join(os.homedir(), ".kojee", "sessions");
 }
 function sessionDiscoveryPath(sessionId) {
   return path.join(sessionDiscoveryDir(), `${sessionId}.json`);
@@ -13,16 +19,10 @@ function discoveryFileName(key) {
 function writeSessionDiscovery(sessionId, entry) {
   const dir = sessionDiscoveryDir();
   fs.mkdirSync(dir, { recursive: true, mode: 448 });
-  try {
-    fs.chmodSync(dir, 448);
-  } catch {
-  }
+  secureDir(dir);
   const filePath = sessionDiscoveryPath(sessionId);
   fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), { mode: 384 });
-  try {
-    fs.chmodSync(filePath, 384);
-  } catch {
-  }
+  secureFile(filePath);
 }
 function readSessionDiscovery(sessionId) {
   try {
@@ -44,16 +44,10 @@ function discoveryPathForKey(key) {
 function writeDiscoveryByKey(key, entry) {
   const dir = sessionDiscoveryDir();
   fs.mkdirSync(dir, { recursive: true, mode: 448 });
-  try {
-    fs.chmodSync(dir, 448);
-  } catch {
-  }
+  secureDir(dir);
   const filePath = discoveryPathForKey(key);
   fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), { mode: 384 });
-  try {
-    fs.chmodSync(filePath, 384);
-  } catch {
-  }
+  secureFile(filePath);
 }
 function cleanupDiscoveryByKey(key) {
   try {

package/dist/chunk-EW72ZNQL.js

@@ -0,0 +1,39 @@
+import {
+  kojeeHomeDir
+} from "./chunk-SQL56SEB.js";
+import {
+  secureFile
+} from "./chunk-BLEGIR35.js";
+
+// src/wizard/runtime-record.ts
+import fs from "fs";
+import path from "path";
+function runtimeRecordPath() {
+  return path.join(kojeeHomeDir(), ".kojee", "runtime");
+}
+function recordRuntime(runtime, recordPath = runtimeRecordPath()) {
+  fs.mkdirSync(path.dirname(recordPath), { recursive: true, mode: 448 });
+  fs.writeFileSync(recordPath, runtime + "\n", { mode: 384 });
+  secureFile(recordPath);
+}
+function readRecordedRuntime(recordPath = runtimeRecordPath()) {
+  try {
+    const raw = fs.readFileSync(recordPath, "utf8").trim();
+    return raw.length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function clearRuntimeRecord(recordPath = runtimeRecordPath()) {
+  try {
+    fs.unlinkSync(recordPath);
+  } catch {
+  }
+}
+
+export {
+  runtimeRecordPath,
+  recordRuntime,
+  readRecordedRuntime,
+  clearRuntimeRecord
+};