context-mode 1.0.136 → 1.0.138

package/build/adapters/vscode-copilot/hooks.js

@@ -1,4 +1,3 @@
-import { buildNodeCommand } from "../types.js";
 /**
  * adapters/vscode-copilot/hooks — VS Code Copilot hook definitions and matchers.
  *
@@ -63,21 +62,37 @@ export function isContextModeHook(entry, hookType) {
 }
 /**
  * Build the hook command string for a given hook type.
- * Uses absolute node path to avoid PATH issues (homebrew, nvm, volta, etc.).
- * Falls back to CLI dispatcher if pluginRoot is not provided.
+ *
+ * Always emits the CLI dispatcher form
+ * (`context-mode hook vscode-copilot <event>`) — the `pluginRoot` argument
+ * is accepted for API compatibility but intentionally ignored.
+ *
+ * Why the dispatcher form is mandatory here (Issue #613 — Tier C contract):
+ *   `.github/hooks/context-mode.json` is a **workspace-committed** file
+ *   (upstream: refs/platforms/vscode-copilot/assets/prompts/skills/
+ *   agent-customization/references/hooks.md line 7 — "Workspace
+ *   (team-shared)"). It lands in every teammate's `git status`. Embedding
+ *   `process.execPath` or any absolute pluginRoot path here:
+ *     - Leaks PII (username, `C:/Users/<user>/...` paths).
+ *     - Breaks cross-machine portability (fnm/nvm/volta/brew shims are
+ *       per-shell-session ephemeral; the path goes stale immediately on
+ *       Windows + fnm).
+ *
+ * Commit `f5c9d02` (2026-03-06) added an absolute-path branch when a
+ * pluginRoot was passed. It solved a real PATH-availability bug on
+ * Brew/nvm setups by going too far — the CLI then always passes
+ * pluginRoot, so the portable form became unreachable in production
+ * and every `/ctx-upgrade` baked a non-portable command into the
+ * committed config. This reverts to the pre-`f5c9d02` shape.
+ *
+ * For users without a global install, the recovery path is the same as
+ * every other CLI-dispatcher adapter (cursor, codex):
+ *   `npm install -g context-mode`
  */
-export function buildHookCommand(hookType, pluginRoot) {
+export function buildHookCommand(hookType, _pluginRoot) {
     const scriptName = HOOK_SCRIPTS[hookType];
     if (!scriptName) {
         throw new Error(`No script defined for hook type: ${hookType}`);
     }
-    if (pluginRoot) {
-        // v1.0.107 fix — was `${pluginRoot}/hooks/${scriptName}` which resolved to
-        // the Claude-Code generic hook (`hooks/pretooluse.mjs`) instead of the
-        // VSCode-specific wrapper at `hooks/vscode-copilot/pretooluse.mjs`. JetBrains
-        // adapter already had the correct subdir (jetbrains-copilot/hooks.ts:98)
-        // so this brings VSCode to parity.
-        return buildNodeCommand(`${pluginRoot}/hooks/vscode-copilot/${scriptName}`);
-    }
     return `context-mode hook vscode-copilot ${hookType.toLowerCase()}`;
 }

package/build/cli.js

@@ -14,7 +14,7 @@
 import * as p from "@clack/prompts";
 import color from "picocolors";
 import { execFileSync, execSync, execFile as nodeExecFile } from "node:child_process";
-import { readFileSync, writeFileSync, cpSync, accessSync, existsSync, rmSync, closeSync, openSync, chmodSync, constants } from "node:fs";
+import { readFileSync, cpSync, accessSync, existsSync, readdirSync, rmSync, closeSync, openSync, chmodSync, constants } from "node:fs";
 import { request as httpsRequest } from "node:https";
 import { resolve, dirname, join } from "node:path";
 import { tmpdir, devNull, homedir } from "node:os";
@@ -27,7 +27,7 @@ import { discoverSiblingMcpPids, killSiblingMcpServers } from "./util/sibling-mc
 // v1.0.119 — Issue #523 Layer 5 heal: post-bump assertion on .claude-plugin/plugin.json
 // mcpServers args. Single source of truth shared with start.mjs HEAL block + postinstall.
 // @ts-expect-error — JS module, no TS declarations
-import { healPluginJsonMcpServers, healMcpJsonArgs } from "../scripts/heal-installed-plugins.mjs";
+import { healPluginJsonMcpServers, sweepStaleMcpJson } from "../scripts/heal-installed-plugins.mjs";
 // @ts-expect-error — JS module, no TS declarations
 import { detectWindowsVsYear } from "../scripts/heal-better-sqlite3.mjs";
 // Private 16-LOC copy of browserOpenArgv. Canonical version lives in src/server.ts;
@@ -454,6 +454,166 @@ async function doctor() {
         p.log.warn(color.yellow("Plugin enabled: WARN") +
             ` — ${pluginCheck.message}`);
     }
+    // ── Issue #613 — proactive Tier C absolute-path detection ───────────
+    // PR #620 fixed `buildHookCommand` for vscode-copilot + jetbrains-copilot
+    // so future writes are CLI-dispatcher-shape. But users who ran
+    // /ctx-upgrade on v1.0.136 or earlier are still carrying poisoned
+    // committable files in their workspace:
+    //   - `.github/hooks/context-mode.json`      (vscode-copilot, team-shared)
+    //   - `.jetbrains/copilot/hooks.json`        (jetbrains-copilot, team-shared)
+    //   - `.cursor/hooks.json`                   (cursor, team-shared)
+    // Per ISSUE-613-VERDICT §6.1 these are Tier C — workspace-committed
+    // cross-machine config. Doctor scans them for absolute paths and
+    // fnm_multishells shims; if found, FAIL with `ctx_upgrade` remediation.
+    // Per ISSUE-604-VERDICT §11 ("silent-green doctor while hooks are dead
+    // is itself a P0 trust bug") — surface poison BEFORE the user hits a
+    // runtime failure.
+    p.log.step("Checking team-shared hook configs in your workspace...");
+    {
+        const projectDir = process.cwd();
+        const tierCFiles = [
+            ".github/hooks/context-mode.json",
+            ".cursor/hooks.json",
+            ".jetbrains/copilot/hooks.json",
+        ];
+        let tierCFails = 0;
+        let tierCChecked = 0;
+        // Detect absolute-path patterns that should never appear in a
+        // workspace-committed config. Per Mert's standing Windows-safety rule:
+        // handle both `/` and `\\` separators.
+        function isAbsoluteOrShimPath(s) {
+            // unix absolute
+            if (s.startsWith("/"))
+                return true;
+            // Windows drive-letter absolute (e.g. C:/, C:\)
+            if (/^[A-Za-z]:[/\\]/.test(s))
+                return true;
+            // Windows UNC or escaped-backslash absolute fragments
+            if (s.includes("\\\\"))
+                return true;
+            // fnm shim hint — issue #613 reporter's exact stderr shape
+            if (s.includes("fnm_multishells"))
+                return true;
+            // process.execPath literal baked into JSON
+            if (s.includes("process.execPath"))
+                return true;
+            return false;
+        }
+        function recurseStrings(node, hit) {
+            if (typeof node === "string") {
+                hit(node);
+            }
+            else if (Array.isArray(node)) {
+                for (const item of node)
+                    recurseStrings(item, hit);
+            }
+            else if (node && typeof node === "object") {
+                for (const v of Object.values(node))
+                    recurseStrings(v, hit);
+            }
+        }
+        for (const rel of tierCFiles) {
+            const abs = resolve(projectDir, rel);
+            if (!existsSync(abs))
+                continue; // missing config → SKIP, no false fail
+            tierCChecked++;
+            try {
+                const parsed = JSON.parse(readFileSync(abs, "utf-8"));
+                const offenders = [];
+                recurseStrings(parsed, (s) => {
+                    if (isAbsoluteOrShimPath(s))
+                        offenders.push(s);
+                });
+                if (offenders.length > 0) {
+                    criticalFails++;
+                    tierCFails++;
+                    // Truncate to one example to keep output readable; show count.
+                    const example = offenders[0].length > 100
+                        ? offenders[0].slice(0, 97) + "..."
+                        : offenders[0];
+                    p.log.error(color.red(`Hook config: FAIL`) +
+                        ` — ${rel} has your machine's local paths baked in` +
+                        color.dim("\n  This file is committed to git, so teammates and CI will get your path and the hooks will break for them." +
+                            `\n  Found ${offenders.length} hard-coded path(s), e.g.: ${example}` +
+                            "\n  Fix: run /context-mode:ctx-upgrade — it rewrites the file to a portable form that works on every machine." +
+                            "\n  Details: https://github.com/mksglu/context-mode/issues/613"));
+                }
+                else {
+                    p.log.success(color.green("Hook config: PASS") +
+                        color.dim(` — ${rel} is portable (no hard-coded paths)`));
+                }
+            }
+            catch (err) {
+                // Malformed JSON should not crash doctor; warn and move on.
+                const msg = err instanceof Error ? err.message : String(err);
+                p.log.warn(color.yellow(`Hook config: WARN`) +
+                    ` — ${rel} is not valid JSON` +
+                    color.dim("\n  Doctor cannot scan it for portability issues until the file parses." +
+                        "\n  Fix: open the file and check it in a JSON validator, or delete it and run /context-mode:ctx-upgrade to regenerate." +
+                        `\n  Parser said: ${msg.slice(0, 160)}`));
+            }
+        }
+        if (tierCChecked === 0) {
+            p.log.info(color.dim("Hook config: SKIP — no team-shared hook configs found in this workspace"));
+        }
+        else if (tierCFails === 0) {
+            // already individual PASS messages above; no need for a summary
+        }
+    }
+    // ── Issue #609 — proactive stale `.mcp.json` detection ──────────────
+    // PR #620 deleted the per-version cache `.mcp.json` write from cli.ts
+    // and shipped `sweepStaleMcpJson` to clean up any pre-existing copies.
+    // But users on the field may still have stale `.mcp.json` files left
+    // by /ctx-upgrade flows that ran before PR #620 (or by Claude Code's
+    // native auto-update copying a poisoned file forward). Surface those
+    // as WARN (recoverable — next ctx_upgrade sweeps them) so the user
+    // knows what to do instead of being told everything is green while
+    // the file lingers on disk.
+    // Per ISSUE-604-VERDICT §11 same trust contract as Tier C check above.
+    p.log.step("Checking for leftover .mcp.json files from older versions...");
+    {
+        const cacheRoot = join(homedir(), ".claude", "plugins", "cache", "context-mode", "context-mode");
+        if (!existsSync(cacheRoot)) {
+            p.log.info(color.dim("Leftover .mcp.json check: SKIP — no plugin cache exists yet (Claude Code has not installed context-mode here)"));
+        }
+        else {
+            let staleCount = 0;
+            const staleVersions = [];
+            try {
+                const versionDirs = readdirSync(cacheRoot);
+                for (const v of versionDirs) {
+                    const candidate = join(cacheRoot, v, ".mcp.json");
+                    if (existsSync(candidate)) {
+                        staleCount++;
+                        if (staleVersions.length < 5)
+                            staleVersions.push(v);
+                    }
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                p.log.warn(color.yellow("Leftover .mcp.json check: WARN") +
+                    ` — could not read the plugin cache directory` +
+                    color.dim(`\n  Path: ${cacheRoot}` +
+                        `\n  Reason: ${msg.slice(0, 160)}` +
+                        "\n  Fix: check that the directory is readable, then re-run doctor. If the issue persists, run /context-mode:ctx-upgrade."));
+                staleCount = 0;
+            }
+            if (staleCount === 0) {
+                p.log.success(color.green("Leftover .mcp.json check: PASS") +
+                    color.dim(" — no old .mcp.json files in the plugin cache"));
+            }
+            else {
+                // WARN, not FAIL — per architect spec this is recoverable.
+                p.log.warn(color.yellow("Leftover .mcp.json check: WARN") +
+                    ` — found ${staleCount} old .mcp.json file(s) left over from previous context-mode versions` +
+                    color.dim("\n  These are harmless but should be cleaned up so they cannot confuse Claude Code after an auto-update." +
+                        `\n  Versions affected: ${staleVersions.join(", ")}${staleCount > staleVersions.length ? ", ..." : ""}` +
+                        "\n  Fix: run /context-mode:ctx-upgrade — it sweeps these files automatically on the next run." +
+                        "\n  Details: https://github.com/mksglu/context-mode/issues/609"));
+            }
+        }
+    }
     // FTS5 / SQLite
     p.log.step("Checking FTS5 / SQLite...");
     try {
@@ -798,20 +958,24 @@ async function upgrade(opts) {
                 }
                 catch { /* some files may not exist in source */ }
             }
-            // Write .mcp.json with CLAUDE_PLUGIN_ROOT placeholder (fixes #411).
-            // Absolute paths bake-in the current pluginRoot dir, which sessionstart.mjs
-            // (#181) deletes after upgrade — breaking MCP server resolution. The literal
-            // ${CLAUDE_PLUGIN_ROOT} placeholder is resolved by Claude at load-time and
-            // stays valid across version cleanups. Matches .claude-plugin/plugin.json.
-            const mcpConfig = {
-                mcpServers: {
-                    "context-mode": {
-                        command: "node",
-                        args: ["${CLAUDE_PLUGIN_ROOT}/start.mjs"],
-                    },
-                },
-            };
-            writeFileSync(resolve(pluginRoot, ".mcp.json"), JSON.stringify(mcpConfig, null, 2) + "\n");
+            // Issue #609 — DO NOT write `.mcp.json` into the plugin cache dir.
+            //
+            // Historical context: #411 fixed an absolute-path bake by writing the
+            // ${CLAUDE_PLUGIN_ROOT} placeholder form here. #531 (commit 9261377)
+            // removed `.mcp.json` from `package.json files[]` so the npm tarball
+            // stopped shipping it. But the cli-side write persisted, so every
+            // /ctx-upgrade re-baked one. When Claude Code's native plugin manager
+            // auto-update later carries a previous version's `.mcp.json` forward
+            // into a fresh version dir, the stale start.mjs absolute path goes
+            // with it → MODULE_NOT_FOUND on every MCP boot.
+            //
+            // Architectural fix: Claude Code reads `.claude-plugin/plugin.json`
+            // .mcpServers as the canonical source (upstream:
+            // refs/platforms/claude-code/src/utils/plugins/mcpPluginIntegration.ts:131-212).
+            // `.mcp.json` is a redundant per-version artifact whose only role
+            // historically was to be a write-time poison vector. Don't write it.
+            // The post-bump cache-sweep below removes any pre-existing copies so
+            // the previous-version-carry vector cannot replay.
             // Normalize hooks.json + plugin.json against the REAL pluginRoot now that
             // files have been copied. Two reasons:
             //   1. If a prior buggy postinstall (or any future regression) baked the
@@ -908,30 +1072,33 @@ async function upgrade(opts) {
                 const message = err instanceof Error ? err.message : String(err);
                 throw new Error(`plugin.json drift check failed: ${message}`);
             }
-            // v1.0.122 — Issue #531 — Layer 6 heal: assert .mcp.json's
-            // mcpServers["context-mode"].args[0] is the literal ${CLAUDE_PLUGIN_ROOT}/start.mjs
-            // placeholder. Asymmetric-heal sibling of the plugin.json assertion above.
-            // cli.ts writes .mcp.json at ~line 829-845 with the placeholder, but never
-            // asserted the on-disk shape afterwards — if a future regression dropped
-            // the placeholder write or a parallel normalize baked in an absolute path,
-            // upgrade() would declare success on a poisoned tree. Belt-and-braces:
-            // first call cleans any drift; second call MUST return healed:[] or throw.
-            // Single source of truth shared with start.mjs HEAL block + postinstall.
+            // Issue #609 — Layer 6 replacement: sweep stale `.mcp.json` files from
+            // every per-version cache dir. Supersedes the previous healMcpJsonArgs
+            // drift-check block (v1.0.122) — that block existed because cli.ts
+            // itself wrote `.mcp.json`. With the write gone (above), the only
+            // remaining `.mcp.json` files are stale carry-forwards from earlier
+            // versions. Sweep them so Claude Code's auto-update can't replay them
+            // into a fresh version dir.
+            //
+            // Belt-and-braces: a second sweep call MUST report removed:[] or we
+            // throw — same architectural-lock pattern as the plugin.json drift
+            // check above. Single source of truth shared with start.mjs HEAL
+            // block + postinstall.
             try {
                 const pluginCacheRoot = resolve(resolveClaudeConfigDir(), "plugins", "cache");
                 const pluginKey = "context-mode@context-mode";
-                const firstPass = healMcpJsonArgs({ pluginRoot, pluginCacheRoot, pluginKey });
-                if (firstPass && firstPass.error) {
-                    throw new Error(firstPass.error);
+                const firstSweep = sweepStaleMcpJson({ pluginCacheRoot, pluginKey });
+                if (firstSweep && firstSweep.removed && firstSweep.removed.length > 0) {
+                    p.log.info(color.dim(`  Swept ${firstSweep.removed.length} stale .mcp.json file(s) from cache`));
                 }
-                const secondPass = healMcpJsonArgs({ pluginRoot, pluginCacheRoot, pluginKey });
-                if (secondPass && Array.isArray(secondPass.healed) && secondPass.healed.length > 0) {
-                    throw new Error(`.mcp.json drift: mcpServers.args still poisoned after first heal pass (healed=${secondPass.healed.join(",")})`);
+                const secondSweep = sweepStaleMcpJson({ pluginCacheRoot, pluginKey });
+                if (secondSweep && Array.isArray(secondSweep.removed) && secondSweep.removed.length > 0) {
+                    throw new Error(`.mcp.json sweep drift: ${secondSweep.removed.length} file(s) still present after first pass`);
                 }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`.mcp.json drift check failed: ${message}`);
+                throw new Error(`.mcp.json sweep check failed: ${message}`);
             }
             // v1.0.X — Layer 7 heal: update user-level ~/.claude.json MCP server
             // registrations that point to old context-mode version dirs.

package/build/lifecycle.d.ts

@@ -20,54 +20,7 @@ export interface LifecycleGuardOptions {
     onShutdown: () => void;
     /** Injectable parent-alive check (for testing). Default: ppid-based check. */
     isParentAlive?: () => boolean;
-    /**
-     * Idle shutdown threshold in ms (#565). When the server has handled no
-     * MCP activity for this long, `onShutdown` fires. `0` disables.
-     * Default: env `CONTEXT_MODE_IDLE_TIMEOUT_MS`, else 0 (disabled).
-     * Skipped on TTY stdin (interactive dev / OpenCode ts-plugin standalone).
-     *
-     * Pair with the returned `recordActivity()` callback — call it on every
-     * MCP request the server handles so genuinely busy servers never trip.
-     */
-    idleTimeoutMs?: number;
-    /** Test injection — defaults to `Date.now`. */
-    now?: () => number;
 }
-/**
- * Hybrid return type: callable like the original `() => void` cleanup (kept
- * for backwards compatibility with #103/#236/#311/#388/#534 test suites),
- * and additionally exposes `recordActivity` for the idle-timeout path (#565)
- * and `stop` as an explicit alias.
- */
-export interface LifecycleGuardHandle {
-    /** Stop the guard. Calling the handle directly is equivalent. */
-    (): void;
-    /** Bumps the "last activity" timestamp so the idle timer doesn't fire. */
-    recordActivity: () => void;
-    /** Stop the guard. Alias for invoking the handle. */
-    stop: () => void;
-}
-/**
- * Resolve the idle-shutdown threshold (#565).
- *
- * Idle shutdown is OFF by default (#592) because most hosts (Claude
- * Code, Codex, editor MCP clients) keep registered tool handles after a
- * clean MCP child exit and do NOT transparently respawn on the next call.
- * The global 15 min default introduced in #568 solved OpenCode's child
- * accumulation, but stranded ctx_* tools in Claude Code/Codex-style
- * hosts once the MCP server exited cleanly while the editor stayed alive.
- *
- * Hosts that are known to benefit from idle shutdown MUST opt in via
- * CONTEXT_MODE_IDLE_TIMEOUT_MS in their MCP config. Today that is
- * OpenCode/KiloCode (their configs set 900000 = 15 min). Users and test
- * harnesses can also opt in explicitly with any positive integer.
- *
- * Missing or malformed env = 0 (disabled, safe default). Set env to
- * `0` to disable explicitly.
- *
- * Exported for unit-testing.
- */
-export declare function idleTimeoutForEnv(env?: NodeJS.ProcessEnv): number;
 /** Injectable dependencies for {@link makeDefaultIsParentAlive}. */
 export interface IsParentAliveDeps {
     /** Read the current ppid. Default: `() => process.ppid`. */
@@ -107,9 +60,7 @@ export declare function makeDefaultIsParentAlive(deps?: IsParentAliveDeps): () =
  */
 export declare function lifecycleGuardIntervalForEnv(env?: NodeJS.ProcessEnv): number;
 /**
- * Start the lifecycle guard. Returns a handle with `recordActivity` (call
- * on every MCP request to keep idle timer from firing) and `stop`.
- *
+ * Start the lifecycle guard. Returns a cleanup function.
  * Skipped automatically when stdin is a TTY (e.g. OpenCode ts-plugin).
  */
-export declare function startLifecycleGuard(opts: LifecycleGuardOptions): LifecycleGuardHandle;
+export declare function startLifecycleGuard(opts: LifecycleGuardOptions): () => void;

package/build/lifecycle.js

@@ -14,35 +14,6 @@
  * Cross-platform: macOS, Linux, Windows.
  */
 import { execFileSync } from "node:child_process";
-/**
- * Resolve the idle-shutdown threshold (#565).
- *
- * Idle shutdown is OFF by default (#592) because most hosts (Claude
- * Code, Codex, editor MCP clients) keep registered tool handles after a
- * clean MCP child exit and do NOT transparently respawn on the next call.
- * The global 15 min default introduced in #568 solved OpenCode's child
- * accumulation, but stranded ctx_* tools in Claude Code/Codex-style
- * hosts once the MCP server exited cleanly while the editor stayed alive.
- *
- * Hosts that are known to benefit from idle shutdown MUST opt in via
- * CONTEXT_MODE_IDLE_TIMEOUT_MS in their MCP config. Today that is
- * OpenCode/KiloCode (their configs set 900000 = 15 min). Users and test
- * harnesses can also opt in explicitly with any positive integer.
- *
- * Missing or malformed env = 0 (disabled, safe default). Set env to
- * `0` to disable explicitly.
- *
- * Exported for unit-testing.
- */
-export function idleTimeoutForEnv(env = process.env) {
-    const raw = env.CONTEXT_MODE_IDLE_TIMEOUT_MS;
-    if (raw === undefined)
-        return 0;
-    const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n < 0)
-        return 0;
-    return n;
-}
 /** Read grandparent PID via `ps -o ppid= -p $PPID`. Returns NaN on failure or Windows. */
 function readGrandparentPpidImpl() {
     if (process.platform === "win32")
@@ -124,52 +95,25 @@ export function lifecycleGuardIntervalForEnv(env = process.env) {
     return 1000;
 }
 /**
- * Start the lifecycle guard. Returns a handle with `recordActivity` (call
- * on every MCP request to keep idle timer from firing) and `stop`.
- *
+ * Start the lifecycle guard. Returns a cleanup function.
  * Skipped automatically when stdin is a TTY (e.g. OpenCode ts-plugin).
  */
 export function startLifecycleGuard(opts) {
     const interval = opts.checkIntervalMs ?? lifecycleGuardIntervalForEnv();
     const check = opts.isParentAlive ?? defaultIsParentAlive;
-    const idleTimeoutMs = opts.idleTimeoutMs ?? idleTimeoutForEnv();
-    const now = opts.now ?? Date.now;
     let stopped = false;
-    let lastActivity = now();
     const shutdown = () => {
         if (stopped)
             return;
         stopped = true;
         opts.onShutdown();
     };
-    const recordActivity = () => {
-        lastActivity = now();
-    };
-    // P0: Periodic parent liveness check.
+    // P0: Periodic parent liveness check
     const timer = setInterval(() => {
         if (!check())
             shutdown();
     }, interval);
     timer.unref();
-    // P0+: Idle shutdown (#565). Runs on its OWN tick — distinct from the
-    // 30 s parent-liveness poll — so a 15 min idle timeout actually reacts
-    // close to 15 min instead of "next 30 s tick after 15 min". Pick the
-    // tick as min(idleTimeoutMs / 6, 30 s) so a short timeout (e.g. 3 s in
-    // e2e tests, 60 s in dev) reacts within ~16 % of its window while a
-    // production 15 min timeout still polls every 30 s (cheap).
-    //
-    // Skipped on TTY because interactive dev sessions are expected to
-    // sit idle between commands, and also when idleTimeoutMs is 0 (env
-    // opt-out via CONTEXT_MODE_IDLE_TIMEOUT_MS=0).
-    let idleTimer = null;
-    if (idleTimeoutMs > 0 && !process.stdin.isTTY) {
-        const idleTick = Math.max(50, Math.min(Math.floor(idleTimeoutMs / 6), 30_000));
-        idleTimer = setInterval(() => {
-            if (now() - lastActivity > idleTimeoutMs)
-                shutdown();
-        }, idleTick);
-        idleTimer.unref();
-    }
     // P0: OS signals — terminal close, kill, ctrl+c
     const signals = ["SIGTERM", "SIGINT"];
     if (process.platform !== "win32")
@@ -198,19 +142,11 @@ export function startLifecycleGuard(opts) {
     if (!process.stdin.isTTY) {
         process.stdin.on("end", onStdinEnd);
     }
-    const cleanup = () => {
+    return () => {
         stopped = true;
         clearInterval(timer);
-        if (idleTimer)
-            clearInterval(idleTimer);
         for (const sig of signals)
             process.removeListener(sig, shutdown);
         process.stdin.removeListener("end", onStdinEnd);
     };
-    // Hybrid: callable for legacy `const cleanup = startLifecycleGuard(...)`
-    // sites, with `.recordActivity` / `.stop` properties for the new contract.
-    const handle = cleanup;
-    handle.recordActivity = recordActivity;
-    handle.stop = cleanup;
-    return handle;
 }

package/build/openclaw-plugin.d.ts

@@ -0,0 +1,130 @@
+/**
+ * OpenClaw TypeScript plugin entry point for context-mode.
+ *
+ * Exports an object with { id, name, configSchema, register(api) } for
+ * declarative metadata and config validation before code execution.
+ *
+ * register(api) registers:
+ *   - before_tool_call hook   — Routing enforcement (deny/modify/passthrough)
+ *   - after_tool_call hook    — Session event capture
+ *   - command:new hook         — Session initialization and cleanup
+ *   - session_start hook             — Re-key DB session to OpenClaw's session ID
+ *   - before_compaction hook         — Flush events to resume snapshot
+ *   - after_compaction hook          — Increment compact count
+ *   - before_prompt_build (p=10)  — Resume snapshot injection into system context
+ *   - before_prompt_build (p=5)   — Routing instruction injection into system context
+ *   - context-mode engine      — Context engine with compaction management
+ *   - /ctx-stats command       — Auto-reply command for session statistics
+ *   - /ctx-doctor command      — Auto-reply command for diagnostics
+ *   - /ctx-upgrade command     — Auto-reply command for upgrade
+ *
+ * Loaded by OpenClaw via: openclaw.extensions entry in package.json
+ *
+ * OpenClaw plugin paradigm:
+ *   - Plugins export { id, name, configSchema, register(api) } for metadata
+ *   - api.registerHook() for event-driven hooks
+ *   - api.on() for typed lifecycle hooks
+ *   - api.registerContextEngine() for compaction ownership
+ *   - api.registerCommand() for auto-reply slash commands
+ *   - Plugins run in-process with the Gateway (trusted code)
+ */
+import type { OpenClawToolDef } from "./openclaw/mcp-tools.js";
+/** Context for auto-reply command handlers. */
+interface CommandContext {
+    senderId?: string;
+    channel?: string;
+    isAuthorizedSender?: boolean;
+    args?: string;
+    commandBody?: string;
+    config?: Record<string, unknown>;
+}
+/** OpenClaw plugin API provided to the register function. */
+interface OpenClawPluginApi {
+    registerHook(event: string, handler: (...args: unknown[]) => unknown, meta: {
+        name: string;
+        description: string;
+    }): void;
+    /**
+     * Register a typed lifecycle hook.
+     * Supported names: "session_start", "before_compaction", "after_compaction",
+     * "before_prompt_build"
+     */
+    on(event: string, handler: (...args: unknown[]) => unknown, opts?: {
+        priority?: number;
+    }): void;
+    registerContextEngine(id: string, factory: () => ContextEngineInstance): void;
+    registerCommand?(cmd: {
+        name: string;
+        description: string;
+        acceptsArgs?: boolean;
+        requireAuth?: boolean;
+        handler: (ctx: CommandContext) => {
+            text: string;
+        } | Promise<{
+            text: string;
+        }>;
+    }): void;
+    registerCli?(factory: (ctx: {
+        program: unknown;
+    }) => void, meta: {
+        commands: string[];
+    }): void;
+    /**
+     * Register an agent tool (OpenClaw native registerTool) — see
+     * refs/platforms/openclaw/docs/plugins/building-plugins.md:116. Optional in
+     * the type so we degrade silently on legacy hosts that pre-date this API.
+     */
+    registerTool?(tool: OpenClawToolDef, opts?: {
+        optional?: boolean;
+    }): void;
+    logger?: {
+        info: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+        debug?: (...args: unknown[]) => void;
+        warn?: (...args: unknown[]) => void;
+    };
+}
+/** Context engine instance returned by the factory. */
+interface ContextEngineInstance {
+    info: {
+        id: string;
+        name: string;
+        ownsCompaction: boolean;
+    };
+    ingest(data: unknown): Promise<{
+        ingested: boolean;
+    }>;
+    assemble(ctx: {
+        messages: unknown[];
+    }): Promise<{
+        messages: unknown[];
+        estimatedTokens: number;
+    }>;
+    compact(): Promise<{
+        ok: boolean;
+        compacted: boolean;
+    }>;
+}
+/**
+ * OpenClaw plugin definition. The object form provides declarative metadata
+ * (id, name, configSchema) that OpenClaw can read without executing code.
+ * register() is called once per agent session with a fresh api object.
+ * Each call creates isolated closures (db, sessionId, hooks) — no shared state.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    configSchema: {
+        type: "object";
+        properties: {
+            enabled: {
+                type: "boolean";
+                default: boolean;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default _default;