@compr/opscontext-mcp 2.9.1 → 2.11.0

package/dist/index.js

@@ -2,9 +2,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
+import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findConfigFileWithOrigin } from "./config.js";
 import { ingestSources } from "./ingest.js";
-import { redactSecrets } from "./secret-shapes.js";
+import { redactChunk } from "./secret-shapes.js";
 import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, embedKeyOf, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
@@ -13,8 +13,10 @@ import { loadEmbeddingStore, compactEmbeddingStore } from "./embedding-store.js"
 import { sharedIndexEnabled, corpusId, electIndexer, writeSharedIndex, readSharedIndex, sharedIndexMtime, } from "./shared-index.js";
 import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, runScoreCanary, } from "./agents.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
-import { verifyChain, readAuditLog, filterByRange, autoRotateAuditLog, safeAppend } from "./audit.js";
-import { registerServer, listServers, formatServers } from "./server-registry.js";
+import { verifyChain, readAuditLog, filterByRange, autoRotateAuditLog, safeAppend, readVerifyState } from "./audit.js";
+import { registerServer, listServers, formatServers, liveDaemonPid } from "./server-registry.js";
+import { secureCeHome } from "./ce-home.js";
+import { QUOTED_TEXT_NOTE } from "./framing.js";
 import { computeFleetHealth, writeFleetHealth } from "./fleet-health.js";
 import { startEventIngestServer } from "./http-server.js";
 import { detect } from "./detector.js";
@@ -24,7 +26,8 @@ import { communityRulesToChunks, mergeWithDedup, loadCommunityStore, } from "./c
 import { readFileSync, existsSync, watch, statSync, writeFileSync, mkdirSync } from "fs";
 import { basename, join, dirname } from "path";
 import { homedir } from "os";
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
+import { setPriority } from "os";
 import { scanCodeDir } from "./code-chunker.js";
 import { fileURLToPath } from "url";
 import { TOOL_COUNT, FREE_TOOL_COUNT, PREMIUM_TOOL_NAMES } from "./tools-manifest.js";
@@ -38,7 +41,7 @@ try {
 }
 catch { /* fallback */ }
 import { loadAdapters, collectFromAdapters, } from "./adapters.js";
-import { gateCheck, activate, getActivationStatus, } from "./activation.js";
+import { gateCheckFresh, licenceCheckState, activate, getActivationStatus, } from "./activation.js";
 import { ProtocolFirewall } from "./firewall.js";
 // ---------------------------------------------------------------------------
 // State
@@ -55,6 +58,8 @@ let role = "indexer";
 let corpus;
 let indexerPid = null;
 let setRegistryRole = null;
+let setRegistryEventPort = null;
+let warnedCwdAdapters = false;
 /** key -> vector, loaded from ~/.contextengine/embeddings.bin and grown by what we embed. */
 let vectorStore = new Map();
 let indexSeq = 0;
@@ -133,6 +138,11 @@ async function buildIndex(opts) {
         if (autoImport.refused) {
             console.error(`[ContextEngine] ⛔ Auto-import write refused: ${autoImport.refused}`);
         }
+        // [LOCK] [AUTO-IMPORT-ONLY-FROM-TRUSTED-PROJECTS]: say what was left out, and how to include it.
+        if (autoImport.untrusted.length > 0) {
+            console.error(`[ContextEngine] ⏸ Marked learnings in ${autoImport.untrusted.length} project(s) you have not marked as yours were not imported: ` +
+                `${autoImport.untrusted.join(", ")}. If they are yours: contextengine trust ${autoImport.untrusted.map((p) => JSON.stringify(p)).join(" ")}`);
+        }
     }
     // Inject learnings as searchable chunks (project-scoped to prevent IP leakage)
     const learningChunks = learningsToChunks(activeProjectNames);
@@ -156,9 +166,29 @@ async function buildIndex(opts) {
     // [LOCK] [INDEX-NEVER-SERVES-A-CREDENTIAL]: before the adapters, whose block can return early.
     chunks = chunks.map(redactChunk);
     // Collect from plugin adapters
-    if (config.adapters && config.adapters.length > 0) {
+    // [LOCKED] [ADAPTERS-ONLY-FROM-THE-USERS-OWN-CONFIG] - 2026-09-25
+    // [NEVER] import an adapter module named by a contextengine.json found in the current folder, or
+    //         resolve a relative adapter path from the current folder.
+    // WHY: without CONTEXTENGINE_CONFIG (the README's setup), the server reads ./contextengine.json
+    //      from the folder it starts in, which for Claude Code is the project opened. An adapter entry
+    //      there is import()ed, so a downloaded repository carrying a config and a module ran its own
+    //      code in the user's session when the project was opened; proven in a sandbox on 2026-09-25
+    //      (E2E_REVIEW_2026-09 A6-5). A relative path in the user's own config also resolved from
+    //      that folder, not from the config's.
+    // FIX: adapters load only from the config named by CONTEXTENGINE_CONFIG or ~/.contextengine.json,
+    //      relative paths resolve from that file's folder; a config found in the current folder may
+    //      still list sources, never code.
+    const cfgFile = findConfigFileWithOrigin();
+    if (config.adapters && config.adapters.length > 0 && cfgFile?.origin === "cwd") {
+        if (!warnedCwdAdapters) {
+            warnedCwdAdapters = true;
+            console.error(`[ContextEngine] ⛔ Adapters in ${cfgFile.path} were NOT loaded: a config found in the current folder may not run code. ` +
+                `Point CONTEXTENGINE_CONFIG at it, or move the adapters to ~/.contextengine.json.`);
+        }
+    }
+    else if (config.adapters && config.adapters.length > 0) {
         if (opts.loadAdapters) {
-            const adapterCount = await loadAdapters(config.adapters);
+            const adapterCount = await loadAdapters(config.adapters, cfgFile ? dirname(cfgFile.path) : process.cwd());
             if (adapterCount === 0)
                 return;
         }
@@ -169,22 +199,8 @@ async function buildIndex(opts) {
         }
     }
 }
-/**
- * [LOCKED] [INDEX-NEVER-SERVES-A-CREDENTIAL] - 2026-09-25
- * [NEVER] let a chunk into the index, the shared index file or a search result without passing
- *         its text through redactSecrets().
- * WHY: on 2026-09-25 the shared index held database URLs with their passwords (read from dotenv
- *      files, whose masking skipped the password inside a URL), sshpass and mysql passwords from
- *      runbooks and memory notes, and Google API keys: 55 sources in all. search_context hands
- *      chunks to every AI agent that asks, and the index file rides the weekly backup.
- * FIX: every chunk, whatever collected it (docs, code, ops collectors, learnings, community rules,
- *      adapters), is redacted with the capture shapes (src/secret-shapes.ts) as the index is built.
- *      The source files are not touched: cleaning those is the owner's call, file by file.
- */
-function redactChunk(c) {
-    const r = redactSecrets(c.content);
-    return Object.keys(r.counts).length > 0 ? { ...c, content: r.text } : c;
-}
+// [LOCK] [INDEX-NEVER-SERVES-A-CREDENTIAL]: redactChunk lives in src/secret-shapes.ts, shared with
+// the CLI's index builder.
 /** Load the model once; every caller shares the same promise. */
 function ensureModel() {
     if (!modelInit)
@@ -445,6 +461,42 @@ function evaluateRole(reason) {
 }
 let healthTick = 0;
 let lastStaleCount = -1;
+const SERVER_STARTED_AT = Date.now();
+let lastChainCheckSpawn = 0;
+/**
+ * The indexing server starts the daily full check of the audit chain, in its own process.
+ * [LOCK] [HEALTH-SEES-THE-CHAIN] (src/fleet-health.ts): the check costs 26 s and 3.5 GB on 4.9M
+ * records (measured 2026-09-27), so it never runs in this long-lived process, whose event loop
+ * serves the receiver and the tools. A separate low-priority `audit-verify --scheduled`, at most
+ * one attempt an hour, never in the first 10 minutes after a start, one at a time across processes
+ * (its own lock). CONTEXTENGINE_CHAIN_CHECK=0 turns it off.
+ */
+function maybeScheduleChainCheck() {
+    if (role !== "indexer" || process.env.CONTEXTENGINE_CHAIN_CHECK === "0")
+        return;
+    const now = Date.now();
+    if (now - SERVER_STARTED_AT < 10 * 60_000 || now - lastChainCheckSpawn < 60 * 60_000)
+        return;
+    const state = readVerifyState();
+    if (state && now - Date.parse(state.checkedAt) < 24 * 3_600_000)
+        return;
+    lastChainCheckSpawn = now;
+    try {
+        const cli = join(dirname(fileURLToPath(import.meta.url)), "cli.js");
+        const child = spawn(process.execPath, [cli, "audit-verify", "--scheduled"], { stdio: "ignore", detached: true, env: process.env });
+        if (child.pid) {
+            try {
+                setPriority(child.pid, 10);
+            }
+            catch { /* the check still runs, at normal priority */ }
+        }
+        child.unref();
+        console.error(`[ContextEngine] 🔎 daily audit chain check started (pid ${child.pid ?? "?"})`);
+    }
+    catch (err) {
+        console.error(`[ContextEngine] ⚠ could not start the daily audit chain check: ${err.message}`);
+    }
+}
 /**
  * The indexer writes ~/.contextengine/fleet-health.json once a minute: version drift, reindex
  * rate, today's blocks and refusals, the last verified release. Every surface reads that file.
@@ -460,6 +512,7 @@ function publishHealth() {
         }
         if (role === "indexer")
             writeFleetHealth(h);
+        maybeScheduleChainCheck();
     }
     catch (err) {
         console.error(`[ContextEngine] ⚠ fleet health failed: ${err.message}`);
@@ -577,6 +630,7 @@ server.tool("search_context", "Search across all indexed project knowledge (copi
     const searchMode = isEmbeddingsReady() ? mode : "keyword (embeddings loading)";
     const text = [
         `Search: "${query}" | Mode: ${searchMode} | ${results.length} results`,
+        QUOTED_TEXT_NOTE, // [LOCK] [QUOTED-TEXT-IS-FRAMED-AS-DATA]
         "",
         ...results.map((r, i) => [
             `--- Result ${i + 1} (${r.label}: ${r.score.toFixed(3)}) ---`,
@@ -603,7 +657,8 @@ server.tool("list_sources", "List all knowledge sources indexed by ContextEngine
         const status = exists
             ? `✅ ${count} chunks${embeddedCount > 0 ? ` (${embeddedCount} embedded)` : ""}`
             : "⚠ file not found";
-        const summary = exists ? summarizeSource(s) : "";
+        // A preview quotes the file: redacted like any chunk. [LOCK] [INDEX-NEVER-SERVES-A-CREDENTIAL]
+        const summary = exists ? redactChunk({ content: summarizeSource(s) }).content : "";
         return `${s.name}: ${status}${summary ? `\n  ${summary}` : ""}\n  ${s.path}`;
     });
     const embStatus = isEmbeddingsReady()
@@ -612,6 +667,7 @@ server.tool("list_sources", "List all knowledge sources indexed by ContextEngine
     const text = [
         `ContextEngine v${PKG_VERSION}`,
         `Sources: ${sources.length} | Chunks: ${chunks.length} | Embeddings: ${embStatus}`,
+        QUOTED_TEXT_NOTE, // [LOCK] [QUOTED-TEXT-IS-FRAMED-AS-DATA]
         "",
         ...lines,
     ].join("\n");
@@ -648,8 +704,10 @@ server.tool("read_source", "Read the full content of a specific knowledge source
             isError: true,
         };
     }
-    const content = readFileSync(source.path, "utf-8");
-    return respond("read_source", `# ${source.name}\n\n${content}`, source_name);
+    // [LOCK] [INDEX-NEVER-SERVES-A-CREDENTIAL]: the whole file goes through the same redaction as a
+    // search result; read_source used to return it raw (E2E_REVIEW_2026-09 A6-6).
+    const content = redactChunk({ content: readFileSync(source.path, "utf-8") }).content;
+    return respond("read_source", `# ${source.name}\n${QUOTED_TEXT_NOTE}\n\n${content}`, source_name);
 });
 // ---------------------------------------------------------------------------
 // Tool: reindex
@@ -666,7 +724,7 @@ server.tool("reindex", "Force a full re-index of all knowledge sources. Use afte
 // Tool: list_projects (Multi-Agent Phase 1)
 // ---------------------------------------------------------------------------
 server.tool("list_projects", "Discover and analyze all projects in the workspace. Shows tech stack (framework, runtime, key dependencies), infrastructure (git, docker, pm2), and git remote status for each project. Requires Pro license.", {}, async () => {
-    const gate = gateCheck("list_projects");
+    const gate = await gateCheckFresh("list_projects");
     if (gate)
         return { content: [{ type: "text", text: gate }] };
     const projectDirs = loadProjectDirs();
@@ -678,7 +736,7 @@ server.tool("list_projects", "Discover and analyze all projects in the workspace
 // Tool: check_ports (Multi-Agent Phase 1)
 // ---------------------------------------------------------------------------
 server.tool("check_ports", "Scan all projects for port declarations (ecosystem.config.js, docker-compose.yml, .env, package.json) and detect port conflicts. Returns a port allocation map with conflict warnings. Requires Pro license.", {}, async () => {
-    const gate = gateCheck("check_ports");
+    const gate = await gateCheckFresh("check_ports");
     if (gate)
         return { content: [{ type: "text", text: gate }] };
     const projectDirs = loadProjectDirs();
@@ -695,7 +753,7 @@ server.tool("run_audit", "Run the Compliance Agent audit across all projects. Ch
         .default("all")
         .describe("Audit scope: all checks, compliance only, version checks only, or port conflicts only"),
 }, async ({ scope }) => {
-    const gate = gateCheck("run_audit");
+    const gate = await gateCheckFresh("run_audit");
     if (gate)
         return { content: [{ type: "text", text: gate }] };
     const projectDirs = loadProjectDirs();
@@ -712,7 +770,7 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
         .optional()
         .describe("Project name OR absolute directory path to score. Omit to score all projects."),
 }, async ({ project }) => {
-    const gate = gateCheck("score_project");
+    const gate = await gateCheckFresh("score_project");
     if (gate)
         return { content: [{ type: "text", text: gate }] };
     // 🔒 LOCKED [SCORE-CANARY-COVERS-EVERY-SCORER] — 2026-08-19
@@ -1169,7 +1227,8 @@ server.tool("list_learnings", "List all permanent learnings, optionally filtered
     }
     const learnings = listLearnings(category, activeProjectNames);
     const text = formatLearnings(learnings, { since: sinceDate, sinceSpec: since });
-    return respond("list_learnings", text);
+    // Redacted like every chunk: a learning can quote a command with its password. [LOCK] [INDEX-NEVER-SERVES-A-CREDENTIAL]
+    return respond("list_learnings", redactChunk({ content: text }).content);
 });
 // ---------------------------------------------------------------------------
 // Tool: delete_learning (Permanent Learning Store)
@@ -1265,6 +1324,7 @@ server.tool("activation_status", "Check current ContextEngine license status, pl
         `- **Expires**: ${status.expiresAt}`,
         `- **Delta version**: ${status.deltaVersion}`,
         `- **Machine ID**: ${status.machineId}`,
+        `- **Licence check**: ${licenceCheckState()}`, // [LOCK] [LICENSE-IS-CHECKED-DAILY]
         ``,
     ];
     if (status.premiumTools.length > 0) {
@@ -1319,6 +1379,9 @@ function registerResources() {
 // Start
 // ---------------------------------------------------------------------------
 async function main() {
+    // [LOCK] [CE-HOME-IS-PRIVATE]: the folder is 0700 before the registry, the index or the log write
+    // into it.
+    secureCeHome();
     // 0. Inventory this server FIRST, before indexing takes minutes: a server exists the moment it
     //    starts. [LOCK] [SERVERS-ARE-INVENTORIED]. With the shared index on, the registry is also
     //    the electorate: the record carries the corpus and the role. [LOCK] [ONE-INDEXER-MANY-READERS]
@@ -1331,8 +1394,9 @@ async function main() {
         }
     }
     try {
-        const reg = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url), corpus, role: corpus ? "reader" : undefined });
+        const reg = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url), corpus, role: corpus ? "reader" : undefined, daemon: process.env.OPSCONTEXT_DAEMON === "1" });
         setRegistryRole = reg.setRole;
+        setRegistryEventPort = reg.setEventPort;
         const fleet = listServers();
         if (corpus) {
             const e = electIndexer(corpus, fleet.servers, process.pid);
@@ -1397,7 +1461,7 @@ async function main() {
     const runAutoRotate = () => {
         try {
             const o = autoRotateAuditLog();
-            if (o.action === "rotated" || o.action === "refused" || o.action === "error" || o.action === "in_progress") {
+            if (o.action === "rotated" || o.action === "refused" || o.action === "error" || o.action === "in_progress" || o.action === "finished") {
                 console.error(`[ContextEngine] 📦 audit auto-rotate (${o.action}): ${o.detail}`);
             }
         }
@@ -1466,7 +1530,13 @@ async function main() {
     // No-op if secret is missing; the endpoint will refuse with 401 until
     // a secret is configured. Failure to bind (port collision) logs and
     // continues — the MCP server stays usable without browser capture.
-    startEventIngestServer().catch((err) => {
+    // [LOCK] [EVENT-PORT-BELONGS-TO-THE-DAEMON]: the launchd agent keeps trying until it holds the
+    // port; a chat server takes it only while no agent is alive, and hands it over when one is.
+    startEventIngestServer({
+        daemon: process.env.OPSCONTEXT_DAEMON === "1",
+        onPortChange: (port) => setRegistryEventPort?.(port),
+        liveDaemon: () => liveDaemonPid(),
+    }).catch((err) => {
         console.error("[ContextEngine] event-ingest start failed:", err);
     });
 }

package/dist/install-autostart.js

@@ -17,7 +17,7 @@
 import { existsSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 import { homedir, platform } from "os";
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
 // 🔒 LOCKED [M2-ESM-FILENAME-FIX] — 2026-06-24
@@ -52,7 +52,7 @@ function detectNodePath() {
 function detectOpscontextEntry() {
     // (1) Try global install via `npm root -g`
     try {
-        const globalRoot = execSync("npm root -g 2>/dev/null", { encoding: "utf-8" }).trim();
+        const globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
         const candidate = join(globalRoot, "@compr", "opscontext-mcp", "dist", "index.js");
         if (existsSync(candidate))
             return { kind: "global", path: candidate };
@@ -99,6 +99,17 @@ function detectOpscontextEntry() {
 // FIX: Standard priority; the shared-index flag; CONTEXTENGINE_CONFIG passed through from the
 //      installing shell so its corpus id equals the chats'; the memory skip only if the installer
 //      was itself run with it (an explicit choice, not a default).
+// [LOCKED] [AUTOSTART-ARGV-AND-XML-ESCAPED] - 2026-09-25
+// [NEVER] paste a path into a launchctl/lsof/curl command string, or into the plist unescaped.
+// WHY: with a home folder named "John Smith", `launchctl bootstrap gui/501 ${PLIST_FILE}` handed
+//      launchctl the path in two pieces and failed, after `bootout` had already stopped the running
+//      agent; a home named "R&D home" produced a plist launchd refuses ("unknown ampersand-escape
+//      sequence"); only the passthrough env values were escaped (E2E_REVIEW_2026-09 A3-2, A3-3).
+// FIX: execFileSync with an argument list for every command; xml() on every value in the plist;
+//      `plutil -lint` on the written file before anything running is stopped.
+function xml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+}
 export function buildPlist(nodePath, entryPath, nodeBinDir, env = process.env) {
     // OPSCONTEXT_DAEMON tells the server it has no MCP client on stdin and must stay alive on its
     // own: as a reader it holds no file watchers, and every poller is unref'd, so without this the
@@ -110,7 +121,8 @@ export function buildPlist(nodePath, entryPath, nodeBinDir, env = process.env) {
         passthrough.push(["CONTEXTENGINE_WORKSPACES", env.CONTEXTENGINE_WORKSPACES]);
     if (env.OPSCONTEXT_SKIP_CLAUDE_MEMORY === "1")
         passthrough.push(["OPSCONTEXT_SKIP_CLAUDE_MEMORY", "1"]);
-    const extraEnv = passthrough.map(([k, v]) => `        <key>${k}</key>\n        <string>${v.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</string>`).join("\n");
+    // [LOCK] [AUTOSTART-ARGV-AND-XML-ESCAPED]: every value, not only the passthrough ones.
+    const extraEnv = passthrough.map(([k, v]) => `        <key>${k}</key>\n        <string>${xml(v)}</string>`).join("\n");
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -120,21 +132,21 @@ export function buildPlist(nodePath, entryPath, nodeBinDir, env = process.env) {
 
     <key>ProgramArguments</key>
     <array>
-        <string>${nodePath}</string>
-        <string>${entryPath}</string>
+        <string>${xml(nodePath)}</string>
+        <string>${xml(entryPath)}</string>
     </array>
 
     <key>EnvironmentVariables</key>
     <dict>
         <key>PATH</key>
-        <string>${nodeBinDir}:/usr/local/bin:/usr/bin:/bin</string>
+        <string>${xml(nodeBinDir)}:/usr/local/bin:/usr/bin:/bin</string>
         <key>HOME</key>
-        <string>${homedir()}</string>
+        <string>${xml(homedir())}</string>
 ${extraEnv}
     </dict>
 
     <key>WorkingDirectory</key>
-    <string>${homedir()}</string>
+    <string>${xml(homedir())}</string>
 
     <key>RunAtLoad</key>
     <true/>
@@ -146,10 +158,10 @@ ${extraEnv}
     <integer>10</integer>
 
     <key>StandardOutPath</key>
-    <string>${join(LOG_DIR, "mcp-stdout.log")}</string>
+    <string>${xml(join(LOG_DIR, "mcp-stdout.log"))}</string>
 
     <key>StandardErrorPath</key>
-    <string>${join(LOG_DIR, "mcp-stderr.log")}</string>
+    <string>${xml(join(LOG_DIR, "mcp-stderr.log"))}</string>
 
     <key>ProcessType</key>
     <string>Standard</string>
@@ -165,7 +177,7 @@ function userId() {
 }
 function portIsOurs() {
     try {
-        execSync(`lsof -nP -iTCP:${PORT} -sTCP:LISTEN >/dev/null 2>&1`, { stdio: "ignore" });
+        execFileSync("lsof", ["-nP", `-iTCP:${PORT}`, "-sTCP:LISTEN"], { stdio: "ignore" });
         return true;
     }
     catch {
@@ -177,7 +189,7 @@ function waitForPort(timeoutSec = 30) {
     while (Date.now() - start < timeoutSec * 1000) {
         if (portIsOurs())
             return true;
-        execSync("sleep 1");
+        execFileSync("sleep", ["1"]);
     }
     return false;
 }
@@ -263,16 +275,25 @@ To view server logs:        tail -f ~/.contextengine/logs/mcp-stderr.log
     if (portIsOurs()) {
         console.log(`   detected existing process on :${PORT} — relying on launchctl bootout to clean it.`);
     }
+    // [LOCK] [AUTOSTART-ARGV-AND-XML-ESCAPED]: a file launchd would refuse must never cost the user
+    // the agent that is running now, so check it before the bootout.
+    try {
+        execFileSync("plutil", ["-lint", PLIST_FILE], { stdio: ["ignore", "ignore", "pipe"] });
+    }
+    catch (err) {
+        console.error(`❌ The new plist is not valid, nothing was stopped or loaded: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
     // Idempotent bootstrap: bootout (ignore failure) → bootstrap
     const uid = userId();
     try {
-        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+        execFileSync("launchctl", ["bootout", `gui/${uid}/${LABEL}`], { stdio: "ignore" });
     }
     catch {
         /* not loaded — fine */
     }
     try {
-        execSync(`launchctl bootstrap gui/${uid} ${PLIST_FILE}`, { stdio: "inherit" });
+        execFileSync("launchctl", ["bootstrap", `gui/${uid}`, PLIST_FILE], { stdio: "inherit" });
     }
     catch (err) {
         console.error(`❌ launchctl bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -309,7 +330,7 @@ You can re-install with: opscontext install-autostart`);
     const uid = userId();
     let removed = false;
     try {
-        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+        execFileSync("launchctl", ["bootout", `gui/${uid}/${LABEL}`], { stdio: "ignore" });
         removed = true;
     }
     catch {
@@ -350,7 +371,7 @@ running entrypoint.`);
     const uid = userId();
     let launchctlState = "not loaded";
     try {
-        const out = execSync(`launchctl print gui/${uid}/${LABEL} 2>/dev/null || true`, { encoding: "utf-8" });
+        const out = execFileSync("launchctl", ["print", `gui/${uid}/${LABEL}`], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
         const match = out.match(/state\s*=\s*(\S+)/);
         if (match)
             launchctlState = match[1];
@@ -365,7 +386,7 @@ running entrypoint.`);
     console.log(`  port ${PORT}:   ${portUp ? "✅ listening" : "❌ not listening"}`);
     if (portUp) {
         try {
-            const health = execSync(`curl -sf http://127.0.0.1:${PORT}/health`, { encoding: "utf-8", timeout: 2000 });
+            const health = execFileSync("curl", ["-sf", `http://127.0.0.1:${PORT}/health`], { encoding: "utf-8", timeout: 2000 });
             console.log(`  health:      ${health.trim()}`);
         }
         catch {

package/dist/install-claude-hook.d.ts

@@ -13,6 +13,7 @@ export interface Settings {
 }
 /** The script path of a hook command, with $HOME, ${HOME} or a leading ~ expanded. */
 export declare function hookScriptPath(command: string, home?: string): string;
+export declare function shellQuote(value: string): string;
 /** Removes repeated registrations of our scripts under the same matcher. Keeps the first copy
  *  and every hook that is not ours; drops an entry only when that leaves it empty. */
 export declare function dropDuplicateHooks(entries: HookEntry[], ourScripts: string[], home?: string): {