@gamaze/hicortex 0.12.1 → 0.13.1

package/dist/context-store.d.ts

@@ -34,10 +34,65 @@ export declare class InvalidSectionNameError extends Error {
     readonly names: string[];
     constructor(names: string[]);
 }
+/** Resolution mode for a given agent id (spec §3). */
+export type AgentMode = "override" | "global" | "off";
+/** Reserved subdir under <context>/ holding per-agent sections. NOT a section. */
+export declare const AGENTS_DIR = "agents";
+/**
+ * Agent ids share the section-name allowlist: they are joined into a filesystem
+ * path (`context/agents/<id>`), so this is the same security contract, not just
+ * hygiene.
+ */
+export declare const isValidAgentId: typeof isValidSectionName;
+/**
+ * Sanitize a raw identity string (hostname, configured name) into a valid agent
+ * id, or null when nothing valid remains. Lowercase → collapse invalid runs to
+ * `-` → strip leading `-`/`_` → truncate to the max length, then require the
+ * result to pass the allowlist. "MacBook-Pro.local" → "macbook-pro-local"; a
+ * string of only symbols/non-ASCII → null (caller then omits `?agent=` entirely
+ * rather than sending an id that would 400).
+ */
+export declare function sanitizeAgentId(raw: string): string | null;
+/** The identity a client sends as `?agent=`, and where it came from. */
+export interface AgentIdentity {
+    /** The id the client sends as `?agent=`, or null → no param (bare fetch). */
+    agentId: string | null;
+    source: "configured" | "unset" | "invalid-config";
+    /** The raw config value, for the configured / invalid-config cases. */
+    rawConfigured?: string;
+}
+/**
+ * Resolve an install's per-agent identity from its config (the SINGLE source of
+ * truth shared by the CC hook and `hicortex status`, so the id an install
+ * actually sends can never diverge from the id status reports):
+ *  - `config.agentName` a non-empty string that sanitizes → that id
+ *    ("configured");
+ *  - a non-empty string that sanitizes to null → null id, "invalid-config" (the
+ *    hook sends NO `?agent=`; status must say so);
+ *  - absent, or empty/whitespace-only → null id, "unset". Empty string == unset
+ *    everywhere (this is the value `init --agent-name ""` writes-then-clears to
+ *    opt back out): CC's default is NO `?agent=`, so all CC boxes for one user
+ *    share the global context — one user = one identity across machines.
+ * There is NO hostname fallback: a hostname-derived default would silently give
+ * every machine its own context, the opposite of the shared-identity default.
+ */
+export declare function resolveAgentIdentity(config: Record<string, unknown>): AgentIdentity;
+/**
+ * Normalize the raw `contextAgents` config value into a map of valid agent id →
+ * mode. An entry is kept only when its key passes isValidAgentId AND its value
+ * is one of the three modes; everything else is dropped and its key collected
+ * for a one-time boot warning (mirrors resolveContextClients).
+ */
+export declare function resolveContextAgents(raw: unknown): {
+    agents: Record<string, AgentMode>;
+    dropped: string[];
+};
 export interface ReadResult {
     sections: Record<string, string>;
     /** ISO timestamp of the latest included file's mtime, or null when none. */
     updatedAt: string | null;
+    /** Per-section file mtimeMs — needed to compute updatedAt across a merge. */
+    mtimes: Record<string, number>;
 }
 /**
  * Enumerate the context dir and return the served sections. Only regular files
@@ -97,6 +152,57 @@ export interface ResolvedContextClients {
  * hook can self-gate without its own config.
  */
 export declare function resolveContextClients(raw: unknown): ResolvedContextClients;
+/**
+ * Classify the on-disk state of `context/agents/<id>`, hardened against a
+ * symlink planted at EITHER the `agents` ROOT or the `<id>` leaf — lstat/readdir
+ * follow a symlinked intermediate path component, so checking only the leaf
+ * would let a symlinked root escape the context root entirely. BOTH must be
+ * real, non-symlink directories.
+ *  - "absent" — the root or the leaf does not exist (fresh install / no dir for
+ *    this agent). A normal, safe "no agent sections" case.
+ *  - "real"   — both are real directories → safe to read/write.
+ *  - "unsafe" — the root or leaf exists but is a symlink or non-directory →
+ *    never read/write through it (treat as no agent sections).
+ * Fail-explicit: ENOENT is the ONLY swallowed error; EACCES/EIO/ENOTDIR etc.
+ * rethrow (a permissions fault must never masquerade as "empty", matching
+ * readSections). The single source of truth for the four call sites below.
+ */
+export declare function agentDirState(contextDir: string, agentId: string): "absent" | "real" | "unsafe";
+/**
+ * Resolve the mode for a request `?agent=<id>` (spec §3):
+ *  1. config entry present → that mode;
+ *  2. else `context/agents/<id>/` present as a REAL directory (root + leaf both
+ *     real, non-symlink) → "override" (dropping in a dir is intent, no config);
+ *  3. else → "global".
+ * A symlinked/non-dir root or leaf never counts as "present" (agentDirState).
+ */
+export declare function resolveAgentMode(contextDir: string, agentId: string, contextAgents: Record<string, AgentMode>): AgentMode;
+/**
+ * Enumerate the agents the UI selector should offer: the union of allowlisted
+ * REAL directories under `context/agents/` and every configured `contextAgents`
+ * key, each mapped to its resolved mode (config wins over presence). A missing
+ * agents dir (fresh install) yields the config keys only; a symlinked/non-dir
+ * agents root is treated as "no dirs" (config keys only).
+ */
+export declare function listAgents(contextDir: string, contextAgents: Record<string, AgentMode>): Record<string, AgentMode>;
+export interface ResolvedRead {
+    sections: Record<string, string>;
+    updatedAt: string | null;
+    /** Echoed only when an agent was requested (agentId non-null). */
+    agent?: string;
+    mode?: AgentMode;
+    /** Per-section provenance, present only in override mode (feeds the UI). */
+    origins?: Record<string, "global" | "agent">;
+}
+/**
+ * Read the sections that apply to `agentId` (null → a plain global read).
+ * off → {}; global → the global set; override → per-section merge of the global
+ * set under the agent's own sections, with `updatedAt` taken across only the
+ * files that WON the merge. The agent dir is lstat-guarded immediately before
+ * reading (A1): a symlinked or non-directory `agents/<id>` contributes NO agent
+ * sections regardless of how override was selected (config or presence).
+ */
+export declare function readResolvedSections(contextDir: string, agentId: string | null, contextAgents: Record<string, AgentMode>): ResolvedRead;
 export interface HandlerResult {
     status: number;
     body: unknown;
@@ -111,10 +217,10 @@ export interface HandlerResult {
  * is served normally — the two are indistinguishable at the wire, so a
  * paramless legacy caller is covered by the migration docs, not this guard.)
  */
-export declare function handleContextGet(contextDir: string, clients: string[], query: Record<string, unknown>): HandlerResult;
+export declare function handleContextGet(contextDir: string, clients: string[], query: Record<string, unknown>, contextAgents?: Record<string, AgentMode>): HandlerResult;
 /**
  * PUT /context. Validates the body shape and section content types, then
  * delegates to writeSections (which owns the name allowlist + atomicity +
  * symlink safety). Throws are left to the adapter to turn into a 500.
  */
-export declare function handleContextPut(contextDir: string, body: unknown): HandlerResult;
+export declare function handleContextPut(contextDir: string, body: unknown, query?: Record<string, unknown>, contextAgents?: Record<string, AgentMode>): HandlerResult;

package/dist/context-store.js

@@ -20,12 +20,19 @@
  * temp-file-then-rename, and keep a one-generation `<name>.md.bak` undo.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_CONTEXT_CLIENTS = exports.CONTEXT_SIZE_WARN_BYTES = exports.InvalidSectionNameError = exports.SECTION_NAME_MAX = exports.SECTION_NAME_RE = void 0;
+exports.KNOWN_CONTEXT_CLIENTS = exports.CONTEXT_SIZE_WARN_BYTES = exports.isValidAgentId = exports.AGENTS_DIR = exports.InvalidSectionNameError = exports.SECTION_NAME_MAX = exports.SECTION_NAME_RE = void 0;
 exports.isValidSectionName = isValidSectionName;
+exports.sanitizeAgentId = sanitizeAgentId;
+exports.resolveAgentIdentity = resolveAgentIdentity;
+exports.resolveContextAgents = resolveContextAgents;
 exports.readSections = readSections;
 exports.writeSections = writeSections;
 exports.totalBytes = totalBytes;
 exports.resolveContextClients = resolveContextClients;
+exports.agentDirState = agentDirState;
+exports.resolveAgentMode = resolveAgentMode;
+exports.listAgents = listAgents;
+exports.readResolvedSections = readResolvedSections;
 exports.handleContextGet = handleContextGet;
 exports.handleContextPut = handleContextPut;
 const node_fs_1 = require("node:fs");
@@ -57,6 +64,79 @@ class InvalidSectionNameError extends Error {
     }
 }
 exports.InvalidSectionNameError = InvalidSectionNameError;
+/** Reserved subdir under <context>/ holding per-agent sections. NOT a section. */
+exports.AGENTS_DIR = "agents";
+/**
+ * Agent ids share the section-name allowlist: they are joined into a filesystem
+ * path (`context/agents/<id>`), so this is the same security contract, not just
+ * hygiene.
+ */
+exports.isValidAgentId = isValidSectionName;
+/**
+ * Sanitize a raw identity string (hostname, configured name) into a valid agent
+ * id, or null when nothing valid remains. Lowercase → collapse invalid runs to
+ * `-` → strip leading `-`/`_` → truncate to the max length, then require the
+ * result to pass the allowlist. "MacBook-Pro.local" → "macbook-pro-local"; a
+ * string of only symbols/non-ASCII → null (caller then omits `?agent=` entirely
+ * rather than sending an id that would 400).
+ */
+function sanitizeAgentId(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const cleaned = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+/, "")
+        .slice(0, exports.SECTION_NAME_MAX);
+    return isValidSectionName(cleaned) ? cleaned : null;
+}
+/**
+ * Resolve an install's per-agent identity from its config (the SINGLE source of
+ * truth shared by the CC hook and `hicortex status`, so the id an install
+ * actually sends can never diverge from the id status reports):
+ *  - `config.agentName` a non-empty string that sanitizes → that id
+ *    ("configured");
+ *  - a non-empty string that sanitizes to null → null id, "invalid-config" (the
+ *    hook sends NO `?agent=`; status must say so);
+ *  - absent, or empty/whitespace-only → null id, "unset". Empty string == unset
+ *    everywhere (this is the value `init --agent-name ""` writes-then-clears to
+ *    opt back out): CC's default is NO `?agent=`, so all CC boxes for one user
+ *    share the global context — one user = one identity across machines.
+ * There is NO hostname fallback: a hostname-derived default would silently give
+ * every machine its own context, the opposite of the shared-identity default.
+ */
+function resolveAgentIdentity(config) {
+    const value = config.agentName;
+    // Empty / whitespace-only is treated as absent, not as an invalid id.
+    const raw = typeof value === "string" && value.trim() !== "" ? value : null;
+    if (raw !== null) {
+        const s = sanitizeAgentId(raw);
+        return s ? { agentId: s, source: "configured", rawConfigured: raw }
+            : { agentId: null, source: "invalid-config", rawConfigured: raw };
+    }
+    return { agentId: null, source: "unset" };
+}
+/**
+ * Normalize the raw `contextAgents` config value into a map of valid agent id →
+ * mode. An entry is kept only when its key passes isValidAgentId AND its value
+ * is one of the three modes; everything else is dropped and its key collected
+ * for a one-time boot warning (mirrors resolveContextClients).
+ */
+function resolveContextAgents(raw) {
+    const agents = {};
+    const dropped = [];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return { agents, dropped };
+    for (const [key, value] of Object.entries(raw)) {
+        if ((0, exports.isValidAgentId)(key) && (value === "override" || value === "global" || value === "off")) {
+            agents[key] = value;
+        }
+        else {
+            dropped.push(key);
+        }
+    }
+    return { agents, dropped };
+}
 /**
  * Enumerate the context dir and return the served sections. Only regular files
  * whose basename (sans `.md`) passes the allowlist are included; symlinks are
@@ -75,13 +155,17 @@ function readSections(dir) {
         // error (EACCES, EIO, ENOTDIR) is a real fault: surface it (the route turns
         // it into a 500) rather than masquerading a permissions problem as "empty".
         if (err.code === "ENOENT")
-            return { sections: {}, updatedAt: null };
+            return { sections: {}, updatedAt: null, mtimes: {} };
         throw err;
     }
     const sections = {};
+    const mtimes = {};
     let latestMtimeMs = 0;
     for (const file of entries) {
         // Full-suffix check: only ".md" — excludes "<name>.md.bak" and temp files.
+        // A directory (e.g. the reserved `agents/` subdir) also never matches the
+        // `.md` filter, and even a dir literally named `x.md` fails the isFile()
+        // check below — so the per-agent store is skipped by the global read.
         if (!file.endsWith(".md"))
             continue;
         const name = file.slice(0, -".md".length);
@@ -104,11 +188,12 @@ function readSections(dir) {
         catch {
             continue;
         }
+        mtimes[name] = st.mtimeMs;
         if (st.mtimeMs > latestMtimeMs)
             latestMtimeMs = st.mtimeMs;
     }
     const updatedAt = Object.keys(sections).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
-    return { sections, updatedAt };
+    return { sections, updatedAt, mtimes };
 }
 // ---------------------------------------------------------------------------
 // Write
@@ -262,6 +347,141 @@ function resolveContextClients(raw) {
     return { clients: ["cc"], dropped: [] };
 }
 // ---------------------------------------------------------------------------
+// Per-agent resolution (0.13)
+// ---------------------------------------------------------------------------
+/**
+ * Classify the on-disk state of `context/agents/<id>`, hardened against a
+ * symlink planted at EITHER the `agents` ROOT or the `<id>` leaf — lstat/readdir
+ * follow a symlinked intermediate path component, so checking only the leaf
+ * would let a symlinked root escape the context root entirely. BOTH must be
+ * real, non-symlink directories.
+ *  - "absent" — the root or the leaf does not exist (fresh install / no dir for
+ *    this agent). A normal, safe "no agent sections" case.
+ *  - "real"   — both are real directories → safe to read/write.
+ *  - "unsafe" — the root or leaf exists but is a symlink or non-directory →
+ *    never read/write through it (treat as no agent sections).
+ * Fail-explicit: ENOENT is the ONLY swallowed error; EACCES/EIO/ENOTDIR etc.
+ * rethrow (a permissions fault must never masquerade as "empty", matching
+ * readSections). The single source of truth for the four call sites below.
+ */
+function agentDirState(contextDir, agentId) {
+    const root = (0, node_path_1.join)(contextDir, exports.AGENTS_DIR);
+    let rootSt;
+    try {
+        rootSt = (0, node_fs_1.lstatSync)(root);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "absent";
+        throw err;
+    }
+    if (rootSt.isSymbolicLink() || !rootSt.isDirectory())
+        return "unsafe";
+    let leafSt;
+    try {
+        leafSt = (0, node_fs_1.lstatSync)((0, node_path_1.join)(root, agentId));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "absent";
+        throw err;
+    }
+    if (leafSt.isSymbolicLink() || !leafSt.isDirectory())
+        return "unsafe";
+    return "real";
+}
+/**
+ * Resolve the mode for a request `?agent=<id>` (spec §3):
+ *  1. config entry present → that mode;
+ *  2. else `context/agents/<id>/` present as a REAL directory (root + leaf both
+ *     real, non-symlink) → "override" (dropping in a dir is intent, no config);
+ *  3. else → "global".
+ * A symlinked/non-dir root or leaf never counts as "present" (agentDirState).
+ */
+function resolveAgentMode(contextDir, agentId, contextAgents) {
+    const configured = contextAgents[agentId];
+    if (configured)
+        return configured;
+    return agentDirState(contextDir, agentId) === "real" ? "override" : "global";
+}
+/**
+ * Enumerate the agents the UI selector should offer: the union of allowlisted
+ * REAL directories under `context/agents/` and every configured `contextAgents`
+ * key, each mapped to its resolved mode (config wins over presence). A missing
+ * agents dir (fresh install) yields the config keys only; a symlinked/non-dir
+ * agents root is treated as "no dirs" (config keys only).
+ */
+function listAgents(contextDir, contextAgents) {
+    const result = {};
+    const agentsRoot = (0, node_path_1.join)(contextDir, exports.AGENTS_DIR);
+    // Guard the root itself before readdir would follow a symlinked root.
+    let rootReal = false;
+    try {
+        const st = (0, node_fs_1.lstatSync)(agentsRoot);
+        rootReal = st.isDirectory() && !st.isSymbolicLink();
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err; // fail-explicit
+    }
+    if (rootReal) {
+        for (const entry of (0, node_fs_1.readdirSync)(agentsRoot)) {
+            if (!(0, exports.isValidAgentId)(entry))
+                continue;
+            // Real leaf confirmed by the shared guard → its mode is config-or-override
+            // (config wins over presence); no second lstat via resolveAgentMode.
+            if (agentDirState(contextDir, entry) === "real") {
+                result[entry] = contextAgents[entry] ?? "override";
+            }
+        }
+    }
+    for (const id of Object.keys(contextAgents)) {
+        if (!(id in result))
+            result[id] = contextAgents[id];
+    }
+    return result;
+}
+/**
+ * Read the sections that apply to `agentId` (null → a plain global read).
+ * off → {}; global → the global set; override → per-section merge of the global
+ * set under the agent's own sections, with `updatedAt` taken across only the
+ * files that WON the merge. The agent dir is lstat-guarded immediately before
+ * reading (A1): a symlinked or non-directory `agents/<id>` contributes NO agent
+ * sections regardless of how override was selected (config or presence).
+ */
+function readResolvedSections(contextDir, agentId, contextAgents) {
+    if (agentId === null) {
+        const g = readSections(contextDir);
+        return { sections: g.sections, updatedAt: g.updatedAt };
+    }
+    const mode = resolveAgentMode(contextDir, agentId, contextAgents);
+    if (mode === "off") {
+        return { sections: {}, updatedAt: null, agent: agentId, mode };
+    }
+    const global = readSections(contextDir);
+    if (mode === "global") {
+        return { sections: global.sections, updatedAt: global.updatedAt, agent: agentId, mode };
+    }
+    // override — read the agent dir, but only if root + leaf are real dirs
+    // (agentDirState closes the config-forced-override + symlinked-root holes).
+    let agentRead = { sections: {}, updatedAt: null, mtimes: {} };
+    if (agentDirState(contextDir, agentId) === "real") {
+        agentRead = readSections((0, node_path_1.join)(contextDir, exports.AGENTS_DIR, agentId));
+    }
+    const sections = { ...global.sections, ...agentRead.sections };
+    const origins = {};
+    let latestMtimeMs = 0;
+    for (const name of Object.keys(sections)) {
+        const fromAgent = name in agentRead.sections;
+        origins[name] = fromAgent ? "agent" : "global";
+        const mt = fromAgent ? agentRead.mtimes[name] : global.mtimes[name];
+        if (mt && mt > latestMtimeMs)
+            latestMtimeMs = mt;
+    }
+    const updatedAt = Object.keys(sections).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
+    return { sections, updatedAt, agent: agentId, mode, origins };
+}
+// ---------------------------------------------------------------------------
 // HTTP-shape handlers (real logic behind GET/PUT /context)
 // ---------------------------------------------------------------------------
 //
@@ -270,6 +490,21 @@ function resolveContextClients(raw) {
 // from mcp-server.ts). mcp-server.ts wires req/res to them and nothing else.
 /** Recall query params whose presence means a stale pre-0.12 recall caller. */
 const RECALL_PARAMS = ["project", "limit", "privacy"];
+/**
+ * Extract and validate the `?agent=` query param. Absent → global (agentId
+ * null, no error). Present but not a plain string (express gives `string[]` for
+ * `?agent=a&agent=b`) or failing the allowlist → a 400 error string (never a
+ * silent fallback to global — a typo must be loud, spec §1).
+ */
+function extractAgentParam(query) {
+    if (!("agent" in query))
+        return { agentId: null };
+    const raw = query.agent;
+    if (typeof raw !== "string" || !(0, exports.isValidAgentId)(raw)) {
+        return { agentId: null, error: "Invalid 'agent' — must match ^[a-z0-9][a-z0-9_-]*$ (max 64 chars)" };
+    }
+    return { agentId: raw };
+}
 /**
  * GET /context. Stale-client tripwire first: recall moved to /recent, so
  * project/limit/privacy on this route mean a legacy recall caller — return a
@@ -278,22 +513,46 @@ const RECALL_PARAMS = ["project", "limit", "privacy"];
  * is served normally — the two are indistinguishable at the wire, so a
  * paramless legacy caller is covered by the migration docs, not this guard.)
  */
-function handleContextGet(contextDir, clients, query) {
+function handleContextGet(contextDir, clients, query, contextAgents = {}) {
     if (RECALL_PARAMS.some((p) => p in query)) {
         return {
             status: 400,
             body: { error: "recall moved to /recent — GET /context now serves the standing context layer (0.12)" },
         };
     }
-    const { sections, updatedAt } = readSections(contextDir);
-    return { status: 200, body: { sections, updated_at: updatedAt, clients } };
+    const { agentId, error } = extractAgentParam(query);
+    if (error)
+        return { status: 400, body: { error } };
+    // No agent → the plain global read plus the additive `agents` map the UI
+    // selector needs (backward compatible: existing callers ignore unknown keys).
+    if (agentId === null) {
+        const { sections, updatedAt } = readSections(contextDir);
+        return {
+            status: 200,
+            body: { sections, updated_at: updatedAt, clients, agents: listAgents(contextDir, contextAgents) },
+        };
+    }
+    const resolved = readResolvedSections(contextDir, agentId, contextAgents);
+    const body = {
+        sections: resolved.sections,
+        updated_at: resolved.updatedAt,
+        clients,
+        agent: resolved.agent,
+        mode: resolved.mode,
+    };
+    if (resolved.origins)
+        body.origins = resolved.origins;
+    return { status: 200, body };
 }
 /**
  * PUT /context. Validates the body shape and section content types, then
  * delegates to writeSections (which owns the name allowlist + atomicity +
  * symlink safety). Throws are left to the adapter to turn into a 500.
  */
-function handleContextPut(contextDir, body) {
+function handleContextPut(contextDir, body, query = {}, contextAgents = {}) {
+    const { agentId, error } = extractAgentParam(query);
+    if (error)
+        return { status: 400, body: { error } };
     const sections = body?.sections;
     if (!sections || typeof sections !== "object" || Array.isArray(sections)) {
         return { status: 400, body: { error: "Missing or invalid 'sections' object" } };
@@ -303,19 +562,52 @@ function handleContextPut(contextDir, body) {
             return { status: 400, body: { error: `Section '${name}' content must be a string` } };
         }
     }
-    try {
-        writeSections(contextDir, sections);
+    const targetDir = agentId === null ? contextDir : (0, node_path_1.join)(contextDir, exports.AGENTS_DIR, agentId);
+    if (agentId !== null) {
+        // A1 write-path guard: never write through a symlinked/non-dir root or leaf
+        // (agentDirState checks both). "absent" is fine — writeSections creates it.
+        if (agentDirState(contextDir, agentId) === "unsafe") {
+            return { status: 400, body: { error: "agent context path exists but is not a directory" } };
+        }
+        // Black-hole guard: if config FORCES off/global for this agent, sections
+        // written under agents/<id>/ could never be served (resolution ignores the
+        // dir). Reject loudly rather than accept a write that silently vanishes.
+        // No config entry → writing creates the dir ⇒ override ⇒ served (allowed).
+        const configMode = contextAgents[agentId];
+        if (configMode === "off" || configMode === "global") {
+            return {
+                status: 409,
+                body: {
+                    error: `config contextAgents['${agentId}']='${configMode}' — sections written here would never be served; ` +
+                        `set it to 'override' (or remove the entry) first`,
+                },
+            };
+        }
     }
-    catch (err) {
-        if (err instanceof InvalidSectionNameError) {
-            return { status: 400, body: { error: `Invalid section name(s): ${err.names.join(", ")}` } };
+    // Skip the write entirely when nothing is supplied: writeSections would
+    // otherwise mkdir the (agent) dir for a no-op PUT, silently flipping an
+    // agent to override via presence. Reading the resolved view still reflects
+    // current disk state.
+    if (Object.keys(sections).length > 0) {
+        try {
+            writeSections(targetDir, sections);
+        }
+        catch (err) {
+            if (err instanceof InvalidSectionNameError) {
+                return { status: 400, body: { error: `Invalid section name(s): ${err.names.join(", ")}` } };
+            }
+            throw err; // real I/O fault → adapter returns 500
         }
-        throw err; // real I/O fault → adapter returns 500
     }
-    const { sections: onDisk, updatedAt } = readSections(contextDir);
-    const bytes = totalBytes(onDisk);
+    const resolved = readResolvedSections(contextDir, agentId, contextAgents);
+    const bytes = totalBytes(resolved.sections);
     const warn = bytes > exports.CONTEXT_SIZE_WARN_BYTES
         ? `Context layer total size ${bytes} bytes exceeds ${exports.CONTEXT_SIZE_WARN_BYTES} — injected into every session; consider trimming.`
         : undefined;
-    return { status: 200, body: { ok: true, updated_at: updatedAt }, warn };
+    const respBody = { ok: true, updated_at: resolved.updatedAt };
+    if (agentId !== null) {
+        respBody.agent = resolved.agent;
+        respBody.mode = resolved.mode;
+    }
+    return { status: 200, body: respBody, warn };
 }

package/dist/distiller.d.ts

@@ -26,5 +26,31 @@ export declare function extractConversationText(messages: unknown[], redactionCo
  * 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.
+ */
+export declare function distillSession(llm: LlmClient, conversation: string, projectName: string, date: string, chunkSizeChars?: number, droppedOut?: string[]): Promise<string[]>;
+/**
+ * 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.
  */
-export declare function distillSession(llm: LlmClient, conversation: string, projectName: string, date: string, chunkSizeChars?: number): Promise<string[]>;
+export declare function hasMinimalSubstance(entry: string): boolean;