@gamaze/hicortex 0.12.1 → 0.13.1

package/dist/distiller.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectChunkSize = detectChunkSize;
 exports.extractConversationText = extractConversationText;
 exports.distillSession = distillSession;
+exports.hasMinimalSubstance = hasMinimalSubstance;
 const prompts_js_1 = require("./prompts.js");
 const redact_js_1 = require("./redact.js");
 const MAX_TRANSCRIPT_CHARS = 80_000;
@@ -215,8 +216,12 @@ function extractConversationText(messages, redactionConfig) {
  * Send filtered conversation to LLM for knowledge extraction.
  * For large transcripts, chunks into segments to avoid overwhelming small models.
  * Returns an array of memory entries to ingest, or empty array if nothing worth extracting.
+ *
+ * `droppedOut`, when provided, is filled with every entry the substance gate
+ * discarded (full text). Callers use it to build a durable audit trail (#156);
+ * omitting it leaves gate behaviour unchanged.
  */
-async function distillSession(llm, conversation, projectName, date, chunkSizeChars) {
+async function distillSession(llm, conversation, projectName, date, chunkSizeChars, droppedOut) {
     if (conversation.length < MIN_CONVERSATION_CHARS) {
         return [];
     }
@@ -229,7 +234,10 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
     const chunkSize = chunkSizeChars ?? MAX_TRANSCRIPT_CHARS;
     // If transcript fits in one chunk, distill directly (errors propagate)
     if (transcript.length <= chunkSize) {
-        return distillChunk(llm, transcript, projectName, date);
+        const { entries, dropped } = await distillChunk(llm, transcript, projectName, date);
+        if (droppedOut)
+            droppedOut.push(...dropped);
+        return entries;
     }
     // Chunk large transcripts and distill each segment.
     //
@@ -248,7 +256,9 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
     for (let i = 0; i < chunks.length; i++) {
         console.log(`[hicortex]     Chunk ${i + 1}/${chunks.length} (${chunks[i].length} chars)`);
         try {
-            const entries = await distillChunk(llm, chunks[i], projectName, date);
+            const { entries, dropped } = await distillChunk(llm, chunks[i], projectName, date);
+            if (droppedOut)
+                droppedOut.push(...dropped);
             for (const entry of entries) {
                 // Deduplicate by normalized content
                 const key = entry.toLowerCase().replace(/\s+/g, " ").slice(0, 100);
@@ -279,13 +289,17 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
  * Distill a single chunk of conversation text.
  *
  * Behaviour contract:
- *   - Returns `[]` for legitimate empty results (NO_EXTRACT, empty LLM response,
- *     transcript produced no entries). These are terminal states — the chunk was
- *     processed successfully, there's just nothing worth keeping.
+ *   - Returns `{entries: [], dropped: []}` for legitimate empty results
+ *     (NO_EXTRACT, empty LLM response, transcript produced no entries). These are
+ *     terminal states — the chunk was processed successfully, there's just
+ *     nothing worth keeping.
  *   - Throws for transient errors (LLM unreachable, HTTP 4xx/5xx, timeout, model
  *     not found, rate limit). These MUST propagate so the nightly pipeline can
  *     distinguish "nothing to extract" from "try again later" and avoid
  *     advancing the last-run watermark past sessions it never actually processed.
+ *
+ * `dropped` carries entries the substance gate rejected (full text) so the
+ * caller can surface them in a durable audit trail (#156).
  */
 async function distillChunk(llm, transcript, projectName, date) {
     const prompt = (0, prompts_js_1.distillation)(projectName, date, transcript);
@@ -295,11 +309,24 @@ async function distillChunk(llm, transcript, projectName, date) {
     // "processed successfully with zero extractions".
     const result = await llm.completeDistill(prompt);
     if (!result)
-        return [];
+        return { entries: [], dropped: [] };
     if (result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT")) {
-        return [];
+        return { entries: [], dropped: [] };
     }
-    return parseDistilledEntries(result);
+    const parsed = parseDistilledEntries(result);
+    const entries = [];
+    const dropped = [];
+    for (const entry of parsed) {
+        (hasMinimalSubstance(entry) ? entries : dropped).push(entry);
+    }
+    if (dropped.length > 0) {
+        for (const d of dropped) {
+            const preview = d.length > 120 ? `${d.slice(0, 120)}…` : d;
+            console.log(`[hicortex]     Substance gate: dropped "${preview}"`);
+        }
+        console.log(`[hicortex]     Substance gate: dropped ${dropped.length}/${parsed.length} content-free fragment(s)`);
+    }
+    return { entries, dropped };
 }
 /**
  * Split transcript text into chunks at natural boundaries (double newlines).
@@ -330,6 +357,51 @@ function splitIntoChunks(text, maxChars) {
     }
     return chunks.filter((c) => c.length >= MIN_CONVERSATION_CHARS);
 }
+// Entries longer than this trivially carry substance; the cap short-circuits
+// the checks below and bounds every regex to a small input, so no pathological
+// input can make the gate expensive (#156).
+const MAX_GATE_LENGTH = 2000;
+/**
+ * Reject ONLY structurally-empty distiller fragments before they become
+ * memories (#156). The distiller occasionally emits leftovers that parse into
+ * entries but carry no recallable content:
+ *   - bare section prefixes:        "[Specific AI Content:]", "[Facts Learned]"
+ *   - echoed template placeholders: "[decision]: [reasoning] (2026-07-05)"
+ *   - pseudo-header bullets:        "**Facts Learned:**"
+ *   - metadata-only lines:          "(2026-07-05)"
+ *
+ * PRECISION OVER RECALL — deliberate trade: the gate rejects only shapes that
+ * are structurally empty of content, never on a length or word-count threshold.
+ * A kept artifact ("Classification: WORK" style) is cheaply pruned later by the
+ * no-fit decay path; a wrongly-dropped genuine memory is unrecoverable. So when
+ * in doubt, keep. Consequence documented for the reviewer: metadata lines like
+ * "Classification: WORK" now PASS the gate — that is intended.
+ *
+ * Stripping is scoped and anchored (one leading section prefix, one trailing
+ * date stamp), never global, so bracketed payloads ("use [ollama] not
+ * [claude-cli]") and content-bearing dates ("deadline moved (2026-08-01)")
+ * survive. Stripping affects only this gate's decision, never stored text.
+ */
+function hasMinimalSubstance(entry) {
+    const raw = entry.trim();
+    if (raw.length > MAX_GATE_LENGTH)
+        return true;
+    // Strip ONE leading section prefix (anchored + length-bounded, never global).
+    let body = raw.replace(/^\[[^\]]{0,80}\]\s*/, "");
+    // Strip ONE trailing date stamp (anchored to end).
+    body = body.replace(/\(\s*\d{4}-\d{2}-\d{2}\s*\)\s*$/, "");
+    // Markdown decoration.
+    body = body.replace(/[*_`#>]/g, " ").trim();
+    if (!body)
+        return false; // metadata-only line or bare section prefix
+    if (/:$/.test(body))
+        return false; // pseudo-header: "Facts Learned:"
+    // Pure placeholder echo — nothing but bracketed tokens and separators,
+    // e.g. "[decision]: [reasoning]".
+    if (/^(?:\[[^\]]{0,80}\]|[\s:.,;–-])+$/.test(body))
+        return false;
+    return true;
+}
 /**
  * Parse distilled markdown into individual memory entry strings.
  * Each section item becomes a separate memory.

package/dist/index.js

@@ -23,6 +23,8 @@ const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
+const context_store_js_1 = require("./context-store.js");
+const lessons_context_js_1 = require("./lessons-context.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -31,7 +33,10 @@ const node_os_1 = require("node:os");
 // ---------------------------------------------------------------------------
 const DEFAULT_SERVER_URL = "http://127.0.0.1:8787";
 const LESSONS_TIMEOUT_MS = 3000;
+const CONTEXT_TIMEOUT_MS = 3000;
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** Harness name this plugin injects for — used to self-gate on GET /context `clients`. */
+const THIS_HARNESS = "oc";
 // ---------------------------------------------------------------------------
 // Module state — initialized in registerService.start()
 // ---------------------------------------------------------------------------
@@ -95,6 +100,54 @@ async function serverPost(path, body, timeoutMs) {
     }
 }
 // ---------------------------------------------------------------------------
+// Context layer (L2) — per-agent standing context (0.13)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch GET /context (per-agent when an id is supplied) and build the
+ * `## Context` block via the shared gate (gateAndRenderContext), or null when
+ * nothing should be injected. The old-server guard is required only when an
+ * agent id was actually sent (amendment A2 — a bare fetch skips it). The server
+ * does the merge; the plugin stays dumb (no client-side mode logic).
+ */
+async function fetchOcContextBlock(agentId) {
+    const path = agentId ? `/context?agent=${encodeURIComponent(agentId)}` : "/context";
+    const { data } = await serverGet(path, CONTEXT_TIMEOUT_MS);
+    if (!data)
+        return null;
+    return (0, lessons_context_js_1.gateAndRenderContext)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
+}
+/**
+ * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
+ * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
+ * output; the caller prepends the `## Context` block and adds separators.
+ */
+async function buildLessonsBlock(project) {
+    const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
+    if (!data || !data.lessons || data.lessons.length === 0)
+        return null;
+    const maxLessons = (0, features_js_1.lessonsLimit)();
+    const state = (0, state_js_1.loadState)(hicortexHome);
+    const moduleIndex = data.moduleIndex ?? state.moduleIndex;
+    const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
+        maxLessons,
+        project,
+        moduleIndex,
+    });
+    if (selected.length === 0)
+        return null;
+    const formatted = selected.map((l) => {
+        const titleMatch = l.content.match(/## Lesson: (.+)/);
+        const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
+        const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
+        const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
+        const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
+        return `- ${title}${meta ? ` (${meta})` : ""}`;
+    });
+    return (`## Hicortex Lessons (auto-injected from long-term memory)\n` +
+        `These are actionable lessons learned from past sessions:\n\n` +
+        formatted.join("\n"));
+}
+// ---------------------------------------------------------------------------
 // Tool result formatter
 // ---------------------------------------------------------------------------
 function formatToolResults(results) {
@@ -158,40 +211,32 @@ exports.default = {
             },
         });
         // -----------------------------------------------------------------------
-        // Hook: before_agent_start — fetch lessons from server (fail-soft)
+        // Hook: before_agent_start — fetch context + lessons from server (fail-soft)
         // -----------------------------------------------------------------------
         api.on("before_agent_start", async (_event, ctx) => {
+            // Outer guard: the hook must NEVER throw (a rejection could block the
+            // agent). `ctx` itself can be nullish on some gateway variants, and the
+            // synchronous sanitize below runs before any per-fetch .catch — so the
+            // whole body is wrapped, not just the fetches.
             try {
-                // One fetch — build context and check cap from the same response.
-                const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
-                if (!data || !data.lessons || data.lessons.length === 0)
-                    return {};
-                const maxLessons = (0, features_js_1.lessonsLimit)();
-                const state = (0, state_js_1.loadState)(hicortexHome);
-                const moduleIndex = data.moduleIndex ?? state.moduleIndex;
-                const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
-                    maxLessons,
-                    project: ctx.project,
-                    moduleIndex,
-                });
-                if (selected.length === 0)
+                // Per-agent context id: sanitize the OC agent id (a symbols-only id
+                // sanitizes to null → bare /context → global set). Null id never sends
+                // ?agent=, so an old server behaves exactly as before.
+                const agentId = (0, context_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
+                // Fetch both concurrently with INDEPENDENT fail-soft: a /context
+                // failure must never cost the lessons block, and vice versa. The
+                // `## Context` block (standing context, 0.13) is prepended before
+                // `## Hicortex Lessons`, mirroring the CC hook.
+                const [contextBlock, lessonsBlock] = await Promise.all([
+                    fetchOcContextBlock(agentId).catch(() => null),
+                    buildLessonsBlock(ctx?.project).catch(() => null),
+                ]);
+                const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+                if (blocks.length === 0)
                     return {};
-                const formatted = selected.map((l) => {
-                    const titleMatch = l.content.match(/## Lesson: (.+)/);
-                    const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
-                    const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
-                    const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
-                    const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
-                    return `- ${title}${meta ? ` (${meta})` : ""}`;
-                });
-                const context = `\n\n## Hicortex Lessons (auto-injected from long-term memory)\n` +
-                    `These are actionable lessons learned from past sessions:\n\n` +
-                    formatted.join("\n") +
-                    "\n";
-                return { appendSystemContext: context };
+                return { appendSystemContext: `\n\n${blocks.join("\n\n")}\n` };
             }
             catch {
-                // Fail-soft — a broken lessons fetch must not block the agent
                 return {};
             }
         });

package/dist/init.d.ts

@@ -16,12 +16,27 @@
  *   - Install CC custom commands (/learn, /hicortex-activate)
  */
 import type { DomainDef } from "./types.js";
+/**
+ * Classify `claude mcp list` output for the hicortex entry. Pure (testable):
+ *   - "missing"    — hicortex not listed → registration didn't take
+ *   - "connected"  — listed AND reachable (✓/✔/Connected shown)
+ *   - "registered" — listed but connection not confirmed (server down / not restarted)
+ */
+export declare function parseMcpListStatus(mcpListOutput: string): "connected" | "registered" | "missing";
 /**
  * Parse a KEY=VALUE env file (e.g. ~/.hermes/.env or ~/.claude/settings.json env block).
  * Handles: comments (#), quoted values, empty lines.
  * Exported for testability.
  */
 export declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * True when an LLM is already persisted and `init` must NOT re-run provider
+ * selection: a named/flat backend, a flat baseUrl+apiKey pair, OR a nested-only
+ * `models.score` (model or baseUrl). The last clause (0.13.1) stops init from
+ * walking a nested-only config back through selection and writing flat keys that
+ * a `models.score` would then silently shadow (nested > flat).
+ */
+export declare function isLlmConfigured(config: Record<string, unknown>): boolean;
 /**
  * Generate a random auth token in the format hctx-<32 hex chars>.
  * Exported for testability.
@@ -37,6 +52,29 @@ export declare function persistAuthToken(configPath: string): {
     token: string;
     generated: boolean;
 };
+/**
+ * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
+ * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
+ * and shares the global context (one user = one identity across machines).
+ *
+ * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
+ * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
+ * returns to global, rather than erroring as an invalid id.
+ *  - explicit `--agent-name <non-empty>` → the sanitized flag (error if it
+ *    sanitizes to null, so a bad flag is loud rather than silently ignored);
+ *  - explicit `--agent-name ""` / whitespace-only → `clear` (remove the key);
+ *  - no flag but an existing non-empty `agentName` → keep it untouched
+ *    (non-clobber like persistAuthToken / scaffoldDefaultDomains);
+ *  - no flag, no (non-empty) existing value → do not write (global by default).
+ * Pure + exported for testability; never touches disk.
+ */
+export declare function decideAgentName(existing: unknown, flag: string | undefined): {
+    write: boolean;
+    value: string | null;
+    clear?: boolean;
+    error?: string;
+};
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -83,6 +121,7 @@ export declare function isEphemeralNpxPath(binPath: string): boolean;
 export declare function installSessionStartHook(settingsPath?: string): void;
 export declare function runInit(options?: {
     serverUrl?: string;
+    agentName?: string;
 }): Promise<void>;
 /**
  * Resolve the nightly hour (0–23, local time) for the generated schedule.

package/dist/init.js

@@ -18,9 +18,12 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERIC_DEFAULT_DOMAINS = void 0;
+exports.parseMcpListStatus = parseMcpListStatus;
 exports.parseEnvFile = parseEnvFile;
+exports.isLlmConfigured = isLlmConfigured;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
+exports.decideAgentName = decideAgentName;
 exports.scaffoldDefaultDomains = scaffoldDefaultDomains;
 exports.isEphemeralNpxPath = isEphemeralNpxPath;
 exports.installSessionStartHook = installSessionStartHook;
@@ -34,6 +37,7 @@ const node_child_process_1 = require("node:child_process");
 const node_readline_1 = require("node:readline");
 const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
+const context_store_js_1 = require("./context-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
@@ -157,6 +161,54 @@ function registerCcMcp(serverUrl) {
     }
     // Add MCP tool permissions to settings.json so users don't get prompted
     allowHicortexTools();
+    // Post-install verification (finding #5): a registration that wrote files
+    // but didn't actually take can still look "done". Best-effort confirm and,
+    // either way, tell the user exactly how to check.
+    verifyCcMcp();
+}
+/**
+ * Classify `claude mcp list` output for the hicortex entry. Pure (testable):
+ *   - "missing"    — hicortex not listed → registration didn't take
+ *   - "connected"  — listed AND reachable (✓/✔/Connected shown)
+ *   - "registered" — listed but connection not confirmed (server down / not restarted)
+ */
+function parseMcpListStatus(mcpListOutput) {
+    // `claude mcp list` prints one line per server: "hicortex: <url> (SSE) - <status>".
+    // Anchor on the "hicortex:" line prefix (not a bare word match) so a
+    // differently-named MCP like "hicortex-foo" can't be mistaken for our entry,
+    // and read status from THAT line only.
+    const line = mcpListOutput.split(/\r?\n/).find((l) => /^\s*hicortex:/.test(l));
+    if (!line)
+        return "missing";
+    return /(✓|✔|connected)/i.test(line) ? "connected" : "registered";
+}
+/**
+ * Best-effort post-install check that the hicortex MCP is actually registered
+ * (and, when reachable, connected). NEVER fails init — if the claude CLI is
+ * absent (e.g. registration went via the ~/.claude.json fallback), we can't
+ * query it, so we just tell the user how to confirm. Closes the "looks
+ * configured but isn't, with no verification" gap.
+ */
+function verifyCcMcp() {
+    let out;
+    try {
+        out = (0, node_child_process_1.execSync)("claude mcp list", { encoding: "utf-8", stdio: "pipe" });
+    }
+    catch {
+        console.log("  ℹ After restarting Claude Code, confirm with `claude mcp list` (hicortex should show ✓ Connected).");
+        return;
+    }
+    switch (parseMcpListStatus(out)) {
+        case "connected":
+            console.log("  ✓ Verified: hicortex MCP registered and connected");
+            break;
+        case "registered":
+            console.log("  ✓ Verified: hicortex MCP registered — restart Claude Code, then `claude mcp list` should show it Connected");
+            break;
+        case "missing":
+            console.log("  ⚠ Could NOT confirm the hicortex MCP registration — run `claude mcp list`; if it's absent, re-run init.");
+            break;
+    }
 }
 function allowHicortexTools() {
     let settings = {};
@@ -442,6 +494,18 @@ function mergeByKey(candidates) {
     }
     return [...seen.values()];
 }
+/**
+ * True when an LLM is already persisted and `init` must NOT re-run provider
+ * selection: a named/flat backend, a flat baseUrl+apiKey pair, OR a nested-only
+ * `models.score` (model or baseUrl). The last clause (0.13.1) stops init from
+ * walking a nested-only config back through selection and writing flat keys that
+ * a `models.score` would then silently shadow (nested > flat).
+ */
+function isLlmConfigured(config) {
+    const modelsScore = config.models?.score;
+    const hasModelsScore = Boolean(modelsScore?.model || modelsScore?.baseUrl);
+    return Boolean(config.llmBackend || (config.llmApiKey && config.llmBaseUrl) || hasModelsScore);
+}
 /**
  * Detect or ask for LLM config and persist to ~/.hicortex/config.json.
  * The daemon can't inherit shell env vars, so we persist here.
@@ -457,8 +521,8 @@ async function persistLlmConfig() {
         config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
     }
     catch { /* new file */ }
-    // Don't overwrite if LLM config already persisted
-    if (config.llmBackend || (config.llmApiKey && config.llmBaseUrl)) {
+    // Don't overwrite if LLM config already persisted (incl. a nested-only config).
+    if (isLlmConfigured(config)) {
         console.log(`  ✓ LLM config already configured`);
         return;
     }
@@ -701,6 +765,68 @@ function persistAuthToken(configPath) {
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
     return { token, generated: true };
 }
+/**
+ * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
+ * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
+ * and shares the global context (one user = one identity across machines).
+ *
+ * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
+ * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
+ * returns to global, rather than erroring as an invalid id.
+ *  - explicit `--agent-name <non-empty>` → the sanitized flag (error if it
+ *    sanitizes to null, so a bad flag is loud rather than silently ignored);
+ *  - explicit `--agent-name ""` / whitespace-only → `clear` (remove the key);
+ *  - no flag but an existing non-empty `agentName` → keep it untouched
+ *    (non-clobber like persistAuthToken / scaffoldDefaultDomains);
+ *  - no flag, no (non-empty) existing value → do not write (global by default).
+ * Pure + exported for testability; never touches disk.
+ */
+function decideAgentName(existing, flag) {
+    if (flag !== undefined) {
+        // Explicit empty / whitespace-only value → clear back to global (unset).
+        if (flag.trim() === "")
+            return { write: false, value: null, clear: true };
+        const s = (0, context_store_js_1.sanitizeAgentId)(flag);
+        if (s === null) {
+            return {
+                write: false,
+                value: null,
+                error: `Invalid --agent-name '${flag}'. Must contain letters or digits and sanitize to ^[a-z0-9][a-z0-9_-]*$ (max 64 chars). Pass --agent-name "" to clear it (global context).`,
+            };
+        }
+        return { write: true, value: s };
+    }
+    if (typeof existing === "string" && existing.trim().length > 0)
+        return { write: false, value: existing };
+    return { write: false, value: null };
+}
+/** Read config.json, set agentName, write it back. Used by the server path. */
+function writeAgentNameConfig(configPath, value) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch { /* new / unreadable → start fresh */ }
+    config.agentName = value;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+}
+/** Read config.json, delete any `agentName` key, write it back (server path). */
+function clearAgentNameConfig(configPath) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch {
+        return; /* new / unreadable → nothing to clear */
+    }
+    if (!("agentName" in config))
+        return;
+    delete config.agentName;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+}
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -994,7 +1120,7 @@ async function ask(question) {
 // ---------------------------------------------------------------------------
 async function runInit(options = {}) {
     if (options.serverUrl) {
-        await runClientInit(options.serverUrl);
+        await runClientInit(options.serverUrl, options.agentName);
         return;
     }
     console.log("Hicortex — Setup for Claude Code\n");
@@ -1076,6 +1202,25 @@ async function runInit(options = {}) {
     // Classification activates automatically once an LLM is configured; until
     // then domains sit inert (strict-skip path).
     scaffoldDefaultDomains(configPath);
+    // Per-agent context id (#179): server mode writes it ONLY when the operator
+    // passes --agent-name. Without the flag no agentName is written and the
+    // co-located CC shares the global context (global by default). Explicit flag
+    // overwrites on re-init; `--agent-name ""` clears it back to global.
+    if (options.agentName !== undefined) {
+        const decision = decideAgentName(undefined, options.agentName);
+        if (decision.error) {
+            console.error(`  ✗ ${decision.error}`);
+            process.exit(1);
+        }
+        if (decision.clear) {
+            clearAgentNameConfig(configPath);
+            console.log("  ✓ Agent name cleared — global context");
+        }
+        else if (decision.write && decision.value) {
+            writeAgentNameConfig(configPath, decision.value);
+            console.log(`  ✓ Agent name set to '${decision.value}'`);
+        }
+    }
     // Install the nightly job (capture via localhost /distill + consolidation).
     // Without it a server-mode install never captures or consolidates — the
     // daemon only serves recall + /distill. Skips if a schedule already exists.
@@ -1137,7 +1282,7 @@ async function runInit(options = {}) {
 // ---------------------------------------------------------------------------
 // Client Mode Init
 // ---------------------------------------------------------------------------
-async function runClientInit(serverUrl) {
+async function runClientInit(serverUrl, agentName) {
     console.log("Hicortex — Client Mode Setup\n");
     serverUrl = serverUrl.replace(/\/+$/, "");
     // Step 1: Verify server is reachable
@@ -1216,8 +1361,30 @@ async function runClientInit(serverUrl) {
     config.serverUrl = serverUrl;
     if (authToken)
         config.authToken = authToken;
+    // Per-agent context id (#179): explicit opt-in only. Written ONLY when
+    // --agent-name is passed; otherwise no agentName is set and the client shares
+    // the global context (global by default). Re-init keeps an existing value
+    // unless --agent-name is explicit; `--agent-name ""` clears it back to global.
+    const nameDecision = decideAgentName(config.agentName, agentName);
+    if (nameDecision.error) {
+        console.error(`  ✗ ${nameDecision.error}`);
+        process.exit(1);
+    }
+    if (nameDecision.clear) {
+        delete config.agentName;
+        console.log("  ✓ Agent name cleared — global context");
+    }
+    else if (nameDecision.write && nameDecision.value) {
+        config.agentName = nameDecision.value;
+        if (agentName && nameDecision.value !== agentName) {
+            console.log(`  ℹ Agent name sanitized to '${nameDecision.value}'`);
+        }
+    }
     saveConfig(configPath, config);
     console.log(`  ✓ Client config saved to ${configPath}`);
+    if (typeof config.agentName === "string") {
+        console.log(`  ✓ Agent name: ${config.agentName}`);
+    }
     // Step 4: Register CC MCP pointing to remote server
     if (authToken) {
         // Write directly with auth header

package/dist/lessons-context.d.ts

@@ -21,6 +21,62 @@
  * parse error) results in silent exit-0. A broken hook must never block a
  * CC session, and a broken /context fetch must never blank the whole output.
  */
+/**
+ * The GET /context response shape, shared by the CC hook and the OC plugin so
+ * their gating cannot drift. `agent`/`mode` are echoed by a 0.13 server whenever
+ * `?agent=` was sent (in EVERY mode); a pre-0.13 server omits them.
+ */
+export interface ContextResponse {
+    sections?: Record<string, string>;
+    updated_at?: string;
+    clients?: string[];
+    agent?: string;
+    mode?: string;
+}
+/**
+ * Title-case a section name for its heading: split on `-`/`_`, capitalize each
+ * word ("user" → "User", "my_notes" → "My Notes").
+ * Exported so the OC plugin (index.ts) renders the `## Context` block
+ * identically to the CC hook rather than duplicating the logic.
+ */
+export declare function titleCaseSection(name: string): string;
+/**
+ * Stable section ordering: `user` first, then `rules` (the seeded primary
+ * sections, spec §8), then every other section alphabetically. Server-side
+ * enumeration order (readdirSync) is FS-dependent, so we sort here for a
+ * deterministic injection block. Exported for reuse by the OC plugin.
+ */
+export declare function orderSectionNames(names: string[]): string[];
+/**
+ * Render the `## Context` block from a resolved section map, or null when there
+ * is nothing to inject (no sections, or every section blank after trimming).
+ * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
+ * both harnesses emit an identical block. Sections are ordered (user, rules,
+ * then alphabetical) and rendered under title-cased `###` headings.
+ */
+export declare function renderContextBlock(sections: Record<string, string>): string | null;
+/**
+ * Gate a GET /context response and render the `## Context` block, or null when
+ * nothing should be injected: `harness` not in the server-resolved `clients`,
+ * an empty/blank section set, or — when `requireAgentEcho` — a response that
+ * does not echo `agent`. The SINGLE gate used by both CC and OC so the two can
+ * never drift (the Python Hermes plugin `provider.py::_context_block` mirrors
+ * this logic — keep them in sync).
+ *
+ * `requireAgentEcho` is the old-server guard, and it is the CALLER's decision:
+ *   - OC passes `agentId !== null` — when it actually sent an id, a 0.12 server
+ *     that ignores `?agent=` (200 global, no echo) must NOT leak global context
+ *     into every persona; on a bare fetch (no id) the guard is off (amendment
+ *     A2).
+ *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
+ *     client auto-upgrades via npx BEFORE bedrock does, so during the upgrade
+ *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
+ *     global IS the operator's intended state there, and a guard would instead
+ *     blank ALL context for every CC session in that window.
+ */
+export declare function gateAndRenderContext(data: ContextResponse, harness: string, opts: {
+    requireAgentEcho: boolean;
+}): string | null;
 /**
  * Fetch context + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints