@gamaze/hicortex 0.17.5 → 0.18.0

package/dist/mcp-server.js

@@ -49,6 +49,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startServer = startServer;
+exports.formatResults = formatResults;
 const express_1 = __importDefault(require("express"));
 const node_path_1 = require("node:path");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
@@ -64,14 +65,17 @@ const storage = __importStar(require("./storage.js"));
 const graph_js_1 = require("./graph.js");
 const viz_js_1 = require("./viz.js");
 const dashboard_js_1 = require("./dashboard.js");
-const context_store_js_1 = require("./context-store.js");
+const identity_store_js_1 = require("./identity-store.js");
 const retrieval = __importStar(require("./retrieval.js"));
 const recall_registry_js_1 = require("./recall-registry.js");
 const memory_instructions_js_1 = require("./memory-instructions.js");
 const recall_index_js_1 = require("./recall-index.js");
+const type_labels_js_1 = require("./type-labels.js");
+const health_js_1 = require("./health.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
 const distiller_js_1 = require("./distiller.js");
 const dedup_js_1 = require("./dedup.js");
+const redact_js_1 = require("./redact.js");
 const init_js_1 = require("./init.js");
 // ---------------------------------------------------------------------------
 // Server state
@@ -97,13 +101,15 @@ function warnDeprecatedPrivacyParamIfPresent(query, route) {
         `Use a separate Hicortex server for isolation. (This warning fires once per process.)`);
 }
 let stateDir = "";
-// Resolved contextClients list (spec §2) — the harness names allowed to inject
-// the standing context layer. Echoed by GET /context so each hook self-gates.
-let contextClients = ["cc"];
-// Resolved contextAgents map (0.13) — agent id → mode (override/global/off).
-// Read once at boot (like contextClients); the drop-in-a-dir presence path is
+// Resolved identityClients list (spec §2) — the harness names allowed to inject
+// the standing identity layer. Echoed by GET /identity so each hook self-gates.
+// (#264: was contextClients; the legacy key is still read with a one-time
+// deprecation warning via resolveIdentityClientsConfig.)
+let identityClients = ["cc"];
+// Resolved identityAgents map (0.13) — agent id → mode (override/global/off).
+// Read once at boot (like identityClients); the drop-in-a-dir presence path is
 // per-request, so only explicit config entries need a daemon restart to apply.
-let contextAgents = {};
+let identityAgents = {};
 // Pushed-recall dedup registry (#192) + options; configured at boot.
 let recallRegistry = new recall_registry_js_1.SessionRecallRegistry();
 let recallIndexOptions = {};
@@ -464,21 +470,33 @@ async function startServer(options = {}) {
         console.warn("[hicortex] WARNING: no authToken configured — remote connections will be rejected " +
             "(localhost still works). Run `npx @gamaze/hicortex init` to generate a token.");
     }
-    // Context layer (0.12): resolve which harnesses may inject the standing
-    // context. Warn once per boot on unknown names so typos (e.g. "herms")
-    // surface instead of silently dropping.
-    const resolvedClients = (0, context_store_js_1.resolveContextClients)(savedConfig?.contextClients);
-    contextClients = resolvedClients.clients;
+    // Optional rotation-grace token (#254): config-only (no env var — rotation is
+    // an explicit, deliberate op). When set, both tokens are accepted so client
+    // reconfiguration never causes failed requests.
+    const authTokenPrevious = savedConfig?.authTokenPrevious;
+    // Identity layer (0.12; renamed from context layer in 0.18 #264): resolve
+    // which harnesses may inject the standing identity. Warn once per boot on
+    // unknown names so typos (e.g. "herms") surface instead of silently dropping.
+    const resolvedClients = (0, identity_store_js_1.resolveIdentityClientsConfig)(savedConfig);
+    identityClients = resolvedClients.clients;
+    if (resolvedClients.legacy) {
+        console.warn("[hicortex] Config uses the legacy 'contextClients' key — renamed to 'identityClients' in 0.18 (#264). " +
+            "The legacy key still works; update your config to silence this warning.");
+    }
     if (resolvedClients.dropped.length > 0) {
-        console.warn(`[hicortex] Ignoring unknown contextClients: ${resolvedClients.dropped.join(", ")} ` +
+        console.warn(`[hicortex] Ignoring unknown identityClients: ${resolvedClients.dropped.join(", ")} ` +
             `(known: cc, hermes, oc)`);
     }
-    // Per-agent context (0.13): resolve the config-declared modes. Warn once per
+    // Per-agent identity (0.13): resolve the config-declared modes. Warn once per
     // boot on dropped entries (bad key or bad mode) so typos surface. NOTE: this
-    // map is boot-time; editing contextAgents needs a daemon restart. Dropping an
+    // map is boot-time; editing identityAgents needs a daemon restart. Dropping an
     // agents/<id> dir onto disk takes effect immediately (per-request presence).
-    const resolvedAgents = (0, context_store_js_1.resolveContextAgents)(savedConfig?.contextAgents);
-    contextAgents = resolvedAgents.agents;
+    const resolvedAgents = (0, identity_store_js_1.resolveIdentityAgentsConfig)(savedConfig);
+    identityAgents = resolvedAgents.agents;
+    if (resolvedAgents.legacy) {
+        console.warn("[hicortex] Config uses the legacy 'contextAgents' key — renamed to 'identityAgents' in 0.18 (#264). " +
+            "The legacy key still works; update your config to silence this warning.");
+    }
     // #192 recall/decay alignment: decay speed + recall breadth + pushed-recall
     // knobs, ALL from config (see retrieval.ts configureRecall for the key list)
     // so calibration is a config edit + restart, never a release.
@@ -504,9 +522,19 @@ async function startServer(options = {}) {
     };
     memoryInstructionsEnabled = savedConfig?.memoryInstructions !== false;
     if (resolvedAgents.dropped.length > 0) {
-        console.warn(`[hicortex] Ignoring invalid contextAgents entries: ${resolvedAgents.dropped.join(", ")} ` +
+        console.warn(`[hicortex] Ignoring invalid identityAgents entries: ${resolvedAgents.dropped.join(", ")} ` +
             `(keys must match ^[a-z0-9][a-z0-9_-]*$; modes must be override|global|off)`);
     }
+    // #264 dir migration: rename <hicortex-home>/context/ → identity/ on boot
+    // when only the legacy dir exists. The fallback read in identity-store.ts
+    // (readSectionsWithFallback) is the safety net for a partial/no migration.
+    const idMig = (0, identity_store_js_1.migrateIdentityDir)(stateDir);
+    if (idMig.renamed) {
+        console.log(`[hicortex] Migrated identity dir: ${idMig.from} → ${idMig.to}`);
+    }
+    else if (idMig.reason && idMig.reason !== "no legacy context/ dir" && !idMig.reason.startsWith("identity/ already exists")) {
+        console.warn(`[hicortex] Identity dir migration skipped: ${idMig.reason}`);
+    }
     // Express app
     const app = (0, express_1.default)();
     // Raise the body limit — whole-session denoised transcripts exceed the 100 kB default.
@@ -551,20 +579,32 @@ async function startServer(options = {}) {
     // /dashboard has its own shell-exemption pattern. Gives the console one entry
     // point: http://<host>:8787/ → /dashboard.
     app.get("/", (_req, res) => res.redirect("/dashboard"));
-    app.use((0, viz_js_1.createAuthMiddleware)(authToken));
+    app.use((0, viz_js_1.createAuthMiddleware)(authToken, authTokenPrevious));
     // SSE transport management — each connection gets its own McpServer instance
     const transports = new Map();
-    // Health endpoint
+    // Health endpoint — PUBLIC minimal probe. Unauthenticated (the auth
+    // middleware exempts /health) and carries NO data: just liveness for load
+    // balancers, watchdogs, and anonymous probers. Tenant/install BI (memory
+    // count, link count, DB size, version, the full LLM backend string) lives
+    // on /health/detail, which is auth-gated (localhost bypasses auth so
+    // co-located tooling — `hicortex status`, nightly preflight, `init` detect
+    // — sees it without a token). #253 — spec 2026-07-27-hosted-service §6.
     app.get("/health", (_req, res) => {
+        res.json((0, health_js_1.publicHealthResponse)());
+    });
+    // Operator-only diagnostics. Goes through the standard auth middleware
+    // (not in the public-path exemption list in viz.ts); localhost bypasses
+    // auth, remote needs the bearer token. Keeps the public LB/watchdog path
+    // cheap (no COUNT(*)) and the diagnostics off the public surface.
+    app.get("/health/detail", (_req, res) => {
         const s = db ? (0, db_js_1.getStats)(db, dbPath) : { memories: 0, links: 0, db_size_bytes: 0, by_type: {} };
-        res.json({
-            status: "ok",
-            version: VERSION,
+        res.json((0, health_js_1.detailedHealthResponse)({
             memories: s.memories,
             links: s.links,
-            db_size_kb: Math.round(s.db_size_bytes / 1024),
-            llm: llmConfig ? `${llmConfig.provider}/${llmConfig.model}` : "not configured",
-        });
+            dbSizeBytes: s.db_size_bytes,
+            version: VERSION,
+            llmLabel: llmConfig ? `${llmConfig.provider}/${llmConfig.model}` : "not configured",
+        }));
     });
     // REST /lessons — return lessons + memory index for client CLAUDE.md injection
     app.get("/lessons", (_req, res) => {
@@ -599,7 +639,7 @@ async function startServer(options = {}) {
             });
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "lessons", err);
         }
     });
     // REST /ingest — accept pre-distilled memories from remote clients
@@ -644,7 +684,8 @@ async function startServer(options = {}) {
             res.status(201).json({ id, message: "Memory ingested" });
         }
         catch (err) {
-            res.status(500).json({ error: "Ingestion failed", message: err instanceof Error ? err.message : String(err) });
+            res.status(500).json({ error: "Ingestion failed" });
+            console.error(`[hicortex] /ingest: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
         }
     });
     // REST /search — semantic search over the memory store.
@@ -671,7 +712,7 @@ async function startServer(options = {}) {
             res.json({ results });
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "search", err);
         }
     });
     // REST /recall-index — pushed recall index (#192). One recall logic for all
@@ -735,7 +776,7 @@ async function startServer(options = {}) {
             res.status(r.status).json(r.body);
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "memory", err);
         }
     });
     // REST /recent — recent memories, optionally filtered by project.
@@ -754,30 +795,36 @@ async function startServer(options = {}) {
             res.json({ results });
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "recent", err);
         }
     });
     // -------------------------------------------------------------------------
-    // REST /context — standing context layer (0.12, spec 2026-07-12).
+    // REST /identity — standing identity layer (0.12, spec 2026-07-12; renamed
+    // from /context in 0.18 #264).
     //
-    // GET  → { sections, updated_at, clients } read from <hicortex-home>/context/.
+    // GET  → { sections, updated_at, clients } read from <hicortex-home>/identity/.
     // PUT  → partial upsert of named sections (allowlisted names, atomic).
     //
-    // This is NOT recall. The recall endpoint that previously held this name is
-    // now /recent (§Naming). Stale-client tripwire: old recall callers always
-    // send project/limit/privacy query params; context-layer callers never do —
-    // so those params on GET /context return a loud, self-explaining 400 instead
-    // of silently degrading recall to an empty {sections} response.
+    // This is NOT recall. The recall endpoint that previously held the /context
+    // name is now /recent (§Naming). Stale-client tripwire: old recall callers
+    // always send project/limit/privacy query params; identity-layer callers
+    // never do — so those params on GET /identity return a loud, self-explaining
+    // 400 instead of silently degrading recall to an empty {sections} response.
     //
     // Auth is the standard model (bearer; localhost bypass) via the shared
     // middleware — no special-casing here.
     // -------------------------------------------------------------------------
     // Thin adapters: all logic (tripwire, validation, allowlist, atomicity,
-    // symlink safety, size warn) lives in the pure handlers in context-store.ts,
+    // symlink safety, size warn) lives in the pure handlers in identity-store.ts,
     // which the tests exercise directly — no mirror-app drift.
-    app.get("/context", (req, res) => {
+    //
+    // #264 backcompat: GET/PUT /context remain mounted BELOW as aliases that
+    // route to the SAME handlers (Hermes/OC plugins and pre-0.18 clients keep
+    // working unchanged). Both endpoints read/write the SAME identity dir.
+    const identityDir = (0, node_path_1.join)(stateDir, "identity");
+    app.get("/identity", (req, res) => {
         try {
-            const r = (0, context_store_js_1.handleContextGet)((0, node_path_1.join)(stateDir, "context"), contextClients, req.query, contextAgents);
+            const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents);
             // #192: product-owned memory instructions ride as a synthetic read-only
             // `memory` section (config memoryInstructions !== false; agent mode
             // "off" respected inside the helper). Every harness renders it via the
@@ -788,10 +835,10 @@ async function startServer(options = {}) {
             res.status(r.status).json(r.body);
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "identity", err);
         }
     });
-    app.put("/context", (req, res) => {
+    app.put("/identity", (req, res) => {
         try {
             // Reserved product section: never writable, loud error (no silent skip).
             const putSections = req.body?.sections;
@@ -799,13 +846,46 @@ async function startServer(options = {}) {
                 res.status(400).json({ error: `Section name '${memory_instructions_js_1.MEMORY_SECTION_NAME}' is reserved for the product-owned memory instructions (config memoryInstructions to disable them)` });
                 return;
             }
-            const r = (0, context_store_js_1.handleContextPut)((0, node_path_1.join)(stateDir, "context"), req.body, req.query, contextAgents);
+            const r = (0, identity_store_js_1.handleIdentityPut)(identityDir, req.body, req.query, identityAgents);
             if (r.warn)
                 console.warn(`[hicortex] ${r.warn}`);
             res.status(r.status).json(r.body);
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "identity", err);
+        }
+    });
+    // #264 backcompat aliases: /context → /identity handlers (same dir, same
+    // clients/agents). Kept indefinitely so external callers (the Hermes plugin,
+    // pre-0.18 OC clients, operator scripts) never break. The dir is "identity"
+    // in BOTH aliases — the rename + migration is server-side; clients see no
+    // difference in behaviour, only the URL.
+    app.get("/context", (req, res) => {
+        try {
+            const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents);
+            if (r.status === 200) {
+                (0, memory_instructions_js_1.injectMemorySection)(r.body, memoryInstructionsEnabled);
+            }
+            res.status(r.status).json(r.body);
+        }
+        catch (err) {
+            (0, health_js_1.logAndSendInternalError)(res, "context", err);
+        }
+    });
+    app.put("/context", (req, res) => {
+        try {
+            const putSections = req.body?.sections;
+            if (putSections && Object.keys(putSections).some((n) => (0, memory_instructions_js_1.isReservedSectionName)(n))) {
+                res.status(400).json({ error: `Section name '${memory_instructions_js_1.MEMORY_SECTION_NAME}' is reserved for the product-owned memory instructions (config memoryInstructions to disable them)` });
+                return;
+            }
+            const r = (0, identity_store_js_1.handleIdentityPut)(identityDir, req.body, req.query, identityAgents);
+            if (r.warn)
+                console.warn(`[hicortex] ${r.warn}`);
+            res.status(r.status).json(r.body);
+        }
+        catch (err) {
+            (0, health_js_1.logAndSendInternalError)(res, "context", err);
         }
     });
     // REST /distill — canonical capture endpoint (0.9.0+).
@@ -826,17 +906,41 @@ async function startServer(options = {}) {
         }
         const { text, messages, source_agent, source_agent_id, source_domain, project, session_id, segment_id, session_date, privacy } = req.body ?? {};
         // Resolve the conversation text from either the pre-denoised string or raw messages array.
+        // `fromTextBranch` is captured once so the redaction gate below uses the SAME
+        // discriminator as the resolution (avoids re-redacting the messages-derived
+        // text in the `{text: "", messages: [...]}` edge case — harmless only because
+        // redaction is idempotent, but the comment/code must agree).
+        const fromTextBranch = typeof text === "string" && text.length > 0;
         let conversationText;
-        if (typeof text === "string" && text.length > 0) {
+        if (fromTextBranch) {
             conversationText = text;
         }
         else if (Array.isArray(messages) && messages.length > 0) {
+            // The messages branch already redacts via extractConversationText
+            // (distiller.ts), which calls redact() as its final step.
             conversationText = (0, distiller_js_1.extractConversationText)(messages);
         }
         else {
             res.status(400).json({ error: "Provide either 'text' (string) or 'messages' (array)" });
             return;
         }
+        // SERVER-SIDE REDACTION (#252): scrub secrets/PII from the text branch
+        // BEFORE it reaches the distillation LLM or storage. Client-side redaction
+        // (capture.ts) is customer-disableable; a processor cannot base a privacy
+        // claim on scrubbing the caller can switch off, and unredacted secrets
+        // would reach the LLM subprocessor. Unconditional + idempotent — safe for
+        // self-hosted too (a second pass over already-redacted text is a no-op;
+        // the [REDACTED] marker is excluded by the generic_secret pattern's
+        // negative lookahead, and format-specific patterns don't match it). The
+        // messages branch is already covered above. Disable-resistance
+        // (hostedMode) is Phase 0b.
+        if (fromTextBranch) {
+            const { text: redacted, count } = (0, redact_js_1.redact)(conversationText);
+            if (count > 0) {
+                console.log(`[hicortex] Redacted ${count} secret(s) from /distill text`);
+            }
+            conversationText = redacted;
+        }
         // Segment-exact dedup (#189): an incremental capture POST carries
         // segment_id "<start>-<end>[.pN]". Skip iff THIS exact segment's chunks are
         // already stored (keys "<sid>#<segment_id>#<i>"). This is what lets a failed
@@ -938,7 +1042,8 @@ async function startServer(options = {}) {
             });
         }
         catch (err) {
-            res.status(500).json({ error: "Distillation failed", message: err instanceof Error ? err.message : String(err) });
+            res.status(500).json({ error: "Distillation failed" });
+            console.error(`[hicortex] /distill: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
         }
     });
     // -------------------------------------------------------------------------
@@ -991,7 +1096,8 @@ async function startServer(options = {}) {
             res.json({ updated: true, id: fullId });
         }
         catch (err) {
-            res.status(500).json({ error: "Update failed", message: err instanceof Error ? err.message : String(err) });
+            res.status(500).json({ error: "Update failed" });
+            console.error(`[hicortex] /update: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
         }
     });
     // -------------------------------------------------------------------------
@@ -1019,7 +1125,8 @@ async function startServer(options = {}) {
             res.json({ deleted: true, id: fullId });
         }
         catch (err) {
-            res.status(500).json({ error: "Delete failed", message: err instanceof Error ? err.message : String(err) });
+            res.status(500).json({ error: "Delete failed" });
+            console.error(`[hicortex] /delete: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
         }
     });
     // -------------------------------------------------------------------------
@@ -1057,7 +1164,7 @@ async function startServer(options = {}) {
             res.json({ projects: rows.map((r) => ({ name: r.project, count: r.cnt })) });
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "index", err);
         }
     });
     // -------------------------------------------------------------------------
@@ -1160,7 +1267,7 @@ async function startServer(options = {}) {
             }
         }
         catch (err) {
-            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+            (0, health_js_1.logAndSendInternalError)(res, "graph", err);
         }
     });
     // -------------------------------------------------------------------------
@@ -1181,16 +1288,19 @@ async function startServer(options = {}) {
     // (static third-party code from the npm tarball, no data) — the exemption
     // lives in createAuthMiddleware next to the /viz one.
     app.get("/viz/vendor/:file", (0, viz_js_1.vizVendorHandler)());
-    // GET /context/ui — standing-context editor page (0.12, spec 2026-07-12 §5).
+    // GET /identity/ui — standing-identity editor page (0.12, spec 2026-07-12 §5;
+    // renamed from /context/ui in 0.18 #264).
     //
-    // The PRIMARY edit surface for the context layer. Self-contained HTML (inline
-    // CSS/JS, zero external requests) served from assets/context.html; builds one
-    // tab per section from GET /context and saves via PUT /context. The page
+    // The PRIMARY edit surface for the identity layer. Self-contained HTML (inline
+    // CSS/JS, zero external requests) served from assets/identity.html; builds one
+    // tab per section from GET /identity and saves via PUT /identity. The page
     // SHELL is public (exempted in createAuthMiddleware, like /viz — it carries
-    // no data); the GET/PUT /context data calls stay bearer-only (localhost
+    // no data); the GET/PUT /identity data calls stay bearer-only (localhost
     // bypass). The page collects the token client-side: ?token= URL param
     // (stripped on load) or an in-page prompt on 401, persisted in localStorage.
-    app.get("/context/ui", (0, viz_js_1.contextUiHandler)());
+    // #264 backcompat: /context/ui remains mounted below as an alias.
+    app.get("/identity/ui", (0, viz_js_1.identityUiHandler)());
+    app.get("/context/ui", (0, viz_js_1.identityUiHandler)());
     // GET /dashboard — view-only memory analytics page (#224).
     //
     // Self-contained HTML (inline CSS/JS, hand-rolled inline SVG charts, zero
@@ -1352,6 +1462,6 @@ function formatResults(results) {
     // (id + date), hicortex_get lazy-load of truncated content, hicortex_graph
     // entry points, and hicortex_update/delete self-correction (#192).
     return results
-        .map((r) => `[${r.id}] [${r.memory_type}] (${(r.created_at ?? "").slice(0, 10)}, score: ${r.score.toFixed(3)}, strength: ${r.effective_strength.toFixed(3)}) ${r.content.slice(0, 500)}`)
+        .map((r) => `[${r.id}] [${(0, type_labels_js_1.labelForType)(r.memory_type)}] (${(r.created_at ?? "").slice(0, 10)}, score: ${r.score.toFixed(3)}, strength: ${r.effective_strength.toFixed(3)}) ${r.content.slice(0, 500)}`)
         .join("\n\n");
 }

package/dist/memory-instructions.d.ts

@@ -3,19 +3,19 @@
  *
  * The instructions for HOW agents use Hicortex are shipped BY the product,
  * versioned with the server, and injected as a synthetic read-only `memory`
- * section in the GET /context response. Rationale ("enforced, built-in"):
+ * section in the GET /identity response. Rationale ("enforced, built-in"):
  *   - Harness personas (SOUL.md etc.) carry ZERO hicortex content — mechanics
  *     described there rot silently when the product changes (field evidence:
  *     stale "captured via hooks" sentences; an agent shell-spelunking its own
  *     plugin infrastructure when told "the plugin was updated").
- *   - User context files (user.md / rules.md) stay purely personal — norms the
+ *   - User identity files (user.md / rules.md) stay purely personal — norms the
  *     product depends on must not live in user-editable files (same principle
  *     as the built-in citation norm, 0.14.1).
- *   - Because every harness already renders `## Context` sections through the
+ *   - Because every harness already renders `## Identity` sections through the
  *     shared gate/render path, a synthetic section ships fleet-wide with zero
  *     client changes — including plugins that predate this feature.
  *
- * The section name is RESERVED: PUT /context rejects it, and the synthetic
+ * The section name is RESERVED: PUT /identity rejects it, and the synthetic
  * text overrides any user file of the same name (enforced means enforced).
  * Off-switch: config `memoryInstructions: false`.
  */
@@ -27,9 +27,9 @@ export declare function renderMemoryInstructions(): string;
  *  section names are lowercase by allowlist, but be safe). */
 export declare function isReservedSectionName(name: unknown): boolean;
 /**
- * Inject the synthetic section into a successful GET /context body.
+ * Inject the synthetic section into a successful GET /identity body.
  * Pure: returns the same body object with sections.memory set. Skips agent
- * mode "off" (operator explicitly silenced context for that agent) and
+ * mode "off" (operator explicitly silenced identity for that agent) and
  * non-object bodies (error shapes). Overrides a user file named memory.md.
  */
 export declare function injectMemorySection<T extends {

package/dist/memory-instructions.js

@@ -4,19 +4,19 @@
  *
  * The instructions for HOW agents use Hicortex are shipped BY the product,
  * versioned with the server, and injected as a synthetic read-only `memory`
- * section in the GET /context response. Rationale ("enforced, built-in"):
+ * section in the GET /identity response. Rationale ("enforced, built-in"):
  *   - Harness personas (SOUL.md etc.) carry ZERO hicortex content — mechanics
  *     described there rot silently when the product changes (field evidence:
  *     stale "captured via hooks" sentences; an agent shell-spelunking its own
  *     plugin infrastructure when told "the plugin was updated").
- *   - User context files (user.md / rules.md) stay purely personal — norms the
+ *   - User identity files (user.md / rules.md) stay purely personal — norms the
  *     product depends on must not live in user-editable files (same principle
  *     as the built-in citation norm, 0.14.1).
- *   - Because every harness already renders `## Context` sections through the
+ *   - Because every harness already renders `## Identity` sections through the
  *     shared gate/render path, a synthetic section ships fleet-wide with zero
  *     client changes — including plugins that predate this feature.
  *
- * The section name is RESERVED: PUT /context rejects it, and the synthetic
+ * The section name is RESERVED: PUT /identity rejects it, and the synthetic
  * text overrides any user file of the same name (enforced means enforced).
  * Off-switch: config `memoryInstructions: false`.
  */
@@ -44,9 +44,9 @@ function isReservedSectionName(name) {
     return typeof name === "string" && name.trim().toLowerCase() === exports.MEMORY_SECTION_NAME;
 }
 /**
- * Inject the synthetic section into a successful GET /context body.
+ * Inject the synthetic section into a successful GET /identity body.
  * Pure: returns the same body object with sections.memory set. Skips agent
- * mode "off" (operator explicitly silenced context for that agent) and
+ * mode "off" (operator explicitly silenced identity for that agent) and
  * non-object bodies (error shapes). Overrides a user file named memory.md.
  */
 function injectMemorySection(body, enabled) {

package/dist/nightly.js

@@ -69,6 +69,7 @@ const oc_transcript_reader_js_1 = require("./oc-transcript-reader.js");
 const features_js_1 = require("./features.js");
 const retrieval_js_1 = require("./retrieval.js");
 const state_js_1 = require("./state.js");
+const identity_store_js_1 = require("./identity-store.js");
 const capture_cursors_js_1 = require("./capture-cursors.js");
 const capture_js_1 = require("./capture.js");
 const dashboard_js_1 = require("./dashboard.js");
@@ -132,12 +133,16 @@ function computeSince(stateDir, recaptureWindowDays) {
     }
     return lastRun;
 }
-/** POST /distill transport for server mode — localhost, no auth (localhost bypasses). */
-function makeLocalPost(port) {
+/** POST /distill transport for server mode — localhost. Sends authToken so
+ *  self-capture works regardless of the localhost-bypass marker (#271 root-cause fix). */
+function makeLocalPost(port, authToken) {
     return async (body) => {
         const resp = await fetch(`http://127.0.0.1:${port}/distill`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: {
+                "Content-Type": "application/json",
+                ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+            },
             body: JSON.stringify(body),
             // Synchronous 35B distillation of a large segment can take minutes.
             signal: AbortSignal.timeout(20 * 60 * 1000),
@@ -223,6 +228,16 @@ async function runNightly(options = {}) {
     rotateNightlyLog(stateDir);
     // One-time migration of legacy state files (no-op if state.json exists)
     (0, state_js_1.migrateLegacyState)(stateDir);
+    // #264: rename <home>/context/ → identity/ on the next nightly run when only
+    // the legacy dir exists. The identity-store fallback read is the safety net
+    // for a partial/no migration. No-op when neither dir exists (fresh install).
+    const idMig = (0, identity_store_js_1.migrateIdentityDir)(stateDir);
+    if (idMig.renamed) {
+        console.log(`[hicortex] Migrated identity dir: ${idMig.from} → ${idMig.to}`);
+    }
+    else if (idMig.reason && idMig.reason !== "no legacy context/ dir" && !idMig.reason.startsWith("identity/ already exists")) {
+        console.warn(`[hicortex] Identity dir migration skipped: ${idMig.reason}`);
+    }
     // Check mode: client or server
     const savedConfig = readNightlyConfig(stateDir);
     // 0.16.8 upgrade guard: warn if ignored per-stage keys are still present.
@@ -401,7 +416,7 @@ async function runNightly(options = {}) {
                     // source_agent_id / source_domain are per-client provenance from
                     // config.json (agentId / sourceDomain) — attribution only, no filtering.
                     const result = await (0, capture_js_1.captureBatches)(batches, {
-                        post: makeLocalPost(port),
+                        post: makeLocalPost(port, savedConfig?.authToken),
                         cursorStore,
                         dryRun,
                         sourceAgentId: savedConfig?.agentId,
@@ -450,6 +465,18 @@ async function runNightly(options = {}) {
         let tokensThisRun;
         // #246: per-stage token breakdown (hoisted for the dashboard snapshot).
         let tokensByStage;
+        // #255: budget-exhaustion flag + per-stage deferred counts (hoisted for
+        // telemetry + the dashboard snapshot). Undefined when consolidation didn't
+        // run at all (capture-only / no_llm / throttled) — the optional fields are
+        // omitted so the aggregate treats absent as "not measurable".
+        let budgetExhausted;
+        let budgetDeferredByStage;
+        // #255 CR: always-on usage metric — hoisted for the dashboard snapshot so
+        // the digest renders a continuous used/max bar (consolidation
+        // completeness as a health metric), not just an amber pill at exhaustion.
+        // Undefined when consolidation didn't run; presence = a run happened.
+        let budgetCallsUsed;
+        let budgetMaxCalls;
         if (!dryRun && !captureOnly) {
             if (!llm || !llmConfig) {
                 console.error("[hicortex] consolidation skipped: no LLM configured — run npx @gamaze/hicortex init");
@@ -540,6 +567,19 @@ async function runNightly(options = {}) {
                         tokensThisRun = tokensTotal.total;
                         tokensByStage = report.budget?.tokens_by_stage;
                     }
+                    // #255: budget exhaustion — always populated when consolidation ran
+                    // (report.budget.exhausted is a boolean). The dashboard + telemetry
+                    // treat true as a quality-degradation health signal. The
+                    // ran-vs-didn't-run distinction is carried by `budgetCallsUsed`/
+                    // `budgetMaxCalls` (forwarded whenever consolidation ran), NOT by a
+                    // false `budget_exhausted` flag — the snapshot forwards
+                    // `budget_exhausted` only on exhaustion (alert state), so the
+                    // aggregate reads: calls_used present + budget_exhausted undefined
+                    // = "ran and didn't exhaust"; calls_used undefined = "didn't run".
+                    budgetExhausted = report.budget?.exhausted;
+                    budgetDeferredByStage = report.budget?.deferred_by_stage;
+                    budgetCallsUsed = report.budget?.calls_used;
+                    budgetMaxCalls = report.budget?.max_calls;
                     // #246: accrue to state.json (monthly reset + last-run estimate for
                     // the next throttle check). Written even on a failed run — a partial
                     // run that made metered calls before the failure still spent tokens,
@@ -633,6 +673,15 @@ async function runNightly(options = {}) {
                     // when consolidation didn't run or made no metered calls).
                     tokensThisRun,
                     tokensByStage,
+                    // #255 CR: always-on budget usage — undefined when consolidation
+                    // didn't run (capture-only / no_llm / throttled). Forwarded whenever
+                    // consolidation ran so the digest renders a continuous used/max bar.
+                    budgetCallsUsed,
+                    budgetMaxCalls,
+                    // #255: budget exhaustion — undefined when consolidation didn't run
+                    // (capture-only / no_llm / throttled) or didn't exhaust.
+                    budgetExhausted,
+                    budgetDeferredByStage,
                 }, memorySoftCapResolved);
             }
             catch (snapErr) {
@@ -675,6 +724,10 @@ async function runNightly(options = {}) {
                 // #246: total tokens consumed by this run's consolidation (absent on
                 // capture-only / throttled / no_llm / skipped — no metered calls).
                 tokens_this_run: tokensThisRun,
+                // #255: budget exhaustion — forwarded only when consolidation ran AND
+                // exhausted (false is omitted to keep the ping minimal; the aggregate
+                // treats absent as "not exhausted / not measurable").
+                ...(budgetExhausted ? { budget_exhausted: true } : {}),
                 sessions: batches.length,
                 ok: !hadTransientFailure,
                 shown: adoption.shown,
@@ -720,11 +773,17 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
     let reachable = false;
     for (let attempt = 1; attempt <= PREFLIGHT_ATTEMPTS; attempt++) {
         try {
+            // PUBLIC /health probe — liveness only, no auth required. Client-mode
+            // preflight runs against a REMOTE server over Tailscale, and the client
+            // has NO bearer token to hand on this path (the auth token is the
+            // server's, not the client's; /distill uses the configured authToken
+            // but the liveness check must work even before that resolves). The
+            // public /health returns only {status:"ok"} (#253), so we log
+            // reachability without a version/memory count.
             const resp = await fetch(`${serverUrl}/health`, { signal: AbortSignal.timeout(PREFLIGHT_TIMEOUT_MS) });
             if (!resp.ok)
                 throw new Error(`HTTP ${resp.status}`);
-            const data = await resp.json();
-            console.log(`[hicortex] Server OK: v${data.version}, ${data.memories} memories`);
+            console.log(`[hicortex] Server reachable at ${serverUrl}`);
             reachable = true;
             break;
         }