@gamaze/hicortex 0.19.6 → 0.20.0

package/README.md

@@ -4,7 +4,7 @@
 
 Your agents learn from every session — successes and mistakes. Hicortex captures experiences, distills lessons, and applies them automatically. Connect multiple agents to shared memory and they improve together, overnight.
 
-Works with **Hermes**, **OpenClaw**, **Claude Code**, **Pi**, and any MCP-compatible agent.
+Works with **Hermes**, **OpenClaw**, **Claude Code**, **Pi**, **opencode**, and any MCP-compatible agent.
 
 **Website:** [hicortex.gamaze.com](https://hicortex.gamaze.com) · **Docs:** [hicortex.gamaze.com/docs](https://hicortex.gamaze.com/docs/)
 
@@ -87,7 +87,7 @@ Bare top-level keys (`"serverUrl": …` at the root of `openclaw.json`) still wo
 | When | What | How |
 |------|------|-----|
 | Agent start | Standing identity (`## Identity`) + recent lessons fetched fresh and injected | CC SessionStart hook (calls `hicortex learnings-identity`; `lessons-context` kept as an alias so existing installed hooks don't break) / Hermes plugin `system_prompt_block` / OC `before_agent_start` hook |
-| Every prompt (0.14) | A compact **recall index** of relevant memories is injected — one line per memory; the agent lazy-loads full content with `hicortex_get` only when needed | All three harnesses call server `POST /recall-index` per turn: CC UserPromptSubmit hook (`hicortex recall-hook`), Hermes plugin `prefetch` (0.7.0; falls back to `/search` injection against a pre-0.14 server), OC `before_agent_start` hook (fires per inbound message). Turn-based dedup per session; resets on new session/compaction. Fail-soft |
+| Every prompt (0.14) | A compact **recall index** of relevant memories is injected — one line per memory; the agent lazy-loads full content with `hicortex_get` only when needed | All five harnesses call server `POST /recall-index` per turn: CC UserPromptSubmit hook (`hicortex recall-hook`), Hermes plugin `prefetch` (0.7.0; falls back to `/search` injection against a pre-0.14 server), OC `before_agent_start` hook (fires per inbound message), Pi extension `before_agent_start` (0.20), opencode plugin messages-transform hook (0.21). Turn-based dedup per session; resets on new session/compaction. Fail-soft |
 | Nightly | Denoise sessions → POST /distill → server distills + embeds + stores → consolidate (score, reflect, link, decay) | Automatic pipeline — no manual steps |
 
 **Exposure vs use (0.14):** appearing in the recall index only marks a memory as *shown* (it stops decaying while topically active); fetching it with `hicortex_get` marks it as *used* (durable strengthening). Memory importance is driven by what agents actually use, not by what was pushed at them.
@@ -158,7 +158,7 @@ Beyond auto-distilled memories and lessons, Hicortex holds a **hand-edited ident
 
 - **Storage:** plain files on the server at `~/.hicortex/identity/*.md` — one file per section (recommended starter sections `user.md` + `rules.md`, which you create — nothing is pre-populated; add more by dropping in a file). It lives outside the memories table; consolidation never touches it.
 - **Edit:** the web editor at `http://localhost:8787/identity/ui` (one tab per section, Save), or the CLI `hicortex identity show [name]` / `hicortex identity edit <name>`.
-- **Delivery:** injected into the harnesses listed in `identityClients` (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc` — all three are supported since 0.13).
+- **Delivery:** injected into the harnesses listed in `identityClients` (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`/`pi`/`opencode` — CC/Hermes/OpenClaw since 0.13, Pi since 0.20, opencode since 0.21).
 - **Deletion** is filesystem-only — remove the file on the server (as the daemon user).
 
 ### Per-agent identity (0.13)
@@ -183,6 +183,7 @@ npx @gamaze/hicortex init                      # Set up server mode
 npx @gamaze/hicortex init --server <url>       # Set up client mode
 npx @gamaze/hicortex nightly                   # Run distill + consolidate (full nightly)
 npx @gamaze/hicortex nightly --capture-only    # Capture only, skip consolidation (safe for sub-daily runs)
+npx @gamaze/hicortex nightly --evict-only      # Memory-cap eviction only — pure DB, no capture, no LLM (idempotent; honors --dry-run)
 npx @gamaze/hicortex nightly --dry-run         # Preview without changes
 npx @gamaze/hicortex classify-domains          # Backfill domain tags over the corpus (see Memory Domains & Tags)
 npx @gamaze/hicortex classify-types            # Reclassify memory types (episode/fact/decision)
@@ -239,16 +240,19 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `llmBreakerCooldownMs` | How long the breaker stays open before one half-open trial call goes out (default 600000 = 10 min). A failing trial re-opens it; a succeeding one resets the counter. |
 | `llmProbeTimeoutMs` | Patience of the readiness probe — one minimal 1-token generation request the nightly sends before consolidating and the daemon sends before distilling (default 60000 = 1 min). Catches a gateway that answers health/model-list queries while generation is dead; a failed probe skips consolidation (`endpoint_down`, retried next run) and answers `/distill` with a 503 so capture holds its cursor. |
 | `llmProbeTtlMs` | How long the daemon caches a `/distill` probe outcome (default 300000 = 5 min). A healthy capture cadence pays at most one probe per window; a dead endpoint turns into fast cached 503s instead of every request paying the probe timeout. |
+| `llmSingleFlight` | **Serialized LLM calls — default `true`.** At most ONE request in flight per endpoint at any moment, across every process (the daemon distilling concurrent captures, the nightly consolidating, CLI backfills take turns via a per-endpoint lock file). One Hicortex server is several callers at once, and local single-user model servers (a Mac mini or laptop serving one big-context model) can stall or crash — taking the machine with them — under two concurrent large requests. Queued calls wait their turn; batches run back-to-back. **Set `false` if your endpoint is a beefy multi-tenant service that parallelizes well and you want faster consolidation** — you opt into responsibility for the endpoint's concurrency safety. |
+| `llmSingleFlightWaitMs` | How long a queued call waits for the in-flight call before failing as endpoint-down and retrying per the normal ladder/breaker rules (default: `max(900000, llmTimeoutMs)` — a waiter never gives up before a legitimate in-flight call's own, possibly raised, ceiling expires). Only meaningful with serialization on. Note under contention: the readiness probe queues too, but its wait is capped by its own probe budget — during a long consolidation batch, `/distill` answers 503 quickly (captures cursor-hold and retry, lossless) rather than holding the socket for the full queue budget. |
 | `authToken` | Bearer token for endpoint auth. Generated on first `init` in server mode. Find the active token with `hicortex status` or in `~/.hicortex/config.json`. |
 | `corsAllowedOrigins` | Browser origins allowed to read cross-origin responses, e.g. `["https://ui.example.com"]`. **Empty by default** — the server sends no `Access-Control-Allow-Origin` and never `Allow-Credentials`, so no external web page can read its data. The bundled `/viz` and `/identity/ui` pages are same-origin and need no entry. |
 | `licenseKey` | Commercial license key (optional; for display in `hicortex status`) |
 | `backupRetention` | How many of the newest backup artifacts (`hicortex-*.tar.gz`) the backup dir keeps after each successful write (default: 7; `0` keeps all). See [Backups](#backups) |
 | _env_ `HICORTEX_DISTILL_BODY_LIMIT_MB` | Environment override for the `/distill` body limit — **wins over the `distillBodyLimitMb` config key in every mode** (that is the point: a deployment operator pins it so tenant-writable config cannot raise it). Unset = config/default applies. |
+| _env_ `HICORTEX_MEMORY_CAP` | Environment override for the memory soft cap — a **positive** value wins over the `memorySoftCap` config key in every mode; `0`/negative/malformed fall through to the config key, then the 10000 default (an env can pin a cap, never disable one — config `memorySoftCap: 0` still disables when the env is unset). Mode-agnostic operator knob: nightly eviction, the dashboard-snapshot capacity stamp, and the live dashboard gauge all resolve through the same resolver, so the enforced and displayed caps can never disagree. Drives `nightly --evict-only` the same way. |
 | `domains` | Your memory domain list (`[{name, description}]`). Scaffolded by `init`; edit freely — see [Memory Domains & Tags](#memory-domains--tags) |
 | `weakPrimaryFloor` | Minimum similarity for a no-fit memory to keep a weak domain association (default: 0.45) |
 | `moduleIndexTokenBudget` | Max tokens for domain index in lessons context (default: 500) |
 | `lessonsLimit` | Max lessons injected into an agent's session-start context (default: 10). Lessons are ranked per session by project/domain affinity + recency + strength + access, so each session sees its most-relevant slice. Lower = leaner system prompts. |
-| `identityClients` | Which harnesses inject the [identity layer](#identity-layer) at session start (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`) |
+| `identityClients` | Which harnesses inject the [identity layer](#identity-layer) at session start (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`/`pi`/`opencode`) |
 | `identityAgents` | Per-agent identity modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent identity](#per-agent-identity-013) |
 | `agentName` | This install's per-agent identity id sent as `?agent=`. **Unset by default** (CC shares the global identity — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
 | `captureCooldownHours` | Success-cooldown (hours) for the **capture watchdog** (0.17). The capture timer polls every ~20 min; the watchdog captures only if more than this has elapsed since the last *successful* capture (`state.lastNightly`). Default `6` (≈4 captures/day). A failed preflight retries on the next poll (~20 min) — so a transient fire-instant network miss costs minutes, not a day (#239) |

package/dist/cli.d.ts

@@ -8,6 +8,7 @@
  *   nightly    Run capture + consolidate (manual trigger)
  *              nightly --capture-only     Capture only, skip consolidation
  *              nightly --consolidate-only Consolidate only, skip capture (hosted service)
+ *              nightly --evict-only       Memory-cap eviction only — pure DB, no LLM (#317)
  *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
  *   dedup      Cluster + merge near-duplicate memories (issue #100)

package/dist/cli.js

@@ -9,6 +9,7 @@
  *   nightly    Run capture + consolidate (manual trigger)
  *              nightly --capture-only     Capture only, skip consolidation
  *              nightly --consolidate-only Consolidate only, skip capture (hosted service)
+ *              nightly --evict-only       Memory-cap eviction only — pure DB, no LLM (#317)
  *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
  *   dedup      Cluster + merge near-duplicate memories (issue #100)
@@ -71,11 +72,16 @@ switch (command) {
             const dryRun = args.includes("--dry-run");
             const captureOnly = args.includes("--capture-only");
             const consolidateOnly = args.includes("--consolidate-only");
+            const evictOnly = args.includes("--evict-only");
             const watchdog = args.includes("--watchdog");
             if (captureOnly && consolidateOnly) {
                 console.error("[hicortex] nightly: --capture-only and --consolidate-only are mutually exclusive");
                 process.exit(1);
             }
+            if (evictOnly && (captureOnly || consolidateOnly)) {
+                console.error("[hicortex] nightly: --evict-only is mutually exclusive with --capture-only and --consolidate-only");
+                process.exit(1);
+            }
             // Timestamp every log line. The nightly writes to a file (launchd /
             // systemd StandardOutput append) with NO per-line timestamp, which made
             // diagnosing capture gaps impossible (the #239 investigation couldn't
@@ -98,7 +104,7 @@ switch (command) {
                 }
             }
             import("./nightly.js").then(({ runNightly }) => {
-                runNightly({ dryRun, captureOnly, consolidateOnly, watchdog, recaptureWindowDays }).catch((err) => {
+                runNightly({ dryRun, captureOnly, consolidateOnly, evictOnly, watchdog, recaptureWindowDays }).catch((err) => {
                     console.error("[hicortex] Nightly pipeline failed:", err);
                     process.exit(1);
                 });
@@ -355,6 +361,7 @@ Options:
   nightly --dry-run         Preview without changes
   nightly --capture-only    Capture only, skip consolidation (safe to run multiple times/day)
   nightly --consolidate-only  Consolidate only, skip capture (hosted-service per-tenant runs)
+  nightly --evict-only      Memory-cap eviction only — pure DB, no capture, no LLM (#317)
   nightly --recapture-window <days>   Re-discover sessions quiet since <days> ago (one-shot #189 recovery)
   nightly --status          Show nightly pipeline health
   relink --dry-run          Discovery + counts only, zero writes, cursor untouched

package/dist/consolidate.d.ts

@@ -285,6 +285,27 @@ export declare function stageDecayPrune(db: Database.Database, dryRun: boolean):
  * (recall top-k competes against the long tail). Override via `memorySoftCap`.
  */
 export declare const DEFAULT_MEMORY_SOFT_CAP = 10000;
+/**
+ * Resolve the effective soft cap (#317): a positive finite HICORTEX_MEMORY_CAP
+ * env wins over the `memorySoftCap` config key, which wins over
+ * DEFAULT_MEMORY_SOFT_CAP. The env is the PRICING boundary — in the hosted
+ * stack the cap is a per-plan parameter the provider pins into the tenant .env
+ * (docker exec inherits container env, so the eviction path sees it), and the
+ * tenant's config.json is bind-mounted writable at /data, so config-only
+ * resolution would let a tenant raise or disable its own cap. Same
+ * env-wins-precedence pattern as resolveTokenCap (token-budget.ts) and
+ * resolveBodyLimitMb (mcp-server.ts).
+ *
+ * Deliberate asymmetry with resolveTokenCap: a MALFORMED/0/negative env falls
+ * through (an env can pin a cap but never disable one), while config 0 is
+ * still honored as the #245 opt-out (indefinite growth) when the env is unset
+ * — env unset → config → default is exactly the pre-#317 behavior, so a
+ * self-hosted install that never hears about the env sees no change. Pure —
+ * exported for tests; every consumer (nightly eviction + snapshot stamp,
+ * dashboard live headline) must route through this ONE function so the
+ * enforced cap and the displayed cap cannot disagree.
+ */
+export declare function resolveMemorySoftCap(configVal: unknown): number;
 export declare function stageMemoryCapEviction(db: Database.Database, dryRun: boolean, cap: number): {
     cap: number;
     evicted: number;

package/dist/consolidate.js

@@ -50,12 +50,14 @@ exports.buildSupersessionPrompt = buildSupersessionPrompt;
 exports.parseSupersessionReply = parseSupersessionReply;
 exports.stageSupersession = stageSupersession;
 exports.stageDecayPrune = stageDecayPrune;
+exports.resolveMemorySoftCap = resolveMemorySoftCap;
 exports.stageMemoryCapEviction = stageMemoryCapEviction;
 exports.runConsolidation = runConsolidation;
 exports.msUntilHour = msUntilHour;
 exports.scheduleConsolidation = scheduleConsolidation;
 const retrieval_js_1 = require("./retrieval.js");
 const storage = __importStar(require("./storage.js"));
+const config_read_js_1 = require("./config-read.js");
 const prompts_js_1 = require("./prompts.js");
 const node_crypto_1 = require("node:crypto");
 const features_js_1 = require("./features.js");
@@ -1261,6 +1263,41 @@ function stageDecayPrune(db, dryRun) {
  * (recall top-k competes against the long tail). Override via `memorySoftCap`.
  */
 exports.DEFAULT_MEMORY_SOFT_CAP = 10000;
+/** Env override for the soft cap (#317). Hosted: provider-set via the tenant
+ *  .env, tenant-immutable at runtime (same posture as HICORTEX_TOKEN_CAP).
+ *  Self-hosted: an operator knob — mode-agnostic, never branches on
+ *  hostedMode. */
+const MEMORY_CAP_ENV = "HICORTEX_MEMORY_CAP";
+/**
+ * Resolve the effective soft cap (#317): a positive finite HICORTEX_MEMORY_CAP
+ * env wins over the `memorySoftCap` config key, which wins over
+ * DEFAULT_MEMORY_SOFT_CAP. The env is the PRICING boundary — in the hosted
+ * stack the cap is a per-plan parameter the provider pins into the tenant .env
+ * (docker exec inherits container env, so the eviction path sees it), and the
+ * tenant's config.json is bind-mounted writable at /data, so config-only
+ * resolution would let a tenant raise or disable its own cap. Same
+ * env-wins-precedence pattern as resolveTokenCap (token-budget.ts) and
+ * resolveBodyLimitMb (mcp-server.ts).
+ *
+ * Deliberate asymmetry with resolveTokenCap: a MALFORMED/0/negative env falls
+ * through (an env can pin a cap but never disable one), while config 0 is
+ * still honored as the #245 opt-out (indefinite growth) when the env is unset
+ * — env unset → config → default is exactly the pre-#317 behavior, so a
+ * self-hosted install that never hears about the env sees no change. Pure —
+ * exported for tests; every consumer (nightly eviction + snapshot stamp,
+ * dashboard live headline) must route through this ONE function so the
+ * enforced cap and the displayed cap cannot disagree.
+ */
+function resolveMemorySoftCap(configVal) {
+    const envCap = Number(process.env[MEMORY_CAP_ENV]);
+    if (Number.isFinite(envCap) && envCap > 0)
+        return envCap;
+    // Reuse the disk→runtime boundary validator (warn-on-rejected-value) so the
+    // config half behaves byte-for-byte like the pre-#317 readNonNegativeConfig
+    // call sites: absent → default, valid non-negative (incl. 0 = disabled)
+    // passes through, invalid → warn + default.
+    return (0, config_read_js_1.readNonNegativeConfig)({ memorySoftCap: configVal }, "memorySoftCap", exports.DEFAULT_MEMORY_SOFT_CAP);
+}
 function stageMemoryCapEviction(db, dryRun, cap) {
     // `0` = explicitly disabled (current/legacy behaviour). The guard is on `<=`
     // not `===` to also absorb a stray negative (readNonNegativeConfig already

package/dist/dashboard.js

@@ -361,7 +361,10 @@ function handleDashboardData(db, query, config) {
     // Headline = live corpus (the chart shows history; the headline shows now).
     // `memory_soft_cap` (#245): resolve from the live config (the source of
     // truth for "what cap is in force right now"), defaulting to the production
-    // default. The page renders no gauge when it's 0 (disabled).
+    // default. The page renders no gauge when it's 0 (disabled). #317: routes
+    // through resolveMemorySoftCap so a HICORTEX_MEMORY_CAP env pin is honored
+    // here too — the DISPLAYED cap can never disagree with the ENFORCED cap
+    // (both consumers share the one resolver).
     //
     // `tokens` (#246): period accrual from state.json (the same single source
     // the throttle check reads, so the dashboard always agrees with the runtime
@@ -372,7 +375,7 @@ function handleDashboardData(db, query, config) {
         total_memories: live.totals.mem,
         uses_per_showing: live.adoption?.uses_per_showing ?? null,
         cold_count: live.adoption?.cold_count ?? 0,
-        memory_soft_cap: (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "memorySoftCap", consolidate_js_1.DEFAULT_MEMORY_SOFT_CAP),
+        memory_soft_cap: (0, consolidate_js_1.resolveMemorySoftCap)(config?.memorySoftCap),
         tokens: {
             used: tokenState?.total ?? 0,
             cap: (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "llmTokensPerMonth", 0),

package/dist/identity-store.d.ts

@@ -227,9 +227,9 @@ export declare const IDENTITY_SIZE_WARN_BYTES = 16384;
 /** Backcompat alias for the pre-rename name (#264). */
 export declare const CONTEXT_SIZE_WARN_BYTES = 16384;
 /** Harness names that may inject the identity layer. */
-export declare const KNOWN_IDENTITY_CLIENTS: readonly ["cc", "hermes", "oc"];
+export declare const KNOWN_IDENTITY_CLIENTS: readonly ["cc", "hermes", "oc", "pi", "opencode"];
 /** Backcompat alias for the pre-rename name (#264). */
-export declare const KNOWN_CONTEXT_CLIENTS: readonly ["cc", "hermes", "oc"];
+export declare const KNOWN_CONTEXT_CLIENTS: readonly ["cc", "hermes", "oc", "pi", "opencode"];
 export interface ResolvedIdentityClients {
     /** The resolved, de-duped list of known client names. */
     clients: string[];
@@ -240,7 +240,7 @@ export interface ResolvedIdentityClients {
 export type ResolvedContextClients = ResolvedIdentityClients;
 /**
  * Normalize the raw `identityClients` config value (spec §2):
- *  - `"all"` (any case)      → ["cc","hermes","oc"]
+ *  - `"all"` (any case)      → ["cc","hermes","oc","pi","opencode"]
  *  - array                   → lowercase, keep known names (de-duped), collect dropped unknowns
  *  - missing / non-array-non-"all" → default ["cc"]
  * The resolved list is echoed by GET /identity as `clients` so each harness's

package/dist/identity-store.js

@@ -467,12 +467,12 @@ exports.CONTEXT_SIZE_WARN_BYTES = exports.IDENTITY_SIZE_WARN_BYTES;
 // Config — identityClients normalization
 // ---------------------------------------------------------------------------
 /** Harness names that may inject the identity layer. */
-exports.KNOWN_IDENTITY_CLIENTS = ["cc", "hermes", "oc"];
+exports.KNOWN_IDENTITY_CLIENTS = ["cc", "hermes", "oc", "pi", "opencode"];
 /** Backcompat alias for the pre-rename name (#264). */
 exports.KNOWN_CONTEXT_CLIENTS = exports.KNOWN_IDENTITY_CLIENTS;
 /**
  * Normalize the raw `identityClients` config value (spec §2):
- *  - `"all"` (any case)      → ["cc","hermes","oc"]
+ *  - `"all"` (any case)      → ["cc","hermes","oc","pi","opencode"]
  *  - array                   → lowercase, keep known names (de-duped), collect dropped unknowns
  *  - missing / non-array-non-"all" → default ["cc"]
  * The resolved list is echoed by GET /identity as `clients` so each harness's

package/dist/init.d.ts

@@ -6,7 +6,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)

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)
@@ -80,6 +82,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 +95,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 +136,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,6 +345,58 @@ 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) {
@@ -1501,6 +1567,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 +1602,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 +1723,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();
@@ -1826,6 +1908,16 @@ async function runClientInit(serverUrl, agentName) {
         console.log("\nHermes detected — installing plugin...");
         setupHermes(serverUrl, authToken);
     }
+    // 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):
     // opt-out telemetry is only acceptable if the user is TOLD about it.

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";
+    }
+}