context-mode 1.0.125 → 1.0.127

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.125"
+    "version": "1.0.127"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.125",
+      "version": "1.0.127",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.125",
+  "version": "1.0.127",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.125",
+  "version": "1.0.127",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.125",
+  "version": "1.0.127",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/build/adapters/claude-code/hooks.d.ts

@@ -80,11 +80,17 @@ export declare function isContextModeHook(entry: {
 export declare function buildHookCommand(hookType: HookType, pluginRoot?: string): string;
 /**
  * Extract the hook script file path from a command string.
- * Returns the path if the command uses the `node "/path/to/hook.mjs"` format
- * or the new `"/path/to/node" "/path/to/hook.mjs"` format (#369, #372),
- * or null if it uses the CLI dispatcher format (which is path-independent).
  *
- * Handles both quoted and unquoted paths, and both forward/back slashes.
+ * Algo-D2 twin — same shape as `src/util/hook-config.ts::extractHookScriptPath`.
+ * Delegates to `parseNodeCommand` for canonical buildNodeCommand-shape;
+ * keeps narrow legacy fallbacks for pre-D3 settings.json entries
+ * (`node "X.mjs"` and `node X.mjs` with no internal whitespace).
+ *
+ * Pre-D2 this matched `node\s+"?([^"]+\.mjs)"?` — the unquoted fallback
+ * silently grabbed the tail after the last whitespace, producing the
+ * #548 doubled-path FAIL on Windows paths with spaces. The new shape
+ * refuses ambiguous input; doctor (Algo-D1) falls through to direct
+ * `existsSync` instead of trusting the regex.
  */
 export declare function extractHookScriptPath(command: string): string | null;
 /**

package/build/adapters/claude-code/hooks.js

@@ -1,4 +1,4 @@
-import { buildNodeCommand } from "../types.js";
+import { buildNodeCommand, parseNodeCommand } from "../types.js";
 /**
  * adapters/claude-code/hooks — Claude Code hook definitions and matchers.
  *
@@ -142,20 +142,30 @@ export function buildHookCommand(hookType, pluginRoot) {
 }
 /**
  * Extract the hook script file path from a command string.
- * Returns the path if the command uses the `node "/path/to/hook.mjs"` format
- * or the new `"/path/to/node" "/path/to/hook.mjs"` format (#369, #372),
- * or null if it uses the CLI dispatcher format (which is path-independent).
  *
- * Handles both quoted and unquoted paths, and both forward/back slashes.
+ * Algo-D2 twin — same shape as `src/util/hook-config.ts::extractHookScriptPath`.
+ * Delegates to `parseNodeCommand` for canonical buildNodeCommand-shape;
+ * keeps narrow legacy fallbacks for pre-D3 settings.json entries
+ * (`node "X.mjs"` and `node X.mjs` with no internal whitespace).
+ *
+ * Pre-D2 this matched `node\s+"?([^"]+\.mjs)"?` — the unquoted fallback
+ * silently grabbed the tail after the last whitespace, producing the
+ * #548 doubled-path FAIL on Windows paths with spaces. The new shape
+ * refuses ambiguous input; doctor (Algo-D1) falls through to direct
+ * `existsSync` instead of trusting the regex.
  */
 export function extractHookScriptPath(command) {
-    // New format: "nodePath" "scriptPath.mjs" (from buildNodeCommand)
-    const newFmt = command.match(/"[^"]+"\s+"([^"]+\.mjs)"/);
-    if (newFmt)
-        return newFmt[1];
-    // Legacy format: node "/path/to/hooks/scriptname.mjs" or node /path/to/hooks/scriptname.mjs
-    const match = command.match(/node\s+"?([^"]+\.mjs)"?/);
-    return match?.[1] ?? null;
+    const parsed = parseNodeCommand(command);
+    if (parsed) {
+        return parsed.scriptPath.endsWith(".mjs") ? parsed.scriptPath : null;
+    }
+    const legacyQuoted = command.match(/^\s*node\s+"([^"]+\.mjs)"\s*$/);
+    if (legacyQuoted)
+        return legacyQuoted[1];
+    const legacyBare = command.match(/^\s*node\s+(\S+\.mjs)\s*$/);
+    if (legacyBare)
+        return legacyBare[1];
+    return null;
 }
 /**
  * Check if a hook entry is a context-mode hook (any hook type).

package/build/adapters/claude-code/index.d.ts

@@ -12,7 +12,7 @@
  *   - Plugin registry: <configDir>/plugins/installed_plugins.json
  */
 import { ClaudeCodeBaseAdapter, type ClaudeCodeWireInput } from "../claude-code-base.js";
-import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, HookRegistration } from "../types.js";
+import { type HookAdapter, type HookParadigm, type PlatformCapabilities, type DiagnosticResult, type HookRegistration, type HealthCheck } from "../types.js";
 export declare class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter implements HookAdapter {
     constructor();
     readonly name = "Claude Code";
@@ -44,6 +44,29 @@ export declare class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter implements
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;
     validateHooks(pluginRoot: string): DiagnosticResult[];
+    /**
+     * Adapter-defined health checks (Algo-D1 + Algo-D5).
+     *
+     * For each entry in HOOK_SCRIPTS (the canonical hookType → scriptName
+     * map), emit a HealthCheck that joins `pluginRoot + "hooks" +
+     * scriptName` and probes via `existsSync`. Crucially, this NEVER
+     * parses a hook command — pluginRoot and scriptName are both in our
+     * hand, so the regex round-trip that produced the #548 doubled-path
+     * FAIL is bypassed entirely.
+     *
+     * The hook check derives from HOOK_SCRIPTS (single source of truth in
+     * src/adapters/claude-code/hooks.ts), so adding a new hook event in
+     * that map auto-extends doctor coverage — no parallel hardcoded list
+     * to maintain.
+     *
+     * Algo-D5: appends a single "Plugin cache integrity" check that
+     * delegates to the same helper start.mjs uses at boot
+     * (scripts/plugin-cache-integrity.mjs::assertPluginCacheIntegrity).
+     * Same code, two callsites — boot fail-fast and doctor diagnostic
+     * agree byte-for-byte. Users hitting #550 get the actionable signal
+     * without restarting the MCP server.
+     */
+    getHealthChecks(pluginRoot: string): readonly HealthCheck[];
     /** Read plugin hooks from hooks/hooks.json or .claude-plugin/hooks/hooks.json */
     private readPluginHooks;
     /** Check if a hook type is configured in either settings.json or plugin hooks */

package/build/adapters/claude-code/index.js

@@ -16,6 +16,8 @@ import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { ClaudeCodeBaseAdapter } from "../claude-code-base.js";
 import { resolveClaudeConfigDir } from "../../util/claude-config.js";
+import { checkPluginCacheIntegritySync } from "../../util/plugin-cache-integrity.js";
+import { buildNodeCommand, } from "../types.js";
 import { HOOK_TYPES, HOOK_SCRIPTS, REQUIRED_HOOKS, PRE_TOOL_USE_MATCHERS, PRE_TOOL_USE_MATCHER_PATTERN, isContextModeHook, isAnyContextModeHook, extractHookScriptPath, buildHookCommand, } from "./hooks.js";
 // ─────────────────────────────────────────────────────────
 // Adapter implementation
@@ -67,13 +69,20 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
         return join(this.getConfigDir(), "settings.json");
     }
     generateHookConfig(pluginRoot) {
-        // Paths must be double-quoted so that hosts (or our own diagnostic
-        // regex) parse them correctly when pluginRoot contains spaces — common
-        // on Windows where the user folder is e.g. "C:\Users\First Last\...".
-        // Without quotes, extractHookScriptPath's `\S+\.mjs` fallback grabs
-        // only the tail after the last space, producing a doubled-path FAIL
-        // in `ctx doctor`. Matches the quoting style used in hooks/hooks.json.
-        const preToolUseCommand = `node "${pluginRoot}/hooks/pretooluse.mjs"`;
+        // Algo-D3: every command flows through `buildNodeCommand` (defined in
+        // src/adapters/types.ts), which:
+        //   - quotes both nodePath and scriptPath (#548 — Windows pluginRoots
+        //     with spaces no longer fall through extractHookScriptPath's
+        //     ambiguous-tail fallback),
+        //   - swaps backslashes for forward slashes (#372 MSYS path mangling),
+        //   - uses `process.execPath` instead of bare `node` (#369 PATH
+        //     resolution on Git Bash).
+        // Pre-D3 we hand-rolled `node "${pluginRoot}/hooks/X.mjs"` for all
+        // five events; bare `node` made claude-code the lone outlier and
+        // dropping the execPath swap re-opened the Windows class. Algo-D3.5
+        // (CI invariant in tests/adapters/claude-code.test.ts) locks this in
+        // for adapter #16.
+        const preToolUseCommand = buildNodeCommand(`${pluginRoot}/hooks/pretooluse.mjs`);
         const preToolUseMatchers = [...PRE_TOOL_USE_MATCHERS];
         return {
             PreToolUse: preToolUseMatchers.map((matcher) => ({
@@ -86,7 +95,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: `node "${pluginRoot}/hooks/posttooluse.mjs"`,
+                            command: buildNodeCommand(`${pluginRoot}/hooks/posttooluse.mjs`),
                         },
                     ],
                 },
@@ -97,7 +106,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: `node "${pluginRoot}/hooks/precompact.mjs"`,
+                            command: buildNodeCommand(`${pluginRoot}/hooks/precompact.mjs`),
                         },
                     ],
                 },
@@ -108,7 +117,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: `node "${pluginRoot}/hooks/userpromptsubmit.mjs"`,
+                            command: buildNodeCommand(`${pluginRoot}/hooks/userpromptsubmit.mjs`),
                         },
                     ],
                 },
@@ -119,7 +128,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: `node "${pluginRoot}/hooks/sessionstart.mjs"`,
+                            command: buildNodeCommand(`${pluginRoot}/hooks/sessionstart.mjs`),
                         },
                     ],
                 },
@@ -177,6 +186,53 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
         });
         return results;
     }
+    /**
+     * Adapter-defined health checks (Algo-D1 + Algo-D5).
+     *
+     * For each entry in HOOK_SCRIPTS (the canonical hookType → scriptName
+     * map), emit a HealthCheck that joins `pluginRoot + "hooks" +
+     * scriptName` and probes via `existsSync`. Crucially, this NEVER
+     * parses a hook command — pluginRoot and scriptName are both in our
+     * hand, so the regex round-trip that produced the #548 doubled-path
+     * FAIL is bypassed entirely.
+     *
+     * The hook check derives from HOOK_SCRIPTS (single source of truth in
+     * src/adapters/claude-code/hooks.ts), so adding a new hook event in
+     * that map auto-extends doctor coverage — no parallel hardcoded list
+     * to maintain.
+     *
+     * Algo-D5: appends a single "Plugin cache integrity" check that
+     * delegates to the same helper start.mjs uses at boot
+     * (scripts/plugin-cache-integrity.mjs::assertPluginCacheIntegrity).
+     * Same code, two callsites — boot fail-fast and doctor diagnostic
+     * agree byte-for-byte. Users hitting #550 get the actionable signal
+     * without restarting the MCP server.
+     */
+    getHealthChecks(pluginRoot) {
+        const hookChecks = Object.entries(HOOK_SCRIPTS).map(([hookType, scriptName]) => {
+            const absolutePath = join(pluginRoot, "hooks", scriptName);
+            return {
+                name: `Hook script: ${hookType} (${scriptName})`,
+                check: () => {
+                    // Direct existsSync — no hook-command parsing, no regex.
+                    // pluginRoot is the value the doctor was invoked with;
+                    // scriptName comes from the canonical HOOK_SCRIPTS map.
+                    if (existsSync(absolutePath)) {
+                        return { status: "OK", detail: absolutePath };
+                    }
+                    return {
+                        status: "FAIL",
+                        detail: `not found at ${absolutePath}`,
+                    };
+                },
+            };
+        });
+        const integrityCheck = {
+            name: "Plugin cache integrity",
+            check: () => checkPluginCacheIntegritySync(pluginRoot),
+        };
+        return [...hookChecks, integrityCheck];
+    }
     /** Read plugin hooks from hooks/hooks.json or .claude-plugin/hooks/hooks.json */
     readPluginHooks(pluginRoot) {
         const candidates = [

package/build/adapters/types.d.ts

@@ -206,6 +206,21 @@ export interface HookAdapter {
     writeSettings(settings: Record<string, unknown>): void;
     /** Validate that hooks are properly configured for this platform. */
     validateHooks(pluginRoot: string): DiagnosticResult[];
+    /**
+     * Adapter-defined per-platform health checks (Algo-D1).
+     *
+     * OPTIONAL. Adapters that don't override return nothing — they don't
+     * have this class of check today. claude-code overrides with hook-script
+     * existence checks that join `pluginRoot + scriptName` directly via
+     * `existsSync`, so doctor never round-trips through a regex on a hook
+     * command (the #548 root cause).
+     *
+     * Adapter #16 with hook scripts inherits the contract by overriding;
+     * adapter #17 without hook scripts simply doesn't override. The doctor
+     * iterates `adapter.getHealthChecks?.(pluginRoot) ?? []` and renders
+     * each — no per-adapter wiring in the doctor body.
+     */
+    getHealthChecks?(pluginRoot: string): readonly HealthCheck[];
     /** Check if the plugin is registered/enabled on this platform. */
     checkPluginRegistration(): DiagnosticResult;
     /** Get the installed version from this platform's registry/marketplace. */
@@ -230,6 +245,26 @@ export interface DiagnosticResult {
     /** Suggested fix command (if applicable). */
     fix?: string;
 }
+/**
+ * Adapter-defined health check (Algo-D1).
+ *
+ * Lighter-weight than `DiagnosticResult`: adapters declare a name and a
+ * synchronous `check()` thunk. The doctor renders the result. The
+ * thunk-style intentionally avoids forcing adapters into async — the
+ * existsSync probe used by claude-code is sync and the doctor invokes it
+ * directly without an `await`. Adapters needing async work return a
+ * pre-resolved status (the check ran at thunk-creation time) or extend
+ * `validateHooks()` instead.
+ */
+export interface HealthCheck {
+    /** Human-readable check title (e.g. "Hook script exists: pretooluse.mjs"). */
+    readonly name: string;
+    /** Synchronous check thunk. Returns OK or FAIL with optional detail. */
+    check(): {
+        status: "OK" | "FAIL";
+        detail?: string;
+    };
+}
 /**
  * Build a cross-platform `node <script>` command string.
  *
@@ -243,6 +278,28 @@ export interface DiagnosticResult {
  * Safe on macOS/Linux — quoting and forward slashes are no-ops there.
  */
 export declare function buildNodeCommand(scriptPath: string): string;
+/**
+ * Strict inverse of `buildNodeCommand`.
+ *
+ * Returns `{ nodePath, scriptPath }` ONLY when `cmd` could have been
+ * produced by `buildNodeCommand` — i.e. exactly two double-quoted args
+ * separated by whitespace. Anything else (bare `node …`, single quotes,
+ * unquoted ambiguous input, CLI dispatcher entries) returns `null`.
+ *
+ * Why strict: the legacy `\S+\.mjs` fallback in
+ * `src/util/hook-config.ts:24` and the two-step regex in
+ * `src/adapters/claude-code/hooks.ts:178` silently grabbed the path tail
+ * after the last whitespace whenever the host wire-format dropped quotes,
+ * producing the #548 doubled-path FAIL when `pluginRoot` contained
+ * spaces (e.g. `C:\Users\High Ground Services\…`). A canonical inverse
+ * lets every emit (`buildNodeCommand`) round-trip through every parse
+ * (`parseNodeCommand`) without inventing fallbacks. Adapter #16 inherits
+ * the contract by importing one module.
+ */
+export declare function parseNodeCommand(cmd: string): {
+    nodePath: string;
+    scriptPath: string;
+} | null;
 /** Supported platform identifiers. */
 export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "omp" | "zed" | "qwen-code" | "unknown";
 /** Detection signal used to identify which platform is running. */

package/build/adapters/types.js

@@ -33,3 +33,32 @@ export function buildNodeCommand(scriptPath) {
     const safePath = scriptPath.replace(/\\/g, "/");
     return `"${nodePath}" "${safePath}"`;
 }
+/**
+ * Strict inverse of `buildNodeCommand`.
+ *
+ * Returns `{ nodePath, scriptPath }` ONLY when `cmd` could have been
+ * produced by `buildNodeCommand` — i.e. exactly two double-quoted args
+ * separated by whitespace. Anything else (bare `node …`, single quotes,
+ * unquoted ambiguous input, CLI dispatcher entries) returns `null`.
+ *
+ * Why strict: the legacy `\S+\.mjs` fallback in
+ * `src/util/hook-config.ts:24` and the two-step regex in
+ * `src/adapters/claude-code/hooks.ts:178` silently grabbed the path tail
+ * after the last whitespace whenever the host wire-format dropped quotes,
+ * producing the #548 doubled-path FAIL when `pluginRoot` contained
+ * spaces (e.g. `C:\Users\High Ground Services\…`). A canonical inverse
+ * lets every emit (`buildNodeCommand`) round-trip through every parse
+ * (`parseNodeCommand`) without inventing fallbacks. Adapter #16 inherits
+ * the contract by importing one module.
+ */
+export function parseNodeCommand(cmd) {
+    if (typeof cmd !== "string" || cmd.length === 0)
+        return null;
+    // Match `"<nodePath>" "<scriptPath>"` with arbitrary whitespace
+    // separator. Both segments must be non-empty and contain no embedded
+    // double quotes — buildNodeCommand never emits embedded quotes.
+    const m = cmd.match(/^"([^"]+)"\s+"([^"]+)"\s*$/);
+    if (!m)
+        return null;
+    return { nodePath: m[1], scriptPath: m[2] };
+}

package/build/cli.js

@@ -368,22 +368,47 @@ async function doctor() {
                 (result.fix ? color.dim(`\n  Run: ${result.fix}`) : ""));
         }
     }
-    // Hook scripts exist
+    // Hook scripts exist — Algo-D1 protocol path takes precedence.
+    // Adapters that override `getHealthChecks` (claude-code today) get a
+    // direct `existsSync(join(pluginRoot, "hooks", scriptName))` per
+    // HOOK_SCRIPTS entry — no regex round-trip on a hook command, so the
+    // #548 doubled-path FAIL class can't surface. Adapters that don't
+    // override fall through to the legacy `getHookScriptPaths` flow which
+    // generates the hook config and parses each command via
+    // `extractHookScriptPath`. Post-D3 every adapter emits buildNodeCommand-
+    // shape, so the legacy flow is also safe — but the direct existsSync
+    // path is strictly preferable when the adapter offers it.
     p.log.step("Checking hook scripts...");
-    const hookScriptPaths = getHookScriptPaths(adapter, pluginRoot);
-    if (hookScriptPaths.length === 0) {
-        p.log.success(color.green("Hook scripts: PASS") + color.dim(" — no direct .mjs script paths to verify"));
+    const adapterHealthChecks = adapter.getHealthChecks?.(pluginRoot) ?? [];
+    if (adapterHealthChecks.length > 0) {
+        for (const hc of adapterHealthChecks) {
+            const result = hc.check();
+            if (result.status === "OK") {
+                p.log.success(color.green(`${hc.name}: PASS`) +
+                    (result.detail ? color.dim(` — ${result.detail}`) : ""));
+            }
+            else {
+                p.log.error(color.red(`${hc.name}: FAIL`) +
+                    (result.detail ? color.dim(` — ${result.detail}`) : ""));
+            }
+        }
     }
     else {
-        for (const scriptPath of hookScriptPaths) {
-            const absolutePath = resolve(pluginRoot, scriptPath);
-            try {
-                accessSync(absolutePath, constants.R_OK);
-                p.log.success(color.green("Hook script exists: PASS") + color.dim(` — ${absolutePath}`));
-            }
-            catch {
-                p.log.error(color.red("Hook script exists: FAIL") +
-                    color.dim(` — not found at ${absolutePath}`));
+        const hookScriptPaths = getHookScriptPaths(adapter, pluginRoot);
+        if (hookScriptPaths.length === 0) {
+            p.log.success(color.green("Hook scripts: PASS") + color.dim(" — no direct .mjs script paths to verify"));
+        }
+        else {
+            for (const scriptPath of hookScriptPaths) {
+                const absolutePath = resolve(pluginRoot, scriptPath);
+                try {
+                    accessSync(absolutePath, constants.R_OK);
+                    p.log.success(color.green("Hook script exists: PASS") + color.dim(` — ${absolutePath}`));
+                }
+                catch {
+                    p.log.error(color.red("Hook script exists: FAIL") +
+                        color.dim(` — not found at ${absolutePath}`));
+                }
             }
         }
     }

package/build/server.js

@@ -198,6 +198,12 @@ function getProjectDir() {
     // path on detected platform so non-Claude hosts skip the heuristic and
     // fall through to PWD/cwd cleanly.
     //
+    // The Claude heuristic must also be fresh. Hosts such as Pi can be
+    // misdetected as Claude Code solely because ~/.claude exists; without a
+    // freshness guard an old Claude transcript can globally hijack ctx shell cwd
+    // after reboot. Active Claude sessions update their transcript as the user
+    // interacts, so stale transcripts should fall through to PWD/cwd.
+    //
     // Issue #545 (v1.0.124): pass strictPlatform for ALL adapters so the
     // env-var cascade is built ALGORITHMICALLY from the platform's own
     // workspace vars + universal escape hatch — foreign workspace vars (e.g.
@@ -220,6 +226,7 @@ function getProjectDir() {
         cwd: process.cwd(),
         pwd: process.env.PWD,
         transcriptsRoot,
+        transcriptMaxAgeMs: 5 * 60 * 1000,
         strictPlatform,
     });
 }

package/build/util/hook-config.d.ts

@@ -1,4 +1,27 @@
-import type { HookAdapter } from "../adapters/types.js";
+import { type HookAdapter } from "../adapters/types.js";
 export declare function getCommandsFromHookEntry(entry: unknown): string[];
+/**
+ * Extract the hook script path from a hook command string.
+ *
+ * Post Algo-D2 this is a thin wrapper around `parseNodeCommand` with a
+ * single legacy fallback retained for stale-entry cleanup
+ * (`configureAllHooks` walks pre-v1.0.124 settings.json shapes that
+ * predate `buildNodeCommand`). The legacy branches are deliberately
+ * narrow:
+ *
+ *   1) Canonical: `"<nodePath>" "<scriptPath>.mjs"` — `parseNodeCommand`
+ *      handles this; round-trips with `buildNodeCommand`.
+ *   2) Legacy quoted: `node "<scriptPath>.mjs"` — emitted by claude-code
+ *      pre-D3. The script segment is fully quoted, no whitespace
+ *      ambiguity.
+ *   3) Legacy unquoted: `node <scriptPath>.mjs` — only when the entire
+ *      command is whitespace-safe (exactly two whitespace-separated
+ *      tokens). The #548 wire shape — `node C:/Users/High Ground …` —
+ *      contains internal whitespace so this branch refuses it. Returns
+ *      `null` instead of grabbing the tail after the last whitespace.
+ *
+ * Anything else returns `null`, letting the doctor (Algo-D1) fall
+ * through to direct `existsSync` instead of trusting the regex.
+ */
 export declare function extractHookScriptPath(command: string): string | null;
 export declare function getHookScriptPaths(adapter: HookAdapter, pluginRoot: string): string[];

package/build/util/hook-config.js

@@ -1,3 +1,4 @@
+import { parseNodeCommand } from "../adapters/types.js";
 export function getCommandsFromHookEntry(entry) {
     const commands = [];
     if (entry && typeof entry === "object") {
@@ -17,9 +18,45 @@ export function getCommandsFromHookEntry(entry) {
     }
     return commands;
 }
+/**
+ * Extract the hook script path from a hook command string.
+ *
+ * Post Algo-D2 this is a thin wrapper around `parseNodeCommand` with a
+ * single legacy fallback retained for stale-entry cleanup
+ * (`configureAllHooks` walks pre-v1.0.124 settings.json shapes that
+ * predate `buildNodeCommand`). The legacy branches are deliberately
+ * narrow:
+ *
+ *   1) Canonical: `"<nodePath>" "<scriptPath>.mjs"` — `parseNodeCommand`
+ *      handles this; round-trips with `buildNodeCommand`.
+ *   2) Legacy quoted: `node "<scriptPath>.mjs"` — emitted by claude-code
+ *      pre-D3. The script segment is fully quoted, no whitespace
+ *      ambiguity.
+ *   3) Legacy unquoted: `node <scriptPath>.mjs` — only when the entire
+ *      command is whitespace-safe (exactly two whitespace-separated
+ *      tokens). The #548 wire shape — `node C:/Users/High Ground …` —
+ *      contains internal whitespace so this branch refuses it. Returns
+ *      `null` instead of grabbing the tail after the last whitespace.
+ *
+ * Anything else returns `null`, letting the doctor (Algo-D1) fall
+ * through to direct `existsSync` instead of trusting the regex.
+ */
 export function extractHookScriptPath(command) {
-    const match = command.match(/(?:"([^"]+\.mjs)"|'([^']+\.mjs)'|(\S+\.mjs))/);
-    return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+    const parsed = parseNodeCommand(command);
+    if (parsed) {
+        return parsed.scriptPath.endsWith(".mjs") ? parsed.scriptPath : null;
+    }
+    // Legacy quoted: `node "/path/with spaces/x.mjs"` (pre-D3 claude-code emit).
+    const legacyQuoted = command.match(/^\s*node\s+"([^"]+\.mjs)"\s*$/);
+    if (legacyQuoted)
+        return legacyQuoted[1];
+    // Legacy unquoted: `node /path/x.mjs` — refuses internal whitespace
+    // by anchoring both tokens. The #548 ambiguous shape has 3+ tokens
+    // (spaces in the path) and falls through to `null`.
+    const legacyBare = command.match(/^\s*node\s+(\S+\.mjs)\s*$/);
+    if (legacyBare)
+        return legacyBare[1];
+    return null;
 }
 export function getHookScriptPaths(adapter, pluginRoot) {
     const paths = new Set();

package/build/util/plugin-cache-integrity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TypeScript surface for the start.mjs plugin-cache integrity helper.
+ *
+ * The actual logic lives in `scripts/plugin-cache-integrity.mjs` (raw
+ * `.mjs` so start.mjs can import it without a TS toolchain at boot —
+ * #550 fail-fast happens BEFORE any bundle is loaded). This module is
+ * the bridge that lets TS consumers (claude-code adapter's
+ * getHealthChecks for Algo-D5, the cli doctor surface) call the same
+ * function without duplicating the implementation.
+ *
+ * Single source of truth: scripts/plugin-cache-integrity.mjs. Boot
+ * fail-fast (Algo-D4) and doctor diagnostic (Algo-D5) agree
+ * byte-for-byte because they call the same exported function.
+ *
+ * Top-level dynamic import is used (not a static `import` from `.mjs`)
+ * because the project is ESM and `import` of a sibling `.mjs` from a
+ * `.ts` file relies on the bundler / loader resolving `.mjs`
+ * extensions, which esbuild can do but tsc-only typecheck cannot. The
+ * dynamic import is resolved by the runtime (Node ESM) regardless of
+ * how the consumer was bundled. Errors are caught and surfaced as a
+ * FAIL detail — the helper is required to ship in the npm tarball
+ * (package.json files[]); a missing helper means the install is
+ * fundamentally broken.
+ */
+/**
+ * Run the integrity check synchronously. If the helper module is
+ * still loading (not yet cached) returns a FAIL with detail
+ * "integrity helper not yet loaded" — caller should retry once the
+ * doctor command's IO is complete. In practice the doctor is invoked
+ * many MS after module load so this fallback is defensive only.
+ */
+export declare function checkPluginCacheIntegritySync(pluginRoot: string): {
+    status: "OK" | "FAIL";
+    detail: string;
+};
+/** Force-await the helper load. Tests use this to deflake the eager fire-and-forget. */
+export declare function ensurePluginCacheIntegrityLoaded(): Promise<void>;