@gamaze/hicortex 0.11.1 → 0.12.0

package/dist/context-cli.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * context-cli — `hicortex context show|edit`, the secondary/headless edit
+ * surface for the standing context layer (spec 2026-07-12 §6). The Web UI
+ * (`/context/ui`) is primary; this exists for boxes without a browser.
+ *
+ *   hicortex context show [name]   GET /context → print all sections, or one
+ *   hicortex context edit <name>   GET section → $EDITOR → PUT if changed
+ *
+ * URL/token resolution mirrors lessons-context.ts:44-49 (client mode →
+ * config.serverUrl; server mode → http://127.0.0.1:<port>; token from
+ * config.authToken) — explicitly NOT the hardcoded 127.0.0.1:8787 of
+ * status.ts. Fails soft with a clear message + non-zero exit on any server
+ * error, distinguishing a down server from an HTTP error (esp. 404 = server
+ * too old / wrong endpoint), like the OC plugin's describeGetFailure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextCliError = void 0;
+exports.resolveContextTarget = resolveContextTarget;
+exports.loadConfig = loadConfig;
+exports.sectionChanged = sectionChanged;
+exports.getContext = getContext;
+exports.putSection = putSection;
+exports.formatAllSections = formatAllSections;
+exports.formatOneSection = formatOneSection;
+exports.runEdit = runEdit;
+exports.runContextCommand = runContextCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_child_process_1 = require("node:child_process");
+const context_store_js_1 = require("./context-store.js");
+const DEFAULT_PORT = 8787;
+const REQUEST_TIMEOUT_MS = 5000;
+/** Thrown for any expected, user-facing failure. cli.ts prints .message + exits 1. */
+class ContextCliError extends Error {
+}
+exports.ContextCliError = ContextCliError;
+/** Home dir holding config.json. HICORTEX_HOME override is a headless/test seam. */
+function hicortexHome() {
+    return process.env.HICORTEX_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+}
+/**
+ * Resolve the server URL + token from a parsed config object. Pure + exported
+ * so it is unit-testable without a live config. Follows lessons-context.ts.
+ */
+function resolveContextTarget(config) {
+    const baseUrl = config.mode === "client" && typeof config.serverUrl === "string"
+        ? config.serverUrl.replace(/\/+$/, "")
+        : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
+    const authToken = typeof config.authToken === "string" ? config.authToken : undefined;
+    return { baseUrl, authToken };
+}
+/** Read ~/.hicortex/config.json (or $HICORTEX_HOME/config.json). Missing → {}. */
+function loadConfig() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(hicortexHome(), "config.json"), "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** The Save decision: PUT only when the edited content differs. Pure + tested. */
+function sectionChanged(before, after) {
+    return before !== after;
+}
+function authHeaders(token) {
+    return token ? { Authorization: `Bearer ${token}` } : {};
+}
+/**
+ * Human-readable failure. status === null ⇒ the fetch itself threw (server
+ * unreachable). 404 is called out because it means the server predates the
+ * /context layer, not a network fault — mirrors index.ts describeGetFailure.
+ */
+function describeFailure(status, bodyError) {
+    const suffix = bodyError ? `: ${bodyError}` : "";
+    if (status === null)
+        return "server unreachable (connection refused or timed out)";
+    if (status === 404)
+        return `HTTP 404 — /context not found; the server is likely too old (needs 0.12+)${suffix}`;
+    if (status === 401)
+        return `HTTP 401 — unauthorized; check authToken in config${suffix}`;
+    return `server returned HTTP ${status}${suffix}`;
+}
+async function readBodyError(resp) {
+    try {
+        const j = (await resp.json());
+        return typeof j?.error === "string" ? j.error : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** GET /context. Throws ContextCliError with a clear message on any failure. */
+async function getContext(target) {
+    let resp;
+    try {
+        resp = await fetch(`${target.baseUrl}/context`, {
+            headers: authHeaders(target.authToken),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new ContextCliError(`GET /context failed — ${describeFailure(null)}`);
+    }
+    if (!resp.ok) {
+        throw new ContextCliError(`GET /context failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
+    }
+    return (await resp.json());
+}
+/** PUT one section. Throws ContextCliError with a clear message on any failure. */
+async function putSection(target, name, content) {
+    let resp;
+    try {
+        resp = await fetch(`${target.baseUrl}/context`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", ...authHeaders(target.authToken) },
+            body: JSON.stringify({ sections: { [name]: content } }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new ContextCliError(`PUT /context failed — ${describeFailure(null)}`);
+    }
+    if (!resp.ok) {
+        throw new ContextCliError(`PUT /context failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Pure formatters (tested directly; no I/O)
+// ---------------------------------------------------------------------------
+/** Readable rendering of every section + the resolved clients line (show, no name). */
+function formatAllSections(data) {
+    const names = Object.keys(data.sections);
+    const parts = [];
+    if (names.length === 0) {
+        parts.push("(no context sections)");
+    }
+    else {
+        for (const name of names) {
+            const body = data.sections[name];
+            parts.push(`## ${name}`, "", body.endsWith("\n") ? body.trimEnd() : body, "");
+        }
+    }
+    parts.push(`clients: ${data.clients.join(", ") || "(none)"}`);
+    return parts.join("\n");
+}
+/** Raw markdown for one section (show <name>), or null if it does not exist. */
+function formatOneSection(data, name) {
+    if (!(name in data.sections))
+        return null;
+    return data.sections[name];
+}
+// ---------------------------------------------------------------------------
+// Editor seam
+// ---------------------------------------------------------------------------
+/** Ordered editor candidates: $EDITOR → nano → vi (spec §6). */
+function candidateEditors() {
+    const list = [];
+    const env = process.env.EDITOR?.trim();
+    if (env)
+        list.push(env);
+    list.push("nano", "vi");
+    return list;
+}
+const defaultSpawn = (file) => {
+    for (const ed of candidateEditors()) {
+        const [cmd, ...prefixArgs] = ed.split(/\s+/);
+        const r = (0, node_child_process_1.spawnSync)(cmd, [...prefixArgs, file], { stdio: "inherit" });
+        if (r.error) {
+            if (r.error.code === "ENOENT")
+                continue; // not installed → next
+            return false; // spawned but failed for another reason
+        }
+        return true; // editor ran (any exit code — e.g. `:q` in vi)
+    }
+    return false;
+};
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+async function runShow(name) {
+    const data = await getContext(resolveContextTarget(loadConfig()));
+    if (name) {
+        const body = formatOneSection(data, name);
+        if (body === null) {
+            const avail = Object.keys(data.sections).join(", ") || "(none)";
+            process.stderr.write(`Section '${name}' not found. Available: ${avail}\n`);
+            process.exit(1);
+        }
+        process.stdout.write(body.endsWith("\n") ? body : body + "\n");
+        return;
+    }
+    process.stdout.write(formatAllSections(data) + "\n");
+}
+/**
+ * `edit <name>`: validate name (fast-fail; the server enforces too) → fetch
+ * current content → $EDITOR on a temp file → PUT only if changed. Temp file is
+ * always cleaned up. `spawn` is injectable for tests.
+ */
+async function runEdit(name, spawn = defaultSpawn) {
+    if (!(0, context_store_js_1.isValidSectionName)(name)) {
+        throw new ContextCliError(`Invalid section name '${name}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${context_store_js_1.SECTION_NAME_MAX} chars).`);
+    }
+    const target = resolveContextTarget(loadConfig());
+    const data = await getContext(target);
+    const before = data.sections[name] ?? "";
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-ctx-"));
+    const file = (0, node_path_1.join)(dir, `${name}.md`);
+    try {
+        (0, node_fs_1.writeFileSync)(file, before, "utf-8");
+        const ran = spawn(file);
+        if (!ran) {
+            throw new ContextCliError("No editor available. Set $EDITOR, or install nano or vi.");
+        }
+        const after = (0, node_fs_1.readFileSync)(file, "utf-8");
+        if (!sectionChanged(before, after)) {
+            process.stdout.write("no changes\n");
+            return;
+        }
+        await putSection(target, name, after);
+        process.stdout.write(`Saved section '${name}'.\n`);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+    }
+}
+/** Dispatch for `hicortex context <sub>`. Throws ContextCliError on bad usage/failure. */
+async function runContextCommand(args) {
+    const sub = args[0];
+    switch (sub) {
+        case "show":
+            await runShow(args[1]);
+            return;
+        case "edit":
+            if (!args[1])
+                throw new ContextCliError("Usage: hicortex context edit <name>");
+            await runEdit(args[1]);
+            return;
+        default:
+            throw new ContextCliError("Usage: hicortex context <show [name] | edit <name>>");
+    }
+}

package/dist/context-store.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Context layer (L2) — file-backed storage (0.12.0, spec 2026-07-12).
+ *
+ * The context layer is hand-edited Markdown ("who you are + how to work") stored
+ * as plain files in `<hicortex-home>/context/*.md` — one file per section, one
+ * Web UI tab. It lives OUTSIDE the memories table: never distilled, scored,
+ * decayed, or pruned. As plain files this guarantee is structural — no code in
+ * consolidate.ts / distiller.ts references this directory.
+ *
+ * This module is pure file-layer logic (no express) so it is unit-testable and
+ * reusable by the CLI. The daemon resolves `<hicortex-home>` exactly as it
+ * resolves the DB dir (dirname of the resolved DB path) and passes the context
+ * dir in — nothing here hardcodes `~`.
+ *
+ * Security contract (spec §1): client-supplied section names are NEVER joined
+ * into a filesystem path except after passing the strict allowlist; the server
+ * itself appends `.md`. Reads skip symlinks (lstat, not stat). Writes validate
+ * ALL names before touching the disk (atomic request semantics), go via
+ * temp-file-then-rename, and keep a one-generation `<name>.md.bak` undo.
+ */
+/** A valid section name: lowercase alnum start, then alnum / `_` / `-`. */
+export declare const SECTION_NAME_RE: RegExp;
+/** Max section-name length (excludes the server-appended `.md`). */
+export declare const SECTION_NAME_MAX = 64;
+/**
+ * True when `name` is a valid section name — matches the allowlist and is
+ * 1..64 chars. Rejects traversal (`../x`, `a/b`), uppercase, leading `_`/`-`,
+ * empty, and over-long names. The server appends `.md`; the name is never
+ * otherwise joined into a path.
+ */
+export declare function isValidSectionName(name: string): boolean;
+/** Thrown by writeSections when any supplied name fails the allowlist. */
+export declare class InvalidSectionNameError extends Error {
+    readonly names: string[];
+    constructor(names: string[]);
+}
+export interface ReadResult {
+    sections: Record<string, string>;
+    /** ISO timestamp of the latest included file's mtime, or null when none. */
+    updatedAt: string | null;
+}
+/**
+ * Enumerate the context dir and return the served sections. Only regular files
+ * whose basename (sans `.md`) passes the allowlist are included; symlinks are
+ * skipped (lstat). `<name>.md.bak` and temp files never match the `*.md` filter.
+ *
+ * Fail-soft: a missing dir (fresh install) returns `{ sections: {}, updatedAt:
+ * null }` and NEVER creates the dir or throws.
+ */
+export declare function readSections(dir: string): ReadResult;
+/**
+ * Partial upsert of the named sections. Contract (spec §1):
+ *  - Validate ALL names first; any invalid → throw InvalidSectionNameError and
+ *    write NOTHING (atomic request semantics).
+ *  - Only the named sections are touched; omitted sections stay untouched
+ *    (omission is not deletion — deletion is filesystem-only).
+ *  - Each write goes temp-file-then-rename in the same dir (no half-applied
+ *    reads on GET-during-PUT).
+ *  - After committing a write over an EXISTING file, the prior content is kept
+ *    as `<name>.md.bak` (one-generation undo; `.bak` never matches the read
+ *    `*.md` filter).
+ *  - Empty-string content is allowed (clears the file).
+ * Creates the dir (recursive) on first write.
+ *
+ * Failure semantics:
+ *  - Invalid names → nothing written (validated up front).
+ *  - All new content is written to temp files FIRST (phase A); if any temp
+ *    write fails (disk full / EIO), nothing is committed and temps are cleaned
+ *    up. This makes the common failure atomic. A rename failure during the
+ *    commit loop (phase B) — rare for a same-dir rename — can still leave
+ *    earlier sections of a MULTI-section write committed; single-section PUT
+ *    (the norm from the UI/CLI) is fully all-or-nothing.
+ *  - The `.bak` is written via its own temp+rename and only AFTER the main
+ *    rename commits, so (a) a failed write never destroys the existing undo
+ *    generation and (b) a symlink planted at the `.bak` path is replaced, never
+ *    written THROUGH (never-follow-symlinks-on-write).
+ */
+export declare function writeSections(dir: string, sections: Record<string, string>): void;
+/** Total UTF-8 byte size of all sections (used for the >16 KB warn). */
+export declare function totalBytes(sections: Record<string, string>): number;
+/** Warn threshold: this layer bypasses token budgeting and injects every session. */
+export declare const CONTEXT_SIZE_WARN_BYTES = 16384;
+/** Harness names that may inject the context layer. */
+export declare const KNOWN_CONTEXT_CLIENTS: readonly ["cc", "hermes", "oc"];
+export interface ResolvedContextClients {
+    /** The resolved, de-duped list of known client names. */
+    clients: string[];
+    /** Unknown names dropped from an array value (for a one-time boot warning). */
+    dropped: string[];
+}
+/**
+ * Normalize the raw `contextClients` config value (spec §2):
+ *  - `"all"` (any case)      → ["cc","hermes","oc"]
+ *  - array                   → lowercase, keep known names (de-duped), collect dropped unknowns
+ *  - missing / non-array-non-"all" → default ["cc"]
+ * The resolved list is echoed by GET /context as `clients` so each harness's
+ * hook can self-gate without its own config.
+ */
+export declare function resolveContextClients(raw: unknown): ResolvedContextClients;
+export interface HandlerResult {
+    status: number;
+    body: unknown;
+    /** When set, the adapter should console.warn this (size warning). */
+    warn?: string;
+}
+/**
+ * GET /context. Stale-client tripwire first: recall moved to /recent, so
+ * project/limit/privacy on this route mean a legacy recall caller — return a
+ * loud 400 rather than silently degrading to an empty context-layer response.
+ * (A bare GET /context with no params is the legitimate context-layer read and
+ * 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;
+/**
+ * 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;

package/dist/context-store.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * Context layer (L2) — file-backed storage (0.12.0, spec 2026-07-12).
+ *
+ * The context layer is hand-edited Markdown ("who you are + how to work") stored
+ * as plain files in `<hicortex-home>/context/*.md` — one file per section, one
+ * Web UI tab. It lives OUTSIDE the memories table: never distilled, scored,
+ * decayed, or pruned. As plain files this guarantee is structural — no code in
+ * consolidate.ts / distiller.ts references this directory.
+ *
+ * This module is pure file-layer logic (no express) so it is unit-testable and
+ * reusable by the CLI. The daemon resolves `<hicortex-home>` exactly as it
+ * resolves the DB dir (dirname of the resolved DB path) and passes the context
+ * dir in — nothing here hardcodes `~`.
+ *
+ * Security contract (spec §1): client-supplied section names are NEVER joined
+ * into a filesystem path except after passing the strict allowlist; the server
+ * itself appends `.md`. Reads skip symlinks (lstat, not stat). Writes validate
+ * ALL names before touching the disk (atomic request semantics), go via
+ * 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.isValidSectionName = isValidSectionName;
+exports.readSections = readSections;
+exports.writeSections = writeSections;
+exports.totalBytes = totalBytes;
+exports.resolveContextClients = resolveContextClients;
+exports.handleContextGet = handleContextGet;
+exports.handleContextPut = handleContextPut;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+// ---------------------------------------------------------------------------
+// Section-name allowlist (security contract)
+// ---------------------------------------------------------------------------
+/** A valid section name: lowercase alnum start, then alnum / `_` / `-`. */
+exports.SECTION_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/** Max section-name length (excludes the server-appended `.md`). */
+exports.SECTION_NAME_MAX = 64;
+/**
+ * True when `name` is a valid section name — matches the allowlist and is
+ * 1..64 chars. Rejects traversal (`../x`, `a/b`), uppercase, leading `_`/`-`,
+ * empty, and over-long names. The server appends `.md`; the name is never
+ * otherwise joined into a path.
+ */
+function isValidSectionName(name) {
+    return typeof name === "string" && name.length >= 1 && name.length <= exports.SECTION_NAME_MAX && exports.SECTION_NAME_RE.test(name);
+}
+/** Thrown by writeSections when any supplied name fails the allowlist. */
+class InvalidSectionNameError extends Error {
+    names;
+    constructor(names) {
+        super(`Invalid section name(s): ${names.join(", ")}`);
+        this.names = names;
+        this.name = "InvalidSectionNameError";
+    }
+}
+exports.InvalidSectionNameError = InvalidSectionNameError;
+/**
+ * Enumerate the context dir and return the served sections. Only regular files
+ * whose basename (sans `.md`) passes the allowlist are included; symlinks are
+ * skipped (lstat). `<name>.md.bak` and temp files never match the `*.md` filter.
+ *
+ * Fail-soft: a missing dir (fresh install) returns `{ sections: {}, updatedAt:
+ * null }` and NEVER creates the dir or throws.
+ */
+function readSections(dir) {
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch (err) {
+        // ENOENT = fresh install (dir not created yet) → fail-soft empty. Any other
+        // 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 };
+        throw err;
+    }
+    const sections = {};
+    let latestMtimeMs = 0;
+    for (const file of entries) {
+        // Full-suffix check: only ".md" — excludes "<name>.md.bak" and temp files.
+        if (!file.endsWith(".md"))
+            continue;
+        const name = file.slice(0, -".md".length);
+        if (!isValidSectionName(name))
+            continue;
+        const full = (0, node_path_1.join)(dir, file);
+        let st;
+        try {
+            // lstat (not stat): a symlink must be skipped, not followed.
+            st = (0, node_fs_1.lstatSync)(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isSymbolicLink() || !st.isFile())
+            continue;
+        try {
+            sections[name] = (0, node_fs_1.readFileSync)(full, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (st.mtimeMs > latestMtimeMs)
+            latestMtimeMs = st.mtimeMs;
+    }
+    const updatedAt = Object.keys(sections).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
+    return { sections, updatedAt };
+}
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+/**
+ * Partial upsert of the named sections. Contract (spec §1):
+ *  - Validate ALL names first; any invalid → throw InvalidSectionNameError and
+ *    write NOTHING (atomic request semantics).
+ *  - Only the named sections are touched; omitted sections stay untouched
+ *    (omission is not deletion — deletion is filesystem-only).
+ *  - Each write goes temp-file-then-rename in the same dir (no half-applied
+ *    reads on GET-during-PUT).
+ *  - After committing a write over an EXISTING file, the prior content is kept
+ *    as `<name>.md.bak` (one-generation undo; `.bak` never matches the read
+ *    `*.md` filter).
+ *  - Empty-string content is allowed (clears the file).
+ * Creates the dir (recursive) on first write.
+ *
+ * Failure semantics:
+ *  - Invalid names → nothing written (validated up front).
+ *  - All new content is written to temp files FIRST (phase A); if any temp
+ *    write fails (disk full / EIO), nothing is committed and temps are cleaned
+ *    up. This makes the common failure atomic. A rename failure during the
+ *    commit loop (phase B) — rare for a same-dir rename — can still leave
+ *    earlier sections of a MULTI-section write committed; single-section PUT
+ *    (the norm from the UI/CLI) is fully all-or-nothing.
+ *  - The `.bak` is written via its own temp+rename and only AFTER the main
+ *    rename commits, so (a) a failed write never destroys the existing undo
+ *    generation and (b) a symlink planted at the `.bak` path is replaced, never
+ *    written THROUGH (never-follow-symlinks-on-write).
+ */
+function writeSections(dir, sections) {
+    const invalid = Object.keys(sections).filter((n) => !isValidSectionName(n));
+    if (invalid.length > 0)
+        throw new InvalidSectionNameError(invalid);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const suffix = `${process.pid}-${(0, node_crypto_1.randomBytes)(6).toString("hex")}`;
+    const staged = [];
+    try {
+        // Phase A — write every section to a temp file. The temp name never ends
+        // in exactly ".md", so a leftover temp is invisible to readSections. If any
+        // write throws, the finally block cleans up and NOTHING is committed.
+        for (const [name, content] of Object.entries(sections)) {
+            const target = (0, node_path_1.join)(dir, `${name}.md`);
+            const tmp = (0, node_path_1.join)(dir, `.${name}.md.tmp-${suffix}`);
+            (0, node_fs_1.writeFileSync)(tmp, content, "utf-8");
+            staged.push({ name, tmp, target });
+        }
+        // Phase B — commit. Capture prior content BEFORE the rename, back it up
+        // only AFTER the rename succeeds.
+        for (const { name, tmp, target } of staged) {
+            let prior = null;
+            try {
+                const st = (0, node_fs_1.lstatSync)(target);
+                // Real file → keep its content for the undo. A symlink is neither
+                // followed nor read through: renameSync below atomically replaces the
+                // symlink itself with our regular file, neutralizing a planted link.
+                if (st.isFile() && !st.isSymbolicLink())
+                    prior = (0, node_fs_1.readFileSync)(target);
+            }
+            catch {
+                // no prior file
+            }
+            (0, node_fs_1.renameSync)(tmp, target); // commit (atomic; replaces a symlink, never follows it)
+            if (prior !== null) {
+                // Update the one-generation undo via temp+rename so we never write
+                // through a planted symlink at the .bak path. Best-effort: a backup
+                // failure must not fail the (already committed) write.
+                const bak = (0, node_path_1.join)(dir, `${name}.md.bak`);
+                const bakTmp = (0, node_path_1.join)(dir, `.${name}.md.bak.tmp-${suffix}`);
+                try {
+                    (0, node_fs_1.writeFileSync)(bakTmp, prior);
+                    (0, node_fs_1.renameSync)(bakTmp, bak);
+                }
+                catch {
+                    try {
+                        if ((0, node_fs_1.existsSync)(bakTmp))
+                            (0, node_fs_1.unlinkSync)(bakTmp);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+    }
+    finally {
+        // Remove any temp that never got renamed into place (phase-A/B failure).
+        for (const { tmp } of staged) {
+            try {
+                if ((0, node_fs_1.existsSync)(tmp))
+                    (0, node_fs_1.unlinkSync)(tmp);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** Total UTF-8 byte size of all sections (used for the >16 KB warn). */
+function totalBytes(sections) {
+    let total = 0;
+    for (const content of Object.values(sections))
+        total += Buffer.byteLength(content, "utf-8");
+    return total;
+}
+/** Warn threshold: this layer bypasses token budgeting and injects every session. */
+exports.CONTEXT_SIZE_WARN_BYTES = 16_384;
+// ---------------------------------------------------------------------------
+// Config — contextClients normalization
+// ---------------------------------------------------------------------------
+/** Harness names that may inject the context layer. */
+exports.KNOWN_CONTEXT_CLIENTS = ["cc", "hermes", "oc"];
+/**
+ * Normalize the raw `contextClients` config value (spec §2):
+ *  - `"all"` (any case)      → ["cc","hermes","oc"]
+ *  - array                   → lowercase, keep known names (de-duped), collect dropped unknowns
+ *  - missing / non-array-non-"all" → default ["cc"]
+ * The resolved list is echoed by GET /context as `clients` so each harness's
+ * hook can self-gate without its own config.
+ */
+function resolveContextClients(raw) {
+    if (typeof raw === "string" && raw.toLowerCase() === "all") {
+        return { clients: [...exports.KNOWN_CONTEXT_CLIENTS], dropped: [] };
+    }
+    if (Array.isArray(raw)) {
+        const known = new Set(exports.KNOWN_CONTEXT_CLIENTS);
+        const clients = [];
+        const dropped = [];
+        for (const item of raw) {
+            if (typeof item !== "string") {
+                dropped.push(String(item));
+                continue;
+            }
+            const lower = item.toLowerCase();
+            // "all" as an array member expands to every known client — the array is
+            // the natural form of the documented "all" value, so ["all"] must mean
+            // all, not an empty list.
+            if (lower === "all") {
+                for (const k of exports.KNOWN_CONTEXT_CLIENTS)
+                    if (!clients.includes(k))
+                        clients.push(k);
+                continue;
+            }
+            if (known.has(lower)) {
+                if (!clients.includes(lower))
+                    clients.push(lower);
+            }
+            else {
+                dropped.push(item);
+            }
+        }
+        return { clients, dropped };
+    }
+    return { clients: ["cc"], dropped: [] };
+}
+// ---------------------------------------------------------------------------
+// HTTP-shape handlers (real logic behind GET/PUT /context)
+// ---------------------------------------------------------------------------
+//
+// These are the actual request handlers, expressed as pure functions over
+// plain inputs so they are unit-tested directly (no mirror app that can drift
+// 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"];
+/**
+ * GET /context. Stale-client tripwire first: recall moved to /recent, so
+ * project/limit/privacy on this route mean a legacy recall caller — return a
+ * loud 400 rather than silently degrading to an empty context-layer response.
+ * (A bare GET /context with no params is the legitimate context-layer read and
+ * 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) {
+    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 } };
+}
+/**
+ * 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) {
+    const sections = body?.sections;
+    if (!sections || typeof sections !== "object" || Array.isArray(sections)) {
+        return { status: 400, body: { error: "Missing or invalid 'sections' object" } };
+    }
+    for (const [name, content] of Object.entries(sections)) {
+        if (typeof content !== "string") {
+            return { status: 400, body: { error: `Section '${name}' content must be a string` } };
+        }
+    }
+    try {
+        writeSections(contextDir, 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
+    }
+    const { sections: onDisk, updatedAt } = readSections(contextDir);
+    const bytes = totalBytes(onDisk);
+    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 };
+}