context-mode 1.0.125 → 1.0.127

package/hooks/core/routing.mjs

@@ -249,39 +249,88 @@ let securityInitFailed = false;
 /**
  * @returns {boolean} true if security module loaded successfully.
  *
- * Loud fail: if `build/security.js` is missing or fails to import, log a
- * clear stderr warning instead of swallowing the error silently. Without
- * this, user-configured `permissions.deny` patterns (#466) become no-ops
- * with no indication that policy enforcement is disabled — a fail-open
- * security regression.
+ * Loud fail: if neither the esbuild bundle nor `build/security.js` is
+ * importable, log a clear stderr warning instead of swallowing the error
+ * silently. Without this, user-configured `permissions.deny` patterns
+ * (#466) become no-ops with no indication that policy enforcement is
+ * disabled — a fail-open security regression.
+ *
+ * ─── Resolution order (#558) ───────────────────────────────────────────
+ *
+ *   1. `hooks/security.bundle.mjs` — esbuild output, sibling of routing.mjs's
+ *      parent. Marketplace installs (`git clone` install path) ship this
+ *      bundle via CI's `git add -f`, so it's the only artifact reliably
+ *      present across BOTH `npm install` (build/ generated by tsc) AND
+ *      marketplace install (build/ excluded by .gitignore, never built).
+ *
+ *   2. `<buildDir>/security.js` — tsc output. Present after `npm run build`.
+ *      Kept as a fallback so source checkouts that bypass `npm run bundle`
+ *      still degrade gracefully to the tsc-emitted module.
+ *
+ * Bundle path is computed from `import.meta.url` (sibling layout:
+ * `hooks/core/routing.mjs` → `hooks/security.bundle.mjs`).
+ * `CONTEXT_MODE_SECURITY_BUNDLE_PATH` is a test seam — it lets
+ * subprocess-based tests stage a bundle in tmpdir without polluting the
+ * repo's hooks/ directory.
  */
 export async function initSecurity(buildDir) {
-  try {
-    const { existsSync } = await import("node:fs");
-    const { resolve } = await import("node:path");
-    const { pathToFileURL } = await import("node:url");
-    const secPath = resolve(buildDir, "security.js");
-    if (!existsSync(secPath)) {
+  const { existsSync } = await import("node:fs");
+  const { resolve, dirname } = await import("node:path");
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+
+  // Default: <hooks/core/ dir>/../security.bundle.mjs → hooks/security.bundle.mjs.
+  const defaultBundlePath = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "security.bundle.mjs",
+  );
+  const bundlePath = process.env.CONTEXT_MODE_SECURITY_BUNDLE_PATH || defaultBundlePath;
+  const secPath = resolve(buildDir, "security.js");
+
+  // Bundle-first: marketplace installs ship the bundle, never the build/ dir.
+  if (existsSync(bundlePath)) {
+    try {
+      security = await import(pathToFileURL(bundlePath).href);
+      return true;
+    } catch (err) {
       if (!securityInitFailed && !process.env.CONTEXT_MODE_SUPPRESS_SECURITY_WARNING) {
         process.stderr.write(
-          `[context-mode] WARNING: ${secPath} not found — security deny patterns will NOT be enforced. ` +
-            `Run \`npm run build\` to generate it. Set CONTEXT_MODE_SUPPRESS_SECURITY_WARNING=1 to silence.\n`,
+          `[context-mode] WARNING: failed to load security bundle (${bundlePath}) — deny patterns NOT enforced: ${err?.message ?? err}\n`,
         );
       }
       securityInitFailed = true;
       return false;
     }
-    security = await import(pathToFileURL(secPath).href);
-    return true;
-  } catch (err) {
-    if (!securityInitFailed && !process.env.CONTEXT_MODE_SUPPRESS_SECURITY_WARNING) {
-      process.stderr.write(
-        `[context-mode] WARNING: failed to load security module — deny patterns NOT enforced: ${err?.message ?? err}\n`,
-      );
+  }
+
+  // Fallback: tsc-emitted build/security.js (source checkout + `npm run build`).
+  if (existsSync(secPath)) {
+    try {
+      security = await import(pathToFileURL(secPath).href);
+      return true;
+    } catch (err) {
+      if (!securityInitFailed && !process.env.CONTEXT_MODE_SUPPRESS_SECURITY_WARNING) {
+        process.stderr.write(
+          `[context-mode] WARNING: failed to load security module — deny patterns NOT enforced: ${err?.message ?? err}\n`,
+        );
+      }
+      securityInitFailed = true;
+      return false;
     }
-    securityInitFailed = true;
-    return false;
   }
+
+  // Neither artifact present — preserve fail-open with an actionable warning
+  // that mentions BOTH paths so users on either install model can self-diagnose.
+  if (!securityInitFailed && !process.env.CONTEXT_MODE_SUPPRESS_SECURITY_WARNING) {
+    process.stderr.write(
+      `[context-mode] WARNING: security module not found — security deny patterns will NOT be enforced.\n` +
+        `  Searched: ${bundlePath} (bundle) and ${secPath} (build).\n` +
+        `  Marketplace installs ship hooks/security.bundle.mjs via CI; for source checkouts run \`npm run bundle\` (or \`npm run build\`).\n` +
+        `  Set CONTEXT_MODE_SUPPRESS_SECURITY_WARNING=1 to silence.\n`,
+    );
+  }
+  securityInitFailed = true;
+  return false;
 }
 
 /** @returns {boolean} true if a previous initSecurity() call failed to load the module. */
@@ -289,6 +338,49 @@ export function isSecurityInitFailed() {
   return securityInitFailed;
 }
 
+/**
+ * Build the agent-facing additionalContext block surfacing the security
+ * init failure (#558).
+ *
+ * Pre-558 the only signal of a fail-open security regression was a
+ * stderr WARNING line that adapters typically suppress / discard. The
+ * user had no in-band signal that `permissions.deny` was no-op'd.
+ *
+ * Returns a structured XML-ish block when initSecurity() has failed,
+ * `null` otherwise. SessionStart hooks append the block to their
+ * additionalContext so the agent (and through the agent, the user)
+ * sees the warning the next time they view the session — not just in
+ * suppressed stderr.
+ *
+ * The block format intentionally mirrors the `<context_guidance>`
+ * shape used elsewhere in routing so existing prompt-template
+ * scaffolding picks it up without special-casing.
+ */
+export function buildSecurityWarningContext() {
+  if (!securityInitFailed) return null;
+  return [
+    "<context_mode_security_warning>",
+    "  <severity>HIGH</severity>",
+    "  <issue>",
+    "    The context-mode security module failed to load.",
+    "    User-configured `permissions.deny` patterns are NOT being enforced.",
+    "    Bash commands and file operations bypass the deny gate (fail-open).",
+    "  </issue>",
+    "  <root_cause>",
+    "    `hooks/security.bundle.mjs` (and `build/security.js`) are absent or unloadable.",
+    "    Common on marketplace installs where `build/` is gitignored and the",
+    "    bundle was missing prior to v1.0.127.",
+    "  </root_cause>",
+    "  <fix>",
+    "    Run `npm run bundle` from the context-mode source checkout, OR",
+    "    upgrade context-mode to v1.0.127+ (which ships hooks/security.bundle.mjs",
+    "    via CI). To opt in to fail-CLOSED instead, set CONTEXT_MODE_REQUIRE_SECURITY=1.",
+    "    To silence this warning while you investigate, set CONTEXT_MODE_SUPPRESS_SECURITY_WARNING=1.",
+    "  </fix>",
+    "</context_mode_security_warning>",
+  ].join("\n");
+}
+
 /**
  * Normalize platform-specific tool names to canonical (Claude Code) names.
  *

package/hooks/gemini-cli/sessionstart.mjs

@@ -25,7 +25,7 @@ import { createSessionLoaders } from "../session-loaders.mjs";
 import { join, dirname } from "node:path";
 import { readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 
 const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
 const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
@@ -88,11 +88,13 @@ try {
     const sessionId = getSessionId(input, OPTS);
     db.ensureSession(sessionId, projectDir);
 
-    // Auto-write GEMINI.md on startup if missing or not merged yet
-    try {
-      const { GeminiCLIAdapter } = await import(pathToFileURL(join(HOOK_DIR, "..", "..", "build", "adapters", "gemini-cli", "index.js")).href);
-      new GeminiCLIAdapter().writeRoutingInstructions(projectDir, join(HOOK_DIR, "..", ".."));
-    } catch { /* best effort — don't block session start */ }
+    // NOTE (#558): excised the old GEMINI.md auto-write block. It loaded an
+    // adapter from build/ (gitignored, missing on marketplace installs) and
+    // called a method that was deleted from every adapter in commit 6dae20c.
+    // Both layers were silently no-op'd by the surrounding try/catch on every
+    // install path for many releases. If routing-instruction auto-write is
+    // reintroduced it must come with its own PRD, method spec, and format
+    // tests — out of scope for the security regression fix.
 
     const ruleFilePaths = [
       join(homedir(), ".gemini", "GEMINI.md"),

package/hooks/security.bundle.mjs

@@ -0,0 +1 @@
+import{readFileSync as S,realpathSync as R}from"node:fs";import{resolve as u}from"node:path";import{resolve as a}from"node:path";import{homedir as d}from"node:os";import{createRequire as C}from"node:module";function v(e=process.env){let s=e.CLAUDE_CONFIG_DIR;return s&&s.trim()!==""?s.startsWith("~")?a(d(),s.replace(/^~[/\\]?/,"")):a(s):a(d(),".claude")}function E(e=process.env){return a(v(e),"settings.json")}function h(e=process.env){let s=[],t=null,n=null;try{let r=C(import.meta.url)("../adapters/detect.js");t=r.detectPlatform(),n=r.getSessionDirSegments}catch{}if(t&&n&&t.platform!=="claude-code"){let o=n(t.platform);o&&o.length>0&&s.push(a(d(),...o,"settings.json"))}let i=E(e);return s.includes(i)||s.push(i),s}function w(e){let s=e.match(/^Bash\((.+)\)$/);return s?s[1]:null}function k(e){let s=e.match(/^(\w+)\((.+)\)$/);return s?{tool:s[1],glob:s[2]}:null}function $(e){return e.replace(/[.*+?^${}()|[\]\\\/\-]/g,"\\$&")}function P(e){return e.replace(/[.+?^${}()|[\]\\\/\-]/g,"\\$&").replace(/\*/g,".*")}function A(e,s=!1){let t,n=e.indexOf(":");if(n!==-1){let i=e.slice(0,n),o=e.slice(n+1),r=$(i),l=P(o);t=`^${r}(\\s${l})?$`}else t=`^${P(e)}$`;return new RegExp(t,s?"i":"")}function G(e,s=!1){let t="",n=0;for(;n<e.length;)e[n]==="*"&&e[n+1]==="*"?n+2<e.length&&e[n+2]==="/"?(t+="(.*/)?",n+=3):(t+=".*",n+=2):e[n]==="*"?(t+="[^/]*",n++):e[n]==="?"?(t+="[^/]",n++):(t+=e[n].replace(/[.+^${}()|[\]\\\/\-]/g,"\\$&"),n++);return new RegExp(`^${t}$`,s?"i":"")}function f(e,s,t=!1){for(let n of s){let i=w(n);if(i&&A(i,t).test(e))return n}return null}function b(e){let s=[],t="",n=!1,i=!1,o=!1;for(let r=0;r<e.length;r++){let l=e[r],c=r>0?e[r-1]:"";l==="'"&&!i&&!o&&c!=="\\"?(n=!n,t+=l):l==='"'&&!n&&!o&&c!=="\\"?(i=!i,t+=l):l==="`"&&!n&&!i&&c!=="\\"?(o=!o,t+=l):!n&&!i&&!o?l===";"?(s.push(t.trim()),t=""):l==="|"&&e[r+1]==="|"||l==="&"&&e[r+1]==="&"?(s.push(t.trim()),t="",r++):l==="|"?(s.push(t.trim()),t=""):t+=l:t+=l}return t.trim()&&s.push(t.trim()),s.filter(r=>r.length>0)}function m(e){let s;try{s=S(e,"utf-8")}catch{return null}let t;try{t=JSON.parse(s)}catch{return null}let n=t?.permissions;if(!n||typeof n!="object")return null;let i=o=>Array.isArray(o)?o.filter(r=>typeof r=="string"&&w(r)!==null):[];return{allow:i(n.allow),deny:i(n.deny),ask:i(n.ask)}}function L(e,s){let t=[];if(e){let i=u(e,".claude","settings.local.json"),o=m(i);o&&t.push(o);let r=u(e,".claude","settings.json"),l=m(r);l&&t.push(l)}let n=s!==void 0?[s]:h();for(let i of n){let o=m(i);o&&t.push(o)}return t}function M(e,s,t){let n=[],i=r=>{let l;try{l=S(r,"utf-8")}catch{return null}let c;try{c=JSON.parse(l)}catch{return null}let g=c?.permissions?.deny;if(!Array.isArray(g))return[];let y=[];for(let x of g){if(typeof x!="string")continue;let p=k(x);p&&p.tool===e&&y.push(p.glob)}return y};if(s){let r=i(u(s,".claude","settings.local.json"));r!==null&&n.push(r);let l=i(u(s,".claude","settings.json"));l!==null&&n.push(l)}let o=t!==void 0?[t]:h();for(let r of o){let l=i(r);l!==null&&n.push(l)}return n}function q(e,s,t=process.platform==="win32"){let n=b(e);for(let i of n)for(let o of s){let r=f(i,o.deny,t);if(r)return{decision:"deny",matchedPattern:r}}for(let i of s){let o=f(e,i.ask,t);if(o)return{decision:"ask",matchedPattern:o};let r=f(e,i.allow,t);if(r)return{decision:"allow",matchedPattern:r}}return{decision:"ask"}}function z(e,s,t=process.platform==="win32"){let n=b(e);for(let i of n)for(let o of s){let r=f(i,o.deny,t);if(r)return{decision:"deny",matchedPattern:r}}return{decision:"allow"}}function I(e,s,t=process.platform==="win32",n){let i=r=>r.replace(/\\/g,"/"),o=new Set;if(o.add(i(e)),n){let r=u(n,e);o.add(i(r));try{o.add(i(R(r)))}catch{}}for(let r of s)for(let l of r){let c=G(i(l),t);for(let g of o)if(c.test(g))return{denied:!0,matchedPattern:l}}return{denied:!1}}var _={python:[/os\.system\(\s*(['"])(.*?)\1\s*\)/g,/subprocess\.(?:run|call|Popen|check_output|check_call)\(\s*(['"])(.*?)\1/g],javascript:[/exec(?:Sync|File|FileSync)?\(\s*(['"`])(.*?)\1/g,/spawn(?:Sync)?\(\s*(['"`])(.*?)\1/g],typescript:[/exec(?:Sync|File|FileSync)?\(\s*(['"`])(.*?)\1/g,/spawn(?:Sync)?\(\s*(['"`])(.*?)\1/g],ruby:[/system\(\s*(['"])(.*?)\1/g,/`(.*?)`/g],go:[/exec\.Command\(\s*(['"`])(.*?)\1/g],php:[/shell_exec\(\s*(['"`])(.*?)\1/g,/(?:^|[^.])exec\(\s*(['"`])(.*?)\1/g,/(?:^|[^.])system\(\s*(['"`])(.*?)\1/g,/passthru\(\s*(['"`])(.*?)\1/g,/proc_open\(\s*(['"`])(.*?)\1/g],rust:[/Command::new\(\s*(['"`])(.*?)\1/g]};function F(e){let s=[],t=/subprocess\.(?:run|call|Popen|check_output|check_call)\(\s*\[([^\]]+)\]/g,n;for(;(n=t.exec(e))!==null;){let o=[...n[1].matchAll(/(['"])(.*?)\1/g)].map(r=>r[2]);o.length>0&&s.push(o.join(" "))}return s}function H(e,s){let t=_[s];if(!t&&s!=="python")return[];let n=[];if(t)for(let i of t){i.lastIndex=0;let o;for(;(o=i.exec(e))!==null;){let r=o[o.length-1];r&&n.push(r)}}return s==="python"&&n.push(...F(e)),n}export{q as evaluateCommand,z as evaluateCommandDenyOnly,I as evaluateFilePath,H as extractShellCommands,G as fileGlobToRegex,A as globToRegex,f as matchesAnyPattern,w as parseBashPattern,k as parseToolPattern,L as readBashPolicies,M as readToolDenyPatterns,b as splitChainedCommands};

package/hooks/sessionstart.mjs

@@ -53,6 +53,24 @@ await runHook(async () => {
 
   let additionalContext = ROUTING_BLOCK;
 
+  // ─── #558: surface security init failure as agent-facing context ───
+  //
+  // Pre-558 the only signal of a fail-open security regression was a
+  // stderr WARNING line (suppressed/discarded by most adapters). The
+  // SessionStart additionalContext block is the in-band channel — the
+  // agent reads it, the user sees it. Idempotent by virtue of
+  // SessionStart's once-per-session lifecycle.
+  try {
+    const { initSecurity, isSecurityInitFailed, buildSecurityWarningContext } =
+      await import("./core/routing.mjs");
+    const { resolve: _resolve } = await import("node:path");
+    await initSecurity(_resolve(HOOK_DIR, "..", "build"));
+    if (isSecurityInitFailed()) {
+      const warning = buildSecurityWarningContext();
+      if (warning) additionalContext = warning + "\n\n" + additionalContext;
+    }
+  } catch { /* security probe is best-effort — never block session start */ }
+
   try {
     const raw = await readStdin();
     const input = parseStdin(raw);

package/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.125",
+  "version": "1.0.127",
   "type": "module",
   "description": "MCP plugin that saves 98% of your context window. Works with Claude Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI. Sandboxed code execution, FTS5 knowledge base, and intent-driven search.",
   "author": "Mert Koseoğlu",
@@ -79,14 +79,15 @@
     "scripts/postinstall.mjs",
     "scripts/heal-better-sqlite3.mjs",
     "scripts/heal-installed-plugins.mjs",
+    "scripts/plugin-cache-integrity.mjs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc && node -e \"if(process.platform!=='win32'){require('fs').chmodSync('build/cli.js',0o755)}\" && npm run bundle && npm run assert-bundle && npm run assert-asymmetric-drift",
-    "assert-bundle": "node scripts/assert-bundle.mjs server.bundle.mjs cli.bundle.mjs hooks/session-extract.bundle.mjs hooks/session-snapshot.bundle.mjs hooks/session-db.bundle.mjs",
+    "assert-bundle": "node scripts/assert-bundle.mjs server.bundle.mjs cli.bundle.mjs hooks/session-extract.bundle.mjs hooks/session-snapshot.bundle.mjs hooks/session-db.bundle.mjs hooks/security.bundle.mjs",
     "assert-asymmetric-drift": "node scripts/assert-asymmetric-drift.mjs",
-    "bundle": "esbuild src/server.ts --bundle --platform=node --target=node18 --format=esm --outfile=server.bundle.mjs --external:better-sqlite3 --external:turndown --external:turndown-plugin-gfm --external:@mixmark-io/domino --minify && esbuild src/cli.ts --bundle --platform=node --target=node18 --format=esm --outfile=cli.bundle.mjs --external:better-sqlite3 --minify && esbuild src/session/extract.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/session-extract.bundle.mjs --minify && esbuild src/session/snapshot.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/session-snapshot.bundle.mjs --minify && esbuild src/session/db.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/session-db.bundle.mjs --external:better-sqlite3 --minify",
+    "bundle": "esbuild src/server.ts --bundle --platform=node --target=node18 --format=esm --outfile=server.bundle.mjs --external:better-sqlite3 --external:turndown --external:turndown-plugin-gfm --external:@mixmark-io/domino --minify && esbuild src/cli.ts --bundle --platform=node --target=node18 --format=esm --outfile=cli.bundle.mjs --external:better-sqlite3 --minify && esbuild src/session/extract.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/session-extract.bundle.mjs --minify && esbuild src/session/snapshot.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/session-snapshot.bundle.mjs --minify && esbuild src/session/db.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/session-db.bundle.mjs --external:better-sqlite3 --minify && esbuild src/security.ts --bundle --platform=node --target=node18 --format=esm --outfile=hooks/security.bundle.mjs --minify",
     "version-sync": "node scripts/version-sync.mjs",
     "version": "node scripts/version-sync.mjs && git add package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json .cursor-plugin/plugin.json .codex-plugin/plugin.json .openclaw-plugin/openclaw.plugin.json .openclaw-plugin/package.json openclaw.plugin.json .pi/extensions/context-mode/package.json",
     "prepublishOnly": "npm run build",

package/scripts/plugin-cache-integrity.mjs

@@ -0,0 +1,248 @@
+/**
+ * Plugin cache integrity check (Algo-D4 + Algo-D5).
+ *
+ * Algorithmic defense against #550: a partial install (interrupted npm
+ * install, broken marketplace pull, half-finished /ctx-upgrade) leaves
+ * start.mjs spawnable but a critical sibling (server.bundle.mjs,
+ * cli.bundle.mjs, hooks/<event>.mjs, …) missing. The MCP child then
+ * dies silently downstream and the user sees an opaque "MCP server
+ * failed to start" with no actionable signal.
+ *
+ * The expected sibling tree is DERIVED from `package.json files[]` —
+ * the npm publish source of truth. Adding a new entry there auto-
+ * extends the integrity check; no parallel hardcoded list to maintain
+ * (the trap that bites every project that hand-rolls "list of files
+ * that must exist at runtime").
+ *
+ * Two consumers:
+ *   1. start.mjs at boot — calls assertPluginCacheIntegrity, on !ok
+ *      writes a structured CONTEXT_MODE_PARTIAL_INSTALL stderr block
+ *      and exits 2. Fail-fast — the alternative is a downstream stack
+ *      trace from `import("./server.bundle.mjs")` that hides the
+ *      actual root cause.
+ *   2. src/cli.ts ctx doctor (Algo-D5) — same helper, same answer,
+ *      surfaced as a HealthCheck so users get the diagnostic without
+ *      restarting the MCP server.
+ *
+ * Pure JS, Node.js built-ins only. Ships in package.json files[] so
+ * users running off the npm tarball get the same code path the
+ * developer ran during `pretest`.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/**
+ * Walk a directory recursively, returning a flat list of relative file
+ * paths (using `/` as separator inside the returned strings). Skips
+ * unreadable entries silently — the integrity check operates on what
+ * IS readable; missing entries are reported by the caller.
+ */
+function listFilesRecursive(absDir, baseAbs) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(absDir);
+  } catch {
+    return out; // unreadable — caller will report the parent as missing
+  }
+  for (const name of entries) {
+    const full = join(absDir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      out.push(...listFilesRecursive(full, baseAbs));
+    } else {
+      out.push(relative(baseAbs, full));
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the expected sibling tree for a given pluginRoot, derived
+ * from the supplied `package.json files[]` array.
+ *
+ * Algorithm:
+ *   - Each entry in files[] is resolved against pluginRoot.
+ *   - If it points to a directory → list every file inside recursively.
+ *   - If it points to a file → kept as-is.
+ *   - Entries that don't exist at probe-time are EXCLUDED from the
+ *     manifest (they show up as `missing` in the assert step instead).
+ *     This avoids the trap of "manifest contains paths that have never
+ *     existed" — the manifest is a snapshot of WHAT IS, not WHAT WAS
+ *     PUBLISHED.
+ *
+ * Returns relative paths (relative to pluginRoot). Used by both
+ * assertPluginCacheIntegrity and the doctor surface.
+ */
+export function derivePluginManifest({ pkg, pluginRoot }) {
+  if (!pkg || !Array.isArray(pkg.files)) return [];
+  const manifest = new Set();
+  for (const entry of pkg.files) {
+    if (typeof entry !== "string" || !entry) continue;
+    const absEntry = join(pluginRoot, entry);
+    if (!existsSync(absEntry)) continue;
+    let st;
+    try {
+      st = statSync(absEntry);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      for (const f of listFilesRecursive(absEntry, pluginRoot)) manifest.add(f);
+    } else {
+      manifest.add(entry);
+    }
+  }
+  return [...manifest];
+}
+
+/**
+ * LEGACY_FALLBACK — the v1.0.126 hardcoded REQUIRED_RUNTIME_SIBLINGS,
+ * preserved verbatim. Forms the union seed for the algorithmic set so
+ * the post-558 contract is strictly additive over the pre-558 contract
+ * (no required sibling ever silently disappears).
+ *
+ * Also acts as a safety net when `package.json` is unreadable — the
+ * boot gate stays loud even if the publish manifest is corrupted.
+ */
+const LEGACY_FALLBACK = Object.freeze([
+  "server.bundle.mjs",
+  "cli.bundle.mjs",
+  join("hooks", "pretooluse.mjs"),
+  join("hooks", "posttooluse.mjs"),
+  join("hooks", "precompact.mjs"),
+  join("hooks", "sessionstart.mjs"),
+  join("hooks", "userpromptsubmit.mjs"),
+]);
+
+/**
+ * SOFT_FALLBACK_BUNDLES — bundles that already implement
+ * bundle-first / build-fallback resolution (via session-loaders.mjs or
+ * session-helpers.mjs). Their absence on a published install is
+ * gracefully recoverable, so they MUST NOT join the fail-fast boot
+ * gate — the gate would refuse to start a working install.
+ *
+ * The security bundle is intentionally NOT here: its absence creates a
+ * silent fail-OPEN regression (#558), so it IS boot-critical.
+ */
+const SOFT_FALLBACK_BUNDLES = new Set([
+  "hooks/session-extract.bundle.mjs",
+  "hooks/session-snapshot.bundle.mjs",
+  "hooks/session-db.bundle.mjs",
+  "hooks/session-attribution.bundle.mjs",
+]);
+
+/**
+ * Algorithmically extract every esbuild output path from
+ * `package.json scripts.bundle`. The bundle script is the SINGLE
+ * SOURCE OF TRUTH for "what bundles this build produces" — parsing
+ * its `--outfile=…` arguments avoids the parallel-list trap that
+ * bit Algo-D4 v1.0.126 (the hardcoded REQUIRED list lagged the
+ * actual bundle output).
+ *
+ * Returns POSIX-style relative paths (forward slashes) for stable
+ * comparison with SOFT_FALLBACK_BUNDLES. Caller normalizes to
+ * `path.join` shape before pluginRoot-relative resolution.
+ */
+function extractBundleOutfiles(pkg) {
+  const script = pkg?.scripts?.bundle;
+  if (typeof script !== "string") return [];
+  const out = new Set();
+  // Match every `--outfile=<path>` token (path is whitespace-delimited
+  // because the script chains commands with `&&`).
+  const re = /--outfile=(\S+)/g;
+  let m;
+  while ((m = re.exec(script)) !== null) {
+    out.add(m[1]);
+  }
+  return [...out];
+}
+
+/**
+ * Algorithmic — derive the boot-critical sibling set as the union of:
+ *   1. LEGACY_FALLBACK (the v1.0.126 contract, preserved verbatim).
+ *   2. Every esbuild output path from `package.json scripts.bundle`
+ *      that is NOT in SOFT_FALLBACK_BUNDLES.
+ *
+ * Why algorithmic instead of hardcoded:
+ *
+ *   v1.0.126 shipped Algo-D4 with a hardcoded REQUIRED_RUNTIME_SIBLINGS
+ *   array that omitted `hooks/security.bundle.mjs` (the bundle didn't
+ *   ship until v1.0.127). The hardcoded list would need manual
+ *   extension every time a runtime bundle is added — the same trap
+ *   would re-bite the next bundle. Deriving from `scripts.bundle`
+ *   closes the trap: any new bundle output is auto-gated unless it
+ *   joins the soft-fallback whitelist (which is itself an explicit
+ *   architectural decision, not a maintenance burden). (#558)
+ *
+ * Returns OS-native-separator relative paths (suitable for
+ * `path.join(pluginRoot, …)`).
+ *
+ * If `package.json` is unreadable, returns LEGACY_FALLBACK as a
+ * safety net so the boot gate never goes silent due to a parse
+ * error in the publish manifest.
+ */
+export function getRequiredRuntimeSiblings(pluginRoot) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf-8"));
+  } catch {
+    return [...LEGACY_FALLBACK];
+  }
+  const required = new Set(LEGACY_FALLBACK);
+  for (const outfile of extractBundleOutfiles(pkg)) {
+    // Normalize to POSIX for soft-fallback membership check —
+    // scripts.bundle is hand-authored with forward slashes already,
+    // but be defensive in case a Windows-authored package.json ever
+    // reaches us.
+    const posix = outfile.split(sep).join("/");
+    if (SOFT_FALLBACK_BUNDLES.has(posix)) continue;
+    // Convert back to OS-native sep for downstream filesystem ops.
+    required.add(posix.split("/").join(sep));
+  }
+  return [...required];
+}
+
+/**
+ * Verify boot-critical siblings exist at pluginRoot.
+ *
+ * Returns `{ ok, missing }`. Pure — does NOT touch process.exit or
+ * stderr. The caller (start.mjs at boot, src/cli.ts at doctor) decides
+ * the failure surface (fail-fast exit 2 vs. doctor diagnostic).
+ *
+ * Required-set is computed by `getRequiredRuntimeSiblings()` —
+ * algorithmically derived from `package.json files[]` filtered to the
+ * RUNTIME_CRITICAL_PATTERN. Drift between publish manifest and runtime
+ * contract becomes architecturally impossible (#558).
+ */
+export function assertPluginCacheIntegrity({ pluginRoot }) {
+  const missing = [];
+  for (const rel of getRequiredRuntimeSiblings(pluginRoot)) {
+    const abs = join(pluginRoot, rel);
+    if (!existsSync(abs)) missing.push(abs);
+  }
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Format the structured stderr block start.mjs emits when integrity
+ * fails. Marker line `CONTEXT_MODE_PARTIAL_INSTALL` lets external
+ * monitoring grep for the exact failure mode without parsing free-form
+ * text. Keep the format stable across versions.
+ */
+export function formatPartialInstallReport({ pluginRoot, missing }) {
+  const lines = [
+    "CONTEXT_MODE_PARTIAL_INSTALL",
+    `  pluginRoot: ${pluginRoot}`,
+    "  missing:",
+    ...missing.map((m) => `    - ${m}`),
+    "  fix: rm -rf the install dir and re-pull (marketplace) or run `npm install -g context-mode` again.",
+    "",
+  ];
+  return lines.join("\n");
+}