@gamaze/hicortex 0.17.6 → 0.18.1

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

package/dist/paths.js

@@ -8,7 +8,7 @@ exports.hicortexHome = hicortexHome;
  * HICORTEX_DB_PATH convention in db.ts); otherwise defaults to ~/.hicortex.
  * Every module that needs the home dir routes through here, so the override
  * behaves consistently across all commands instead of being honored by some
- * (context-cli, lessons-context) and hardcoded away by others.
+ * (identity-cli, learnings-identity) and hardcoded away by others.
  */
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");

package/dist/recall-hook-cli.d.ts

@@ -8,7 +8,7 @@
  *   - SessionStart (startup/resume/clear/compact): POST a reset so the
  *     server's per-session shown-set matches the fresh context window.
  *
- * Fail-soft like lessons-context: ANY failure (no config, timeout, non-2xx,
+ * Fail-soft like learnings-identity: ANY failure (no config, timeout, non-2xx,
  * parse error) prints nothing and exits 0 — a broken hook must never block or
  * slow a CC session beyond the fetch timeout (1000 ms, owner-set).
  */

package/dist/recall-hook-cli.js

@@ -9,14 +9,14 @@
  *   - SessionStart (startup/resume/clear/compact): POST a reset so the
  *     server's per-session shown-set matches the fresh context window.
  *
- * Fail-soft like lessons-context: ANY failure (no config, timeout, non-2xx,
+ * Fail-soft like learnings-identity: ANY failure (no config, timeout, non-2xx,
  * parse error) prints nothing and exits 0 — a broken hook must never block or
  * slow a CC session beyond the fetch timeout (1000 ms, owner-set).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildHookRequest = buildHookRequest;
 exports.runRecallHook = runRecallHook;
-const lessons_context_js_1 = require("./lessons-context.js");
+const learnings_identity_js_1 = require("./learnings-identity.js");
 const node_path_1 = require("node:path");
 const FETCH_TIMEOUT_MS = 1000;
 /** Read all of stdin (CC pipes the hook payload JSON). */
@@ -51,7 +51,7 @@ function buildHookRequest(payload, cwd = process.cwd()) {
     return { session_id: sessionId, prompt, project: (0, node_path_1.basename)(cwd) };
 }
 async function runRecallHook() {
-    const cfg = (0, lessons_context_js_1.resolveConfig)();
+    const cfg = (0, learnings_identity_js_1.resolveConfig)();
     if (!cfg)
         return;
     let payload;

package/dist/recall-index.js

@@ -62,6 +62,7 @@ exports.handleRecallIndex = handleRecallIndex;
 exports.handleMemoryGet = handleMemoryGet;
 exports.formatMemoryGetText = formatMemoryGetText;
 const storage = __importStar(require("./storage.js"));
+const type_labels_js_1 = require("./type-labels.js");
 /** Relevance-gate floor for vector-only candidates (config `recallMinSimilarity`).
  *  0.62 (was 0.55; raised 2026-08-03 on the fine-grain floor sweep — see the
  *  minSimilarity doc above). */
@@ -116,7 +117,7 @@ function formatIndexLine(r, maxLen = DEFAULT_TITLE_CHARS) {
         formatDate(r.created_at),
         r.domain ?? r.project ?? undefined,
         r.source_agent ?? undefined,
-        r.memory_type,
+        (0, type_labels_js_1.labelForType)(r.memory_type),
     ]
         .filter(Boolean)
         .join(", ");
@@ -281,7 +282,9 @@ function formatMemoryGetText(db, query) {
     const mem = r.body.memory;
     const citation = r.body.citation; // carries FETCHED (#204)
     const date = (mem.created_at ?? "").slice(0, 10);
-    const header = `[memory ${mem.id} | ${mem.memory_type ?? "episode"} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
+    // #264 WS2: render the human-term label (Knowledge/Experience/...), not the
+    // internal enum, in the citation header shown to the agent/user.
+    const header = `[memory ${mem.id} | ${(0, type_labels_js_1.labelForType)(mem.memory_type ?? "episode")} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
         `Cite as ${citation} where this shapes your answer; it may be stale — newer memories supersede older.`;
     return { status: 200, text: `${header}\n\n${mem.content ?? ""}` };
 }

package/dist/status.d.ts

@@ -4,9 +4,9 @@
 /**
  * The value shown after "Agent name:" in `hicortex status` (#179, A3). Reports
  * EXACTLY what the CC hook resolves (shared `resolveAgentIdentity`), so the
- * operator never keys `contextAgents`/`agents/<id>/` on an id the install does
+ * operator never keys `identityAgents`/`agents/<id>/` on an id the install does
  * not actually send. Unset → the install sends no `?agent=` and shares the
- * global context (CC default). A configured-but-unsanitizable value is called
+ * global identity (CC default). A configured-but-unsanitizable value is called
  * out as invalid (the hook sends none) rather than silently accepted.
  */
 export declare function statusAgentLine(config: Record<string, unknown>): string;

package/dist/status.js

@@ -13,27 +13,27 @@ const node_child_process_1 = require("node:child_process");
 const db_js_1 = require("./db.js");
 const features_js_1 = require("./features.js");
 const state_js_1 = require("./state.js");
-const context_store_js_1 = require("./context-store.js");
+const identity_store_js_1 = require("./identity-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
 /**
  * The value shown after "Agent name:" in `hicortex status` (#179, A3). Reports
  * EXACTLY what the CC hook resolves (shared `resolveAgentIdentity`), so the
- * operator never keys `contextAgents`/`agents/<id>/` on an id the install does
+ * operator never keys `identityAgents`/`agents/<id>/` on an id the install does
  * not actually send. Unset → the install sends no `?agent=` and shares the
- * global context (CC default). A configured-but-unsanitizable value is called
+ * global identity (CC default). A configured-but-unsanitizable value is called
  * out as invalid (the hook sends none) rather than silently accepted.
  */
 function statusAgentLine(config) {
-    const id = (0, context_store_js_1.resolveAgentIdentity)(config);
+    const id = (0, identity_store_js_1.resolveAgentIdentity)(config);
     switch (id.source) {
         case "configured":
             return id.agentId;
         case "invalid-config":
             return `(invalid configured value "${id.rawConfigured}" — fix config.agentName; hook sends none)`;
         default: // unset
-            return "(not set — global context)";
+            return "(not set — global identity)";
     }
 }
 async function runStatus() {
@@ -87,8 +87,8 @@ async function runStatus() {
     else if (!isClientMode && !savedAuthToken) {
         console.log(`Auth token:   not configured (run: npx @gamaze/hicortex init)`);
     }
-    // Per-agent context id (#179) — the id this install sends as ?agent= and the
-    // key operators use for contextAgents / agents/<id>/ dirs.
+    // Per-agent identity id (#179) — the id this install sends as ?agent= and the
+    // key operators use for identityAgents / agents/<id>/ dirs.
     console.log(`Agent name:   ${statusAgentLine(parsedConfig)}`);
     console.log();
     // Adapters
@@ -119,11 +119,13 @@ async function runStatus() {
     catch { /* no CC settings */ }
     console.log(`  CC MCP:     ${ccRegistered ? `registered → ${ccUrl}` : "not registered"}`);
     console.log();
-    // Server status
+    // Server status. /health/detail carries the diagnostics (version, memories,
+    // llm) — /health itself is the public minimal {status:"ok"} probe (#253).
+    // localhost bypasses auth, so on-box `hicortex status` gets the fields.
     console.log("Server:");
     let serverRunning = false;
     try {
-        const resp = await fetch("http://127.0.0.1:8787/health", {
+        const resp = await fetch("http://127.0.0.1:8787/health/detail", {
             signal: AbortSignal.timeout(2000),
         });
         if (resp.ok) {

package/dist/telemetry.d.ts

@@ -106,6 +106,16 @@ export interface TelemetryPayload {
      * wire (that lives in the dashboard snapshot, not the telemetry ping).
      */
     tokens_this_run?: number;
+    /**
+     * True when the per-tenant consolidation budget (`consolidateMaxLlmCalls`)
+     * was exhausted this run (#255) — LLM-bound stages deferred remaining work.
+     * A quality-degradation signal concentrated on heavy users; absent on a
+     * pre-#255 ping, a capture-only/no-LLM/throttled/skipped run, or when the
+     * budget was NOT exhausted (additive optional — the aggregate treats absent
+     * as "no exhaustion / not measurable"). Per-stage deferred counts live in
+     * the dashboard snapshot, not on the wire (mirrors `tokens_this_run`).
+     */
+    budget_exhausted?: boolean;
 }
 /**
  * Check if telemetry is enabled. Disabled by:

package/dist/type-classify.js

@@ -45,6 +45,7 @@ const node_path_1 = require("node:path");
 const db_js_1 = require("./db.js");
 const state_js_1 = require("./state.js");
 const llm_js_1 = require("./llm.js");
+const type_labels_js_1 = require("./type-labels.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 /** Max chars of memory content fed to the classify prompt. */
 const CLASSIFY_CONTENT_MAX_CHARS = 1500;
@@ -293,7 +294,9 @@ async function runClassifyTypes(options = {}) {
             .all();
         for (const c of counts)
             report.byType[c.memory_type] = c.cnt;
-        const breakdown = counts.map((c) => `${c.memory_type}=${c.cnt}`).join(", ") || "none";
+        // #264 WS2: display the human-term label (Knowledge/Experience/...), not
+        // the internal enum — the operator reading the log sees human terms.
+        const breakdown = counts.map((c) => `${(0, type_labels_js_1.labelForType)(c.memory_type)}=${c.cnt}`).join(", ") || "none";
         console.log(`[hicortex] classify-types ${report.aborted ? "ABORTED" : "complete"}: ` +
             `${report.scanned} classified, ${report.reclassified} reclassified, ` +
             `${report.unchanged} unchanged, ${report.failed} infra-skipped`);

package/dist/type-labels.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Human-term labels for the internal `memory_type` enum (#264 WS2).
+ *
+ * The data model stores four types under unintuitive internal names
+ * (`fact` / `episode` / `decision` / `lesson`). Product-facing surfaces show
+ * the human terms instead — Knowledge / Experience / Decisions / Learnings —
+ * via this single label map. The enum values themselves are NEVER changed:
+ * no DB column, query, distiller tag, or storage path is altered. This is a
+ * DISPLAY rename only; every user-facing rendering routes through
+ * `labelForType`.
+ *
+ * Mapping (decided 2026-08-11, research/2026-08-11-identity-reframe-brainstorm.md):
+ *   fact     → Knowledge
+ *   episode  → Experience
+ *   decision → Decisions
+ *   lesson   → Learnings
+ *
+ * Unknown / future types fall back to the raw value (never silently remapped).
+ */
+/**
+ * The four documented memory types mapped to their human-term labels.
+ * Kept as a plain record so it can be iterated for coverage assertions.
+ */
+export declare const MEMORY_TYPE_LABELS: Record<string, string>;
+/**
+ * Return the human-term label for a `memory_type` enum value. Unknown or
+ * future types (including null/undefined) fall back to the raw input so new
+ * types are visible rather than silently mislabeled.
+ */
+export declare function labelForType(t: string | null | undefined): string;

package/dist/type-labels.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Human-term labels for the internal `memory_type` enum (#264 WS2).
+ *
+ * The data model stores four types under unintuitive internal names
+ * (`fact` / `episode` / `decision` / `lesson`). Product-facing surfaces show
+ * the human terms instead — Knowledge / Experience / Decisions / Learnings —
+ * via this single label map. The enum values themselves are NEVER changed:
+ * no DB column, query, distiller tag, or storage path is altered. This is a
+ * DISPLAY rename only; every user-facing rendering routes through
+ * `labelForType`.
+ *
+ * Mapping (decided 2026-08-11, research/2026-08-11-identity-reframe-brainstorm.md):
+ *   fact     → Knowledge
+ *   episode  → Experience
+ *   decision → Decisions
+ *   lesson   → Learnings
+ *
+ * Unknown / future types fall back to the raw value (never silently remapped).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_TYPE_LABELS = void 0;
+exports.labelForType = labelForType;
+/**
+ * The four documented memory types mapped to their human-term labels.
+ * Kept as a plain record so it can be iterated for coverage assertions.
+ */
+exports.MEMORY_TYPE_LABELS = {
+    fact: "Knowledge",
+    episode: "Experience",
+    decision: "Decisions",
+    lesson: "Learnings",
+};
+/**
+ * Return the human-term label for a `memory_type` enum value. Unknown or
+ * future types (including null/undefined) fall back to the raw input so new
+ * types are visible rather than silently mislabeled.
+ */
+function labelForType(t) {
+    if (!t)
+        return "—";
+    return exports.MEMORY_TYPE_LABELS[t] ?? t;
+}

package/dist/types.d.ts

@@ -161,6 +161,26 @@ export interface ConsolidationReport {
         calls_used: number;
         calls_remaining: number;
         calls_by_stage: Record<string, number>;
+        /**
+         * True when `calls_used >= max_calls` at run end (#255). The run continued
+         * to completion (no abort) but LLM-bound stages past the boundary deferred
+         * their remaining work — a quality-degradation signal, not a failure.
+         * Absent on pre-#255 reports; treat as false.
+         */
+        exhausted?: boolean;
+        /**
+         * Per-stage count of LLM-call REQUESTS refused because the budget was
+         * exhausted (#255). Keys are the same stage labels passed to
+         * `BudgetTracker.use()`. The value is the SUM of the `count` args passed
+         * to each refused `use()` call in that stage — in production every `use()`
+         * call passes count=1, so a stage present here with count N hit the
+         * boundary and had N further single-call requests denied (stages break on
+         * first refusal, so N is small per stage). For item-level "how many
+         * memories/pairs were skipped" see the per-stage reports (e.g.
+         * stages.importance.skipped_budget), which count MEMORIES not call
+         * requests. Absent on pre-#255 reports.
+         */
+        deferred_by_stage?: Record<string, number>;
         /**
          * Token usage per stage (#246). Each value sums prompt + completion +
          * total across every metered LLM call in that stage this run. A stage with
@@ -187,6 +207,14 @@ export interface HicortexConfig {
     serverUrl?: string;
     /** Bearer token for the Hicortex server. Localhost bypasses auth by default. */
     authToken?: string;
+    /**
+     * Optional PRIOR bearer token kept around during rotation (#254). When set,
+     * BOTH `authToken` and `authTokenPrevious` are accepted (constant-time,
+     * zero-downtime rotation). Absent/empty → single-token behaviour. Rotate by
+     * writing the new value to `authToken` and the old value here, then later
+     * clearing this key once all clients have switched.
+     */
+    authTokenPrevious?: string;
     /**
      * Stable per-install UUID generated by `init` (see ensureAgentId in init.ts;
      * never rotated). Attribution identity of the capturing client — stored on

package/dist/uninstall.d.ts

@@ -2,4 +2,16 @@
  * Hicortex uninstall — clean removal of CC integration.
  * Preserves the database (user data).
  */
+/**
+ * Matches a CC SessionStart hook `command` that runs the Hicortex
+ * identity/learnings hook — the canonical `learnings-identity` (#264) OR the
+ * legacy `lessons-context` alias. Exported so the uninstall behavior (which
+ * name variants get cleaned up) is unit-testable without spinning up CC.
+ * Word-boundary guard so "learnings-identity" never matches a hypothetical
+ * "learnings-identity-foo", the two names stay distinct from each other, and
+ * neither collides with the sibling `recall-hook` SessionStart hook.
+ */
+export declare const SESSION_START_HOOK_COMMAND_RE: RegExp;
+/** True when a CC hook `command` string runs the Hicortex SessionStart hook. */
+export declare function isHicortexSessionStartHook(command: string): boolean;
 export declare function runUninstall(): Promise<void>;

package/dist/uninstall.js

@@ -4,6 +4,8 @@
  * Preserves the database (user data).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_START_HOOK_COMMAND_RE = void 0;
+exports.isHicortexSessionStartHook = isHicortexSessionStartHook;
 exports.runUninstall = runUninstall;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -17,6 +19,20 @@ const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const CLAUDE_MD = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
+/**
+ * Matches a CC SessionStart hook `command` that runs the Hicortex
+ * identity/learnings hook — the canonical `learnings-identity` (#264) OR the
+ * legacy `lessons-context` alias. Exported so the uninstall behavior (which
+ * name variants get cleaned up) is unit-testable without spinning up CC.
+ * Word-boundary guard so "learnings-identity" never matches a hypothetical
+ * "learnings-identity-foo", the two names stay distinct from each other, and
+ * neither collides with the sibling `recall-hook` SessionStart hook.
+ */
+exports.SESSION_START_HOOK_COMMAND_RE = /(^|\s)(?:learnings-identity|lessons-context)(\s|$)/;
+/** True when a CC hook `command` string runs the Hicortex SessionStart hook. */
+function isHicortexSessionStartHook(command) {
+    return typeof command === "string" && exports.SESSION_START_HOOK_COMMAND_RE.test(command);
+}
 async function ask(question) {
     const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => {
@@ -130,7 +146,9 @@ async function runUninstall() {
     }
     if (removedCmds > 0)
         console.log(`  ✓ Removed ${removedCmds} legacy CC command${removedCmds > 1 ? "s" : ""} (/learn, /hicortex-activate)`);
-    // 4. Remove SessionStart hook (JSON merge — filter out entries containing "lessons-context")
+    // 4. Remove SessionStart hook (JSON merge — filter out entries containing
+    //    EITHER the canonical "learnings-identity" OR the legacy "lessons-context"
+    //    alias, #264 backcompat: an install may have written either name.)
     try {
         const raw = (0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8");
         const settings = JSON.parse(raw);
@@ -147,7 +165,7 @@ async function runUninstall() {
                         if (typeof h !== "object" || h === null)
                             return false;
                         const hook = h;
-                        return typeof hook.command === "string" && hook.command.includes("lessons-context");
+                        return typeof hook.command === "string" && isHicortexSessionStartHook(hook.command);
                     });
                 }
                 return true;
@@ -155,7 +173,7 @@ async function runUninstall() {
             if (filtered.length < before) {
                 hooks.SessionStart = filtered;
                 (0, node_fs_1.writeFileSync)(CC_SETTINGS, JSON.stringify(settings, null, 2));
-                console.log("  ✓ Removed SessionStart lessons-context hook");
+                console.log("  ✓ Removed SessionStart learnings-identity hook");
             }
         }
     }

package/dist/viz.d.ts

@@ -37,8 +37,16 @@ export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
  * middleware before this runs). With no token configured, remote requests are
  * REJECTED (not open): the default bind is 0.0.0.0, so "no token = no auth"
  * would expose the whole memory store to the network.
+ *
+ * `authTokenPrevious` (optional, #254) is the prior token kept around during
+ * rotation. Both tokens are accepted; this gives a zero-downtime rotation
+ * window — in-flight clients configured with the old token keep working until
+ * they pick up the new one. BOTH comparisons are constant-time and both are
+ * always evaluated (no short-circuit), so a caller cannot learn WHICH token
+ * matched from the response timing. Absent/empty `authTokenPrevious` behaves
+ * exactly as the single-token middleware always has.
  */
-export declare function createAuthMiddleware(authToken: string | undefined): express.RequestHandler;
+export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string): express.RequestHandler;
 /**
  * Resolve the on-disk path of the viz page. Throws (fail explicitly) when the
  * asset is missing — a broken install should surface, not degrade silently.
@@ -52,24 +60,29 @@ export declare function readVizHtml(): string;
  */
 export declare function vizHandler(): express.RequestHandler;
 /**
- * Resolve the on-disk path of the context-layer editor page. Throws (fail
+ * Resolve the on-disk path of the identity-layer editor page. Throws (fail
  * explicitly) when the asset is missing — same contract as resolveVizHtmlPath.
  * assets/ sits next to both dist/ (dist/viz.js → ../assets/) and src/
  * (src/viz.ts → ../assets/ under tsx), so one sibling candidate covers both.
  */
-export declare function resolveContextHtmlPath(): string;
-/** Read the context editor page. Read at request time so a reinstall is live. */
-export declare function readContextHtml(): string;
+export declare function resolveIdentityHtmlPath(): string;
+/** Read the identity editor page. Read at request time so a reinstall is live. */
+export declare function readIdentityHtml(): string;
 /**
- * Express handler for GET /context/ui — the PRIMARY edit surface for the
- * standing context layer. 503 with the usual {error} shape when the asset
- * cannot be read, exactly like vizHandler.
+ * Express handler for GET /identity/ui — the PRIMARY edit surface for the
+ * standing identity layer. 503 with the usual {error} shape when the asset
+ * cannot be read, exactly like vizHandler. Also serves the legacy
+ * /context/ui URL (#264 backcompat).
  */
-export declare function contextUiHandler(): express.RequestHandler;
+export declare function identityUiHandler(): express.RequestHandler;
+/** Backcompat aliases (#264). */
+export declare const resolveContextHtmlPath: typeof resolveIdentityHtmlPath;
+export declare const readContextHtml: typeof readIdentityHtml;
+export declare const contextUiHandler: typeof identityUiHandler;
 /**
  * Resolve the on-disk path of the dashboard page. Throws (fail explicitly)
  * when the asset is missing — same contract as resolveVizHtmlPath and
- * resolveContextHtmlPath. assets/ sits next to both dist/ and src/ (the
+ * resolveIdentityHtmlPath. assets/ sits next to both dist/ and src/ (the
  * sibling layout the other resolvers rely on).
  */
 export declare function resolveDashboardHtmlPath(): string;
@@ -78,7 +91,7 @@ export declare function readDashboardHtml(): string;
 /**
  * Express handler for GET /dashboard — the view-only analytics page (#224).
  * 503 with the usual {error} shape when the asset cannot be read, exactly like
- * vizHandler and contextUiHandler. The page SHELL is public (exempted in
+ * vizHandler and identityUiHandler. The page SHELL is public (exempted in
  * createAuthMiddleware); all data comes from GET /dashboard/data (bearer-only).
  */
 export declare function dashboardHandler(): express.RequestHandler;