@gamaze/hicortex 0.19.6 → 0.20.1

package/dist/init.js

@@ -7,7 +7,9 @@
  *   2. Remote HC server (HICORTEX_SERVER_URL — any reachable host:port)
  *   3. OC plugin installed (~/.openclaw/openclaw.json)
  *   4. CC MCP already registered (~/.claude/settings.json)
- *   5. Existing DB (~/.hicortex/ or ~/.openclaw/data/)
+ *   5. Hermes present (~/.hermes) / Pi present (~/.pi/agent) /
+ *      opencode present (~/.config/opencode or ~/.local/share/opencode)
+ *   6. Existing DB (~/.hicortex/ or ~/.openclaw/data/)
  *
  * Actions:
  *   - Install persistent daemon (launchd/systemd)
@@ -19,6 +21,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERIC_DEFAULT_DOMAINS = void 0;
 exports.parseMcpListStatus = parseMcpListStatus;
+exports.readPreviousServerUrl = readPreviousServerUrl;
+exports.setupHermes = setupHermes;
 exports.parseEnvFile = parseEnvFile;
 exports.isLlmConfigured = isLlmConfigured;
 exports.persistLlmConfig = persistLlmConfig;
@@ -80,6 +84,11 @@ const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
 const HERMES_HOME = process.env.HERMES_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), ".hermes");
+/** Pi's agent dir — its presence means Pi is installed and will load extensions. */
+const PI_AGENT_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent");
+/** opencode's config/data dirs — either present means opencode is installed. */
+const OPENCODE_CONFIG_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "opencode");
+const OPENCODE_DATA_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".local", "share", "opencode");
 const DEFAULT_PORT = 8787;
 async function detect() {
     const result = {
@@ -88,6 +97,8 @@ async function detect() {
         ocPlugin: false,
         ccMcpRegistered: false,
         hermesFound: false,
+        piFound: false,
+        opencodeFound: false,
         existingDb: false,
     };
     // Check local server. /health/detail carries the diagnostics (memories,
@@ -127,6 +138,11 @@ async function detect() {
     }
     // Check Hermes
     result.hermesFound = (0, node_fs_1.existsSync)(HERMES_HOME);
+    // Check Pi (~/.pi/agent — the dir Pi loads extensions from)
+    result.piFound = (0, node_fs_1.existsSync)(PI_AGENT_DIR);
+    // Check opencode (~/.config/opencode or ~/.local/share/opencode — its
+    // global plugins dir / session store; it auto-loads ~/.config/opencode/plugins/)
+    result.opencodeFound = (0, node_fs_1.existsSync)(OPENCODE_CONFIG_DIR) || (0, node_fs_1.existsSync)(OPENCODE_DATA_DIR);
     // Check OC plugin
     try {
         const raw = (0, node_fs_1.readFileSync)(OC_CONFIG, "utf-8");
@@ -331,9 +347,75 @@ function cleanupLegacyCcCommands() {
     }
 }
 // ---------------------------------------------------------------------------
+// Pi setup
+// ---------------------------------------------------------------------------
+/**
+ * Install the bundled Pi extension (#348): one dependency-free .ts file Pi
+ * loads from ~/.pi/agent/extensions/. Deliberately NO config write — the
+ * extension self-resolves the server from ~/.hicortex/config.json (the file
+ * init has already written by this point), so there is nothing to keep in
+ * sync and no secret to route elsewhere. Overwrites on re-init so upgrades
+ * land; skips gracefully when the bundled source is absent (e.g. a dev
+ * checkout without the packaged copy).
+ */
+function setupPi() {
+    const extensionSource = (0, node_path_1.join)(__dirname, "..", "pi-extension", "hicortex", "index.ts");
+    if (!(0, node_fs_1.existsSync)(extensionSource)) {
+        console.log("  ⚠ Pi extension not found in package — skipping Pi setup");
+        return;
+    }
+    const extensionsDir = (0, node_path_1.join)(PI_AGENT_DIR, "extensions");
+    (0, node_fs_1.mkdirSync)(extensionsDir, { recursive: true });
+    const target = (0, node_path_1.join)(extensionsDir, "hicortex.ts");
+    (0, node_fs_1.copyFileSync)(extensionSource, target);
+    console.log(`  ✓ Copied Pi extension to ${target}`);
+    console.log("  → Restart Pi sessions to load the extension (recall, identity, lessons, 9 tools)");
+}
+// ---------------------------------------------------------------------------
+// opencode setup
+// ---------------------------------------------------------------------------
+/**
+ * Install the bundled opencode plugin (#347): one dependency-free .ts file
+ * opencode auto-loads from ~/.config/opencode/plugins/. Deliberately NO
+ * write into opencode's own configuration — the plugin self-resolves the
+ * server from ~/.hicortex/config.json (the file init has already written by
+ * this point), so there is nothing to keep in sync and no secret to route
+ * elsewhere. Overwrites on re-init so upgrades land; skips gracefully when
+ * the bundled source is absent (e.g. a dev checkout without the packaged
+ * copy). The plugins directory may hold third-party files — the copy only
+ * ever touches our own hicortex.ts name.
+ */
+function setupOpencode() {
+    const pluginSource = (0, node_path_1.join)(__dirname, "..", "opencode-plugin", "hicortex", "index.ts");
+    if (!(0, node_fs_1.existsSync)(pluginSource)) {
+        console.log("  ⚠ opencode plugin not found in package — skipping opencode setup");
+        return;
+    }
+    const pluginsDir = (0, node_path_1.join)(OPENCODE_CONFIG_DIR, "plugins");
+    (0, node_fs_1.mkdirSync)(pluginsDir, { recursive: true });
+    const target = (0, node_path_1.join)(pluginsDir, "hicortex.ts");
+    (0, node_fs_1.copyFileSync)(pluginSource, target);
+    console.log(`  ✓ Copied opencode plugin to ${target}`);
+    console.log("  → Restart opencode sessions to load the plugin (recall, identity, lessons, 9 tools)");
+}
+// ---------------------------------------------------------------------------
 // Hermes setup
 // ---------------------------------------------------------------------------
-function setupHermes(serverUrl, authToken) {
+/**
+ * The client config's serverUrl BEFORE this run re-points it — the value init
+ * last wrote into the Hermes plugin's config (so the plugin step can tell an
+ * init-owned URL from a user-set one). Exported for tests.
+ */
+function readPreviousServerUrl(configPath) {
+    try {
+        const { config: prev } = loadConfigStrict(configPath);
+        if (typeof prev.serverUrl === "string" && prev.serverUrl)
+            return prev.serverUrl;
+    }
+    catch { /* no prior config, or unreadable — nothing init-owned to carry */ }
+    return undefined;
+}
+function setupHermes(serverUrl, authToken, previousServerUrl) {
     const pluginSource = (0, node_path_1.join)(__dirname, "..", "hermes-plugin", "hicortex");
     if (!(0, node_fs_1.existsSync)(pluginSource)) {
         console.log("  ⚠ Hermes plugin not found in package — skipping Hermes setup");
@@ -341,23 +423,86 @@ function setupHermes(serverUrl, authToken) {
     }
     const pluginsDir = (0, node_path_1.join)(HERMES_HOME, "plugins", "hicortex");
     (0, node_fs_1.mkdirSync)(pluginsDir, { recursive: true });
-    // Copy plugin files
-    const pluginFiles = (0, node_fs_1.readdirSync)(pluginSource);
-    for (const f of pluginFiles) {
-        const src = (0, node_path_1.join)(pluginSource, f);
-        if ((0, node_fs_1.statSync)(src).isFile()) {
-            (0, node_fs_1.copyFileSync)(src, (0, node_path_1.join)(pluginsDir, f));
-        }
+    // If the plugin was installed via `hermes plugins install` (a git checkout
+    // that actually contains the plugin — .git alone could be an empty/partial
+    // dir), do NOT copy over it — that would mix a managed checkout with
+    // copied files and break its own update path. The config below is still
+    // written: Hermes' own `memory setup` writes config.json into that tree
+    // too, so the file is expected there regardless of install path.
+    const isGitInstall = (0, node_fs_1.existsSync)((0, node_path_1.join)(pluginsDir, ".git")) && (0, node_fs_1.existsSync)((0, node_path_1.join)(pluginsDir, "plugin.yaml"));
+    if (isGitInstall) {
+        console.log("  ✓ Hermes plugin already installed (git checkout) — leaving its files, updating config only");
     }
-    console.log(`  ✓ Copied Hermes plugin to ${pluginsDir}`);
-    // Write plugin config.json (server URL only). The auth token is a SECRET and
-    // is deliberately NOT written here — `hermes memory setup` routes it to
-    // $HERMES_HOME/.env, and localhost bypasses auth entirely. Capture threshold
-    // omitted → the plugin's own default applies.
-    const config = { hicortex_url: serverUrl };
+    else {
+        const pluginFiles = (0, node_fs_1.readdirSync)(pluginSource);
+        for (const f of pluginFiles) {
+            // NEVER copy a bundled config.json over the user's: a stray one in a
+            // developer tree ships via prepack, and clobbering here would defeat
+            // the merge logic below (it runs AFTER this loop).
+            if (f === "config.json")
+                continue;
+            const src = (0, node_path_1.join)(pluginSource, f);
+            if ((0, node_fs_1.statSync)(src).isFile()) {
+                (0, node_fs_1.copyFileSync)(src, (0, node_path_1.join)(pluginsDir, f));
+            }
+        }
+        console.log(`  ✓ Copied Hermes plugin to ${pluginsDir}`);
+    }
+    // Plugin config.json: MERGE, never blindly clobber. The URL is overwritten
+    // when it is INIT-OWNED — unset, a local default (either host spelling:
+    // init has written both `localhost` and `127.0.0.1` variants historically),
+    // or exactly what init last wrote (previousServerUrl — the client config's
+    // serverUrl BEFORE this run re-pointed it). A value the USER set by hand to
+    // something else is preserved WITH A LOUD DIVERGENCE WARNING — silently
+    // keeping a stale endpoint on a re-point is the failure this guards
+    // (CR: re-point must reach the plugin like it reaches CC's MCP entry).
+    // The auth token is a SECRET and is deliberately NOT written here —
+    // `hermes memory setup` routes it to $HERMES_HOME/.env, and localhost
+    // bypasses auth entirely.
+    const stripTrailingSlash = (v) => v.replace(/\/+$/, "");
+    const localDefaults = [`http://localhost:${DEFAULT_PORT}`, `http://127.0.0.1:${DEFAULT_PORT}`];
+    // Normalize before comparing (trailing-slash variants of the same URL must
+    // not read as user-set — the client flow strips, the env-var flow does not).
+    const normalizedPrevious = previousServerUrl ? stripTrailingSlash(previousServerUrl) : undefined;
+    const isInitOwnedUrl = (v) => {
+        if (typeof v !== "string" || v === "")
+            return true;
+        const nv = stripTrailingSlash(v);
+        return localDefaults.includes(nv) || nv === normalizedPrevious;
+    };
     const configPath = (0, node_path_1.join)(pluginsDir, "config.json");
-    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
-    console.log(`  ✓ Plugin config → ${serverUrl}`);
+    let config = {};
+    if ((0, node_fs_1.existsSync)(configPath)) {
+        try {
+            config = loadConfigStrict(configPath).config;
+        }
+        catch {
+            // Corrupt/unreadable plugin config: REPLACE (this file holds no secrets
+            // by design — only URL/knobs; reset to defaults) — loudly, never
+            // silently, never fatally. (The underlying error's copy speaks of
+            // ~/.hicortex config semantics that do not apply to this file, so it
+            // is deliberately not echoed.)
+            console.log("  ⚠ Plugin config.json unreadable — replacing it (URL re-prefilled; optional knobs reset to defaults; no secrets live in this file)");
+            config = {};
+        }
+    }
+    const normalizedServerUrl = stripTrailingSlash(serverUrl);
+    let keptExistingUrl = false;
+    if (isInitOwnedUrl(config.hicortex_url)) {
+        config.hicortex_url = normalizedServerUrl;
+    }
+    else if (stripTrailingSlash(config.hicortex_url) !== normalizedServerUrl) {
+        keptExistingUrl = true;
+        console.log(`  ℹ Kept existing plugin URL ${config.hicortex_url} (differs from this install's ${normalizedServerUrl})`);
+        console.log("    Edit ~/.hermes/plugins/hicortex/config.json if that is not what you want.");
+    }
+    try {
+        (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+        console.log(keptExistingUrl ? `  ℹ Plugin config stays on ${config.hicortex_url}` : `  ✓ Plugin config → ${config.hicortex_url}`);
+    }
+    catch (e) {
+        console.log(`  ⚠ Could not write plugin config (${e instanceof Error ? e.message : e}) — Hermes setup skipped config pre-fill`);
+    }
     // For profile-based setups, symlink the shared plugin into each profile's
     // plugin dir (non-destructive). Discovery scans $HERMES_HOME/plugins/, so
     // this is belt-and-suspenders for profile-scoped installs.
@@ -394,14 +539,26 @@ function setupHermes(serverUrl, authToken) {
     // Activation is left to Hermes' own tooling. We NEVER edit config.yaml —
     // Hermes' `memory setup` discovers this plugin automatically and writes the
     // config with its own YAML-aware writer (routing the token to .env).
-    const isRemote = !(serverUrl.includes("127.0.0.1") || serverUrl.includes("localhost"));
-    console.log("  → Activate with:  hermes memory setup   (select 'hicortex')");
+    // The token is PRINTED here for the remote case (the user's own terminal —
+    // same visibility as `hicortex status`); Hermes has no non-interactive
+    // setup path, so one paste is the floor. When a user-set URL was KEPT, the
+    // token hint names that server's token requirement instead (this install's
+    // token belongs to a different server).
+    console.log("  → Activate with:  hermes memory setup hicortex");
     if ((0, node_fs_1.existsSync)(profilesDir)) {
         console.log("    Run once per profile if you use Hermes profiles.");
     }
-    if (isRemote) {
-        console.log("    Remote server: enter the auth token when prompted (stored in $HERMES_HOME/.env).");
+    if (keptExistingUrl) {
+        console.log("    The kept URL's server needs ITS token — run `hicortex status` on that machine if you don't have it.");
+    }
+    else if (authToken) {
+        console.log(`    When prompted for the token, paste:  ${authToken}`);
+        console.log("    (stored by Hermes in $HERMES_HOME/.env — never in the plugin's config.json)");
     }
+    else {
+        console.log("    Local server: leave the token blank — localhost bypasses auth.");
+    }
+    console.log("    Installed Hermes AFTER Hicortex? Re-running `npx @gamaze/hicortex init` redoes this step.");
 }
 /**
  * Parse a KEY=VALUE env file (e.g. ~/.hermes/.env or ~/.claude/settings.json env block).
@@ -1501,6 +1658,10 @@ async function runInit(options = {}) {
         console.log("  • OpenClaw plugin installed");
     if (d.hermesFound)
         console.log(`  • Hermes found at ${HERMES_HOME}`);
+    if (d.piFound)
+        console.log(`  • Pi found at ${PI_AGENT_DIR}`);
+    if (d.opencodeFound)
+        console.log(`  • opencode found at ${OPENCODE_CONFIG_DIR}`);
     if (d.ccMcpRegistered)
         console.log("  • CC MCP already registered");
     if (d.existingDb)
@@ -1532,6 +1693,10 @@ async function runInit(options = {}) {
         actions.push("Register MCP server in CC settings");
     if (d.hermesFound)
         actions.push("Install Hermes plugin + configure");
+    if (d.piFound)
+        actions.push("Install Pi extension");
+    if (d.opencodeFound)
+        actions.push("Install opencode plugin");
     actions.push("Install SessionStart hook (query-time lessons)");
     if (actions.length === 0) {
         console.log("Everything is already configured. Nothing to do.");
@@ -1649,6 +1814,14 @@ async function runInit(options = {}) {
         const isLocal = serverUrl.includes("127.0.0.1") || serverUrl.includes("localhost");
         setupHermes(serverUrl, isLocal ? "" : authToken);
     }
+    // Setup the Pi extension if detected (self-resolving — no config write)
+    if (d.piFound) {
+        setupPi();
+    }
+    // Setup the opencode plugin if detected (self-resolving — no config write)
+    if (d.opencodeFound) {
+        setupOpencode();
+    }
     // Install CC SessionStart hook for query-time lesson injection.
     // Lessons are now fetched live at session start — no static CLAUDE.md block needed.
     installSessionStartHook();
@@ -1768,6 +1941,11 @@ async function runClientInit(serverUrl, agentName) {
     // writeClientConfig: strict-load → apply overrides → save. Throws on a
     // malformed existing config (0.16.x BLOCKER — never wipe the client's
     // authToken/licenseKey). ENOENT → fresh client config.
+    // The PRE-overwrite serverUrl is captured first: it is what init last
+    // wrote into the Hermes plugin's config, so the plugin step can tell an
+    // init-owned URL (update it — re-point must reach Hermes like it reaches
+    // CC's MCP entry) from a user-set one (keep + warn).
+    const previousServerUrl = readPreviousServerUrl(configPath);
     const { config } = writeClientConfig(configPath, { serverUrl, authToken }, nameDecision);
     console.log(`  ✓ Client config saved to ${configPath}`);
     if (typeof config.agentName === "string") {
@@ -1824,7 +2002,17 @@ async function runClientInit(serverUrl, agentName) {
     // Step 8: Setup Hermes if detected
     if ((0, node_fs_1.existsSync)(HERMES_HOME)) {
         console.log("\nHermes detected — installing plugin...");
-        setupHermes(serverUrl, authToken);
+        setupHermes(serverUrl, authToken, previousServerUrl);
+    }
+    // Step 8b: Setup the Pi extension if detected (self-resolving — no config write)
+    if ((0, node_fs_1.existsSync)(PI_AGENT_DIR)) {
+        console.log("\nPi detected — installing extension...");
+        setupPi();
+    }
+    // Step 8c: Setup the opencode plugin if detected (self-resolving — no config write)
+    if ((0, node_fs_1.existsSync)(OPENCODE_CONFIG_DIR) || (0, node_fs_1.existsSync)(OPENCODE_DATA_DIR)) {
+        console.log("\nopencode detected — installing plugin...");
+        setupOpencode();
     }
     console.log("\n✓ Hicortex client setup complete!\n");
     // Telemetry disclosure at install time (informed consent, best practice):

package/dist/llm-flight.d.ts

@@ -0,0 +1,30 @@
+export type LlmFlightGuard = {
+    kind: "acquired";
+    release: () => void;
+}
+/** Waited past `waitMs` for the holder — the caller treats this as a
+ * total-failure-class error (its message contains "timeout" so the retry
+ * ladder and the #337 breaker classify it as endpoint-down). */
+ | {
+    kind: "timeout";
+}
+/** Filesystem refused the lock — proceed unserialized (fail-open). */
+ | {
+    kind: "open";
+};
+/**
+ * Default staleness floor: a lock older than this is stale REGARDLESS of the
+ * recorded pid (guards the recycled-pid case, capture A5 fix 2). The caller
+ * passes `staleMs = max(this default, 2× llmTimeoutMs)` so an operator who
+ * raises the timeout ceiling can never have a LIVE call's lock reclaimed
+ * mid-flight (CR #355 finding 3 — a reclaim-while-running is exactly the
+ * two-concurrent-calls crash class this guard exists to prevent).
+ */
+export declare const DEFAULT_STALE_MS: number;
+/** Lock path for an endpoint key — exported for tests and diagnostics. */
+export declare function llmFlightLockPath(homeDir: string, endpointKey: string): string;
+/**
+ * Acquire the single-flight lock for `endpointKey`, waiting up to `waitMs`.
+ * Never throws: every filesystem surprise degrades to `{ kind: "open" }`.
+ */
+export declare function acquireLlmFlight(homeDir: string, endpointKey: string, waitMs: number, staleMs?: number): Promise<LlmFlightGuard>;

package/dist/llm-flight.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALE_MS = void 0;
+exports.llmFlightLockPath = llmFlightLockPath;
+exports.acquireLlmFlight = acquireLlmFlight;
+/**
+ * Single-flight guard for LLM endpoint calls (#355).
+ *
+ * Local single-user model servers (one big-context model on a personal
+ * machine) have a standing failure mode: TWO concurrent large-context
+ * requests stall or OOM the server — and take the whole machine with it.
+ * One Hicortex server is several LLM callers at once: the daemon distills
+ * every inbound /distill concurrently, and the nightly's consolidation is a
+ * separate OS process on its own timers. This guard makes "never two
+ * in-flight requests to the same endpoint" STRUCTURAL instead of a hope
+ * that timers do not overlap.
+ *
+ * Same idiom as capture.ts's capture.lock (A5): O_EXCL create, dead-pid or
+ * TTL staleness with a TOCTOU re-race, and FAIL-OPEN — a filesystem refusal
+ * logs a loud warning and lets the call proceed unserialized. The guard must
+ * never be the reason recall or distillation stops on a healthy endpoint.
+ *
+ * The lock file lives in the hicortex home, one file per endpoint
+ * (sha1 of `provider@baseUrl`), so an install with multiple endpoints
+ * serializes within each endpoint, not across them.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Default staleness floor: a lock older than this is stale REGARDLESS of the
+ * recorded pid (guards the recycled-pid case, capture A5 fix 2). The caller
+ * passes `staleMs = max(this default, 2× llmTimeoutMs)` so an operator who
+ * raises the timeout ceiling can never have a LIVE call's lock reclaimed
+ * mid-flight (CR #355 finding 3 — a reclaim-while-running is exactly the
+ * two-concurrent-calls crash class this guard exists to prevent).
+ */
+exports.DEFAULT_STALE_MS = 30 * 60 * 1000;
+/**
+ * A lock file younger than this whose holder is unreadable (empty/invalid
+ * JSON) is treated as LIVE: its creator is between the O_EXCL create and the
+ * writeSync — stealing in that window is the same crash class. Only an
+ * unreadable file OLDER than the grace period is junk to reclaim
+ * (CR #355 finding 4).
+ */
+const GRACE_MS = 2_000;
+/** LLM-scale polling: waits are seconds-to-minutes, not capture-scale. */
+const POLL_MS = 100;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Warn at most once per process that the guard failed open (#355 fail-open). */
+let warnedOpen = false;
+/** Lock path for an endpoint key — exported for tests and diagnostics. */
+function llmFlightLockPath(homeDir, endpointKey) {
+    const hash = (0, node_crypto_1.createHash)("sha1").update(endpointKey).digest("hex").slice(0, 16);
+    return (0, node_path_1.join)(homeDir, `llm-flight-${hash}.lock`);
+}
+/**
+ * Acquire the single-flight lock for `endpointKey`, waiting up to `waitMs`.
+ * Never throws: every filesystem surprise degrades to `{ kind: "open" }`.
+ */
+async function acquireLlmFlight(homeDir, endpointKey, waitMs, staleMs = exports.DEFAULT_STALE_MS) {
+    const lockPath = llmFlightLockPath(homeDir, endpointKey);
+    try {
+        (0, node_fs_1.mkdirSync)(homeDir, { recursive: true });
+    }
+    catch {
+        /* best effort — the create below surfaces real problems */
+    }
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        const attempt = tryAcquireOnce(lockPath, endpointKey, staleMs);
+        if (attempt.kind !== "busy")
+            return attempt;
+        if (Date.now() >= deadline)
+            return { kind: "timeout" };
+        await sleep(Math.max(1, Math.min(POLL_MS, deadline - Date.now())));
+    }
+}
+/** One acquire attempt: create-if-free, else reclaim-if-stale. */
+function tryAcquireOnce(lockPath, endpointKey, staleMs) {
+    const release = () => {
+        try {
+            (0, node_fs_1.unlinkSync)(lockPath);
+        }
+        catch {
+            /* already gone */
+        }
+    };
+    const create = () => {
+        try {
+            const fd = (0, node_fs_1.openSync)(lockPath, "wx"); // O_CREAT | O_EXCL
+            // The lease records how long THIS holder may legitimately run
+            // (now + staleMs) — a waiter with a smaller budget judges staleness
+            // by the recorded lease, never by its own parameter (2nd-review
+            // finding 3: a short-timeout waiter must not TTL-reclaim a live
+            // long-timeout holder's lock).
+            (0, node_fs_1.writeSync)(fd, JSON.stringify({
+                pid: process.pid,
+                endpoint: endpointKey,
+                leaseUntil: Date.now() + staleMs,
+            }));
+            (0, node_fs_1.closeSync)(fd);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return false;
+            throw err;
+        }
+    };
+    try {
+        if (create())
+            return { kind: "acquired", release };
+        const holder = readHolder(lockPath);
+        if (!isStale(lockPath, holder, staleMs))
+            return { kind: "busy" };
+        // Stale. Re-verify the holder has not changed (another reclaimer may
+        // have taken it), unlink, re-race the O_EXCL create (capture fix 12).
+        // Compare by VALUE (pid/endpoint) — readHolder returns a fresh object
+        // per call, so reference equality would always differ.
+        const recheck = readHolder(lockPath);
+        if (recheck?.pid !== holder?.pid ||
+            recheck?.endpoint !== holder?.endpoint) {
+            return { kind: "busy" };
+        }
+        try {
+            (0, node_fs_1.unlinkSync)(lockPath);
+        }
+        catch {
+            /* raced with another reclaimer */
+        }
+        return create() ? { kind: "acquired", release } : { kind: "busy" };
+    }
+    catch {
+        // Filesystem refused the lock op entirely — do not wedge LLM traffic on
+        // the guard; proceed unserialized (the behaviour before #355).
+        if (!warnedOpen) {
+            warnedOpen = true;
+            console.warn(`[hicortex] LLM single-flight lock unavailable (${lockPath}) — ` +
+                `proceeding WITHOUT serialization. This is safe for recall but ` +
+                `concurrent LLM calls can stall a single-user local model server.`);
+        }
+        return { kind: "open" };
+    }
+}
+function readHolder(lockPath) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(lockPath, "utf-8"));
+        if (typeof parsed.pid === "number" && Number.isFinite(parsed.pid))
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Stale = dead pid, OR past the HOLDER's recorded lease, OR (lease-less
+ *  lock files) older than the waiter's `staleMs`. An unreadable holder
+ *  (mid-write or corrupt) is live within the grace period, junk after it. */
+function isStale(lockPath, holder, staleMs) {
+    if (!holder) {
+        try {
+            return Date.now() - (0, node_fs_1.statSync)(lockPath).mtimeMs > GRACE_MS;
+        }
+        catch {
+            return true;
+        }
+    }
+    if (!isProcessAlive(holder.pid))
+        return true;
+    if (typeof holder.leaseUntil === "number" && Number.isFinite(holder.leaseUntil)) {
+        return Date.now() > holder.leaseUntil;
+    }
+    try {
+        return Date.now() - (0, node_fs_1.statSync)(lockPath).mtimeMs > staleMs;
+    }
+    catch {
+        return true;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process; EPERM = exists but not ours (still alive).
+        return err.code === "EPERM";
+    }
+}

package/dist/llm.d.ts

@@ -48,6 +48,15 @@ export interface LlmConfig {
     /** TTL the daemon caches a probe outcome for (#337). Default 300000.
      *  See HicortexConfig.llmProbeTtlMs. */
     probeTtlMs?: number;
+    /** Single-flight serialization: at most ONE in-flight LLM request per
+     *  endpoint, ever (#355). Default true — a correctness property for local
+     *  single-user model servers (two concurrent large-context calls stall/OOM
+     *  the server and the machine under it). See HicortexConfig.llmSingleFlight. */
+    singleFlight?: boolean;
+    /** How long a queued call waits for the in-flight call before failing as
+     *  endpoint-down (#355). Default 900000 — the same ceiling as llmTimeoutMs.
+     *  See HicortexConfig.llmSingleFlightWaitMs. */
+    singleFlightWaitMs?: number;
 }
 /**
  * Resolve LLM configuration from explicit config-file overrides or
@@ -155,6 +164,14 @@ export interface LlmResult {
 export declare class LlmCircuitOpenError extends Error {
     constructor(endpoint: string, cooldownRemainingMs: number);
 }
+/**
+ * The TOTAL-failure class the retry ladder matches (#337, unchanged strings —
+ * this is the same matcher the ladder has always used, now also the breaker's
+ * definition of "endpoint may be down"). A fast HTTP 500, a parse error, or a
+ * rate limit is NOT in this class: those prove the endpoint ANSWERS.
+ */
+declare function isTotalFailure(message: string): boolean;
+export { isTotalFailure };
 export declare class LlmClient {
     private config;
     private ollamaCallCount;
@@ -213,6 +230,21 @@ export declare class LlmClient {
     probe(timeoutMs?: number): Promise<boolean>;
     private complete;
     private completeOnce;
+    /** The single-flight wait budget for a call with ceiling `timeoutMs`.
+     *  An explicit `llmSingleFlightWaitMs` wins; otherwise the default is
+     *  max(900 s, llmTimeoutMs) so a waiter never gives up before a legitimate
+     *  in-flight call's own (possibly raised) ceiling expires (2nd-review
+     *  finding 2 — a hardcoded 900 s made a raised-timeout install treat a
+     *  healthy-busy endpoint as down). */
+    private flightWaitMs;
+    /** Resolve the flight guard for this call, or undefined when disabled.
+     *  `staleMs` is derived from THIS call's timeout ceiling (≥ the 30-min
+     *  floor, 2× timeout) so a raised `llmTimeoutMs` can never get a live
+     *  call's lock reclaimed mid-flight (CR #355 finding 3). The lock file
+     *  records its own lease, so reclaim is judged by the HOLDER's lease, not
+     *  this waiter's parameter (2nd-review finding 3). */
+    private acquireFlightGuard;
+    private dispatchOnce;
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.