@gamaze/hicortex 0.18.1 → 0.18.3

package/assets/dashboard.html

@@ -238,10 +238,15 @@ let compKey = "by_type";
 
 const $ = (id) => document.getElementById(id);
 
-// #264 WS2: human-term labels for the internal memory_type enum. The data
-// blob carries the RAW enum keys (a stable JSON contract, also relied on by
-// tests); only the rendered label changes. Unknown keys pass through.
+// #264 final: the data blob carries the CANONICAL human-term keys
+// (knowledge/experience/decisions/learnings). Legacy raw keys are also mapped
+// so a snapshot taken mid-migrate renders correctly. Unknown keys pass through.
 const TYPE_LABELS = {
+  knowledge: "Knowledge",
+  experience: "Experience",
+  decisions: "Decisions",
+  learnings: "Learnings",
+  // Legacy raw enum (same types, renamed).
   fact: "Knowledge",
   episode: "Experience",
   decision: "Decisions",

package/assets/viz.html

@@ -389,10 +389,16 @@
   var selDomain = document.getElementById("f-domain");
   var selType = document.getElementById("f-type");
 
-  // #264 WS2: human-term labels for the internal memory_type enum. Node data
-  // carries the RAW enum (the /graph JSON contract filters on it); only the
-  // rendered strings change. Unknown values pass through unchanged.
+  // #264 final: node data carries the CANONICAL human-term values
+  // (knowledge/experience/decisions/learnings). Legacy raw values are also
+  // mapped so a mid-migrate snapshot renders correctly. Unknown values pass
+  // through unchanged.
   var TYPE_LABELS = {
+    knowledge: "Knowledge",
+    experience: "Experience",
+    decisions: "Decisions",
+    learnings: "Learnings",
+    // Legacy raw enum (same types, renamed).
     fact: "Knowledge",
     episode: "Experience",
     decision: "Decisions",

package/dist/consolidate.js

@@ -418,7 +418,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             const severity = String(lo.severity ?? "important");
             const confidence = String(lo.confidence ?? "medium");
             const sourcePattern = String(lo.source_pattern ?? "");
-            // No `## Lesson:` prefix: memory_type='lesson' carries the type, and the
+            // No `## Lesson:` prefix: memory_type='learnings' carries the type, and the
             // text is the topic-first first line (display reads the first line, not a
             // header parse — see learnings-identity.ts / index.ts).
             let content = `${lessonText}\n\n`;
@@ -443,7 +443,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                 // the accidental 1−L2 scale and required cosine > 0.98 — the check
                 // effectively never fired. See isContradictionCandidate.
                 const similarLessons = storage.vectorSearch(db, embedding, 3)
-                    .filter((n) => isContradictionCandidate(n.distance) && n.memory_type === "lesson");
+                    .filter((n) => isContradictionCandidate(n.distance) && n.memory_type === "learnings");
                 let contradicted = false;
                 if (similarLessons.length > 0 && budget.use("contradiction_check")) {
                     const existingText = similarLessons[0].content.slice(0, 300);
@@ -470,7 +470,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                     storage.insertMemory(db, content, embedding, {
                         sourceAgent: "hicortex/reflection",
                         project,
-                        memoryType: "lesson",
+                        memoryType: "learnings",
                         baseStrength: baseStrength[severity] ?? 0.8,
                     });
                     generated++;
@@ -509,7 +509,7 @@ function rebuildContentModuleIndex(db, domains, stateDir) {
         .all();
     const lessonRows = db
         .prepare(`SELECT domain, COUNT(*) AS cnt FROM memories
-       WHERE domain IS NOT NULL AND memory_type = 'lesson' GROUP BY domain`)
+       WHERE domain IS NOT NULL AND memory_type = 'learnings' GROUP BY domain`)
         .all();
     const memByDomain = new Map(memRows.map((r) => [r.domain, r.cnt]));
     const lessonByDomain = new Map(lessonRows.map((r) => [r.domain, r.cnt]));
@@ -637,7 +637,7 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
     }
     const lessonRows = db
         .prepare(`SELECT project, COUNT(*) as cnt FROM memories
-       WHERE project IS NOT NULL AND memory_type = 'lesson'
+       WHERE project IS NOT NULL AND memory_type = 'learnings'
        GROUP BY project`)
         .all();
     const lessonsByProject = new Map(lessonRows.map((r) => [r.project, r.cnt]));
@@ -997,7 +997,7 @@ const SUPERSESSION_BATCH_SIZE = 500;
  * events, not mutable state, so there is nothing to supersede.
  */
 function isSupersedableShape(mem) {
-    return (mem.memory_type === "decision" ||
+    return (mem.memory_type === "decisions" ||
         mem.content.includes("[Decisions Made]") ||
         mem.content.includes("[Corrections & Rejections]") ||
         mem.content.includes("[Facts Learned]") ||
@@ -1117,7 +1117,7 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     // in lockstep (an inline SQL copy, so drift here silently narrows scope).
     `SELECT rowid AS __rowid, * FROM memories
        WHERE rowid > ?
-         AND (memory_type = 'decision'
+         AND (memory_type = 'decisions'
               OR content LIKE '%[Decisions Made]%'
               OR content LIKE '%[Corrections & Rejections]%'
               OR content LIKE '%[Facts Learned]%'

package/dist/dashboard.js

@@ -53,7 +53,7 @@ function countBy(db, col) {
 function computeDashboardMetrics(db) {
     const mem = db.prepare("SELECT COUNT(*) AS c FROM memories").get().c;
     const lesson = db
-        .prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'")
+        .prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'learnings'")
         .get().c;
     const link = db.prepare("SELECT COUNT(*) AS c FROM memory_links").get().c;
     const adoptionRow = db
@@ -228,7 +228,7 @@ function backfillSnapshots(db) {
             const dayRows = byDay.get(d);
             for (const r of dayRows) {
                 mem++;
-                if (r.memory_type === "lesson")
+                if (r.memory_type === "learnings")
                     lesson++;
                 byType[r.memory_type] = (byType[r.memory_type] ?? 0) + 1;
                 const domKey = r.domain ?? "(unscoped)";
@@ -380,7 +380,7 @@ function handleDashboardData(db, query, config) {
     const lessonRows = db
         .prepare(`SELECT id, content, created_at
          FROM memories
-        WHERE memory_type = 'lesson' AND created_at BETWEEN ? AND ?
+        WHERE memory_type = 'learnings' AND created_at BETWEEN ? AND ?
         ORDER BY created_at ASC`)
         .all(dayStart, dayEnd);
     // Stage outcomes for the day: dedup merges + supersession links that day.

package/dist/db.js

@@ -105,7 +105,7 @@ CREATE TABLE IF NOT EXISTS memories (
     source_session TEXT,
     project TEXT,
     privacy TEXT DEFAULT 'WORK',
-    memory_type TEXT DEFAULT 'episode',
+    memory_type TEXT DEFAULT 'experience',
     updated_at TIMESTAMP
 );
 
@@ -488,6 +488,29 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 13,
+        name: "memory_type_unified_terminology",
+        up: (db) => {
+            // #264 final step: rename the memory_type COLUMN VALUES from the raw
+            // internal enum (fact/episode/decision/lesson) to the unified human
+            // terms (knowledge/experience/decisions/learnings). The column itself,
+            // its default, and every SQL query/filter were updated in the same
+            // change; this migration converts existing rows in place. Idempotent:
+            // re-running against an already-migrated DB matches 0 rows per clause.
+            // The CREATE TABLE default is now 'experience' (was 'episode'); legacy
+            // rows with the old default value are rewritten here.
+            //
+            // Ordering is irrelevant (each clause keys on a distinct old value) and
+            // no clause can fire on another clause's output (the new values are
+            // disjoint from the old). The transaction wrapper in migrate() makes the
+            // whole migration atomic.
+            db.exec("UPDATE memories SET memory_type = 'knowledge'  WHERE memory_type = 'fact'");
+            db.exec("UPDATE memories SET memory_type = 'experience' WHERE memory_type = 'episode'");
+            db.exec("UPDATE memories SET memory_type = 'decisions'  WHERE memory_type = 'decision'");
+            db.exec("UPDATE memories SET memory_type = 'learnings'  WHERE memory_type = 'lesson'");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/distiller.d.ts

@@ -3,7 +3,7 @@
  * Simplified from hicortex/distiller.py — messages come from agent_end hook,
  * not from filesystem scanning.
  */
-import type { LlmClient } from "./llm.js";
+import type { LlmClient, LlmUsage } from "./llm.js";
 import { type RedactionConfig } from "./redact.js";
 /**
  * Estimate a safe chunk size in chars based on the LLM provider and model.
@@ -39,7 +39,9 @@ export declare function extractConversationText(messages: unknown[], redactionCo
  * discarded (full text). Callers use it to build a durable audit trail (#156);
  * omitting it leaves gate behaviour unchanged.
  */
-export declare function distillSession(llm: LlmClient, conversation: string, projectName: string, date: string, chunkSizeChars?: number, droppedOut?: string[]): Promise<DistilledEntry[]>;
+export declare function distillSession(llm: LlmClient, conversation: string, projectName: string, date: string, chunkSizeChars?: number, droppedOut?: string[], 
+/** Called with each chunk's token usage (#5 budget metering). Optional. */
+onUsage?: (usage: LlmUsage) => void): Promise<DistilledEntry[]>;
 /**
  * Reject ONLY structurally-empty distiller fragments before they become
  * memories (#156). The distiller occasionally emits leftovers that parse into
@@ -64,13 +66,13 @@ export declare function distillSession(llm: LlmClient, conversation: string, pro
 export declare function hasMinimalSubstance(entry: string): boolean;
 /**
  * A parsed distillation entry: the stored content (type tag STRIPPED) plus the
- * classified memory_type. `memoryType` is one of "episode" | "fact" |
- * "decision" — the three distillation-time types. "lesson" is deliberately
- * absent: lessons are the reflection stage's product, never distillation's
- * (#216). A missing/unknown tag defaults to "episode" so older distiller
+ * classified memory_type. `memoryType` is one of "experience" | "knowledge" |
+ * "decisions" — the three distillation-time types. "learnings" is deliberately
+ * absent: learnings are the reflection stage's product, never distillation's
+ * (#216). A missing/unknown tag defaults to "experience" so older distiller
  * output (pre-#216, no tag) stays backward-compatible.
  */
 export interface DistilledEntry {
     content: string;
-    memoryType: "episode" | "fact" | "decision";
+    memoryType: "experience" | "knowledge" | "decisions";
 }

package/dist/distiller.js

@@ -226,7 +226,9 @@ function extractConversationText(messages, redactionConfig) {
  * discarded (full text). Callers use it to build a durable audit trail (#156);
  * omitting it leaves gate behaviour unchanged.
  */
-async function distillSession(llm, conversation, projectName, date, chunkSizeChars, droppedOut) {
+async function distillSession(llm, conversation, projectName, date, chunkSizeChars, droppedOut, 
+/** Called with each chunk's token usage (#5 budget metering). Optional. */
+onUsage) {
     if (conversation.length < MIN_CONVERSATION_CHARS) {
         return [];
     }
@@ -239,7 +241,7 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
     const chunkSize = chunkSizeChars ?? MAX_TRANSCRIPT_CHARS;
     // If transcript fits in one chunk, distill directly (errors propagate)
     if (transcript.length <= chunkSize) {
-        const { entries, dropped } = await distillChunk(llm, transcript, projectName, date);
+        const { entries, dropped } = await distillChunk(llm, transcript, projectName, date, onUsage);
         if (droppedOut)
             droppedOut.push(...dropped);
         return entries;
@@ -261,13 +263,13 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
     for (let i = 0; i < chunks.length; i++) {
         console.log(`[hicortex]     Chunk ${i + 1}/${chunks.length} (${chunks[i].length} chars)`);
         try {
-            const { entries, dropped } = await distillChunk(llm, chunks[i], projectName, date);
+            const { entries, dropped } = await distillChunk(llm, chunks[i], projectName, date, onUsage);
             if (droppedOut)
                 droppedOut.push(...dropped);
             for (const entry of entries) {
                 // Deduplicate by normalized content (type tag does not participate —
                 // two chunks extracting the same fact should collapse regardless of
-                // whether one tagged it [F] and the other [E]).
+                // whether one tagged it [K] and the other [E]).
                 const key = entry.content.toLowerCase().replace(/\s+/g, " ").slice(0, 100);
                 if (!seen.has(key)) {
                     seen.add(key);
@@ -308,13 +310,19 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
  * `dropped` carries entries the substance gate rejected (full text) so the
  * caller can surface them in a durable audit trail (#156).
  */
-async function distillChunk(llm, transcript, projectName, date) {
+async function distillChunk(llm, transcript, projectName, date, onUsage) {
     const prompt = (0, prompts_js_1.distillation)(projectName, date, transcript);
     // NOTE: Intentionally no try/catch here. Transient LLM errors (network
     // failures, 4xx/5xx, model-not-found, timeouts) propagate up to the caller
     // so the nightly pipeline can treat them as "retry later" instead of
     // "processed successfully with zero extractions".
-    const { text: result } = await llm.completeDistill(prompt);
+    const { text: result, usage } = await llm.completeDistill(prompt);
+    // #5: report this chunk's token usage to the caller's budget meter. Optional
+    // (absent for callers that don't meter); a missing/undefined usage (claude-cli)
+    // is a no-op — consistent with the existing design that such tenants never
+    // trip a budget.
+    if (usage && onUsage)
+        onUsage(usage);
     if (!result)
         return { entries: [], dropped: [] };
     if (result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT")) {
@@ -325,7 +333,7 @@ async function distillChunk(llm, transcript, projectName, date) {
     // sometimes ignore constraints (cf. the prior max-15-bullet failure). Count
     // entries that still look actor-led or bracket-led so a format regression
     // shows in nightly logs, not months later in the next eval. Non-blocking.
-    // Note: the type tag ([E]/[F]/[D]) is already stripped by the parser, so a
+    // Note: the type tag ([E]/[K]/[D]) is already stripped by the parser, so a
     // leading bracket here means a payload-bracket or a category-first regression.
     const offTopic = parsed.filter((e) => /^\s*(user|ai|the user|assistant)\b/i.test(e.content) || /^\s*\[/.test(e.content)).length;
     if (parsed.length > 0 && offTopic > 0) {
@@ -426,21 +434,31 @@ function hasMinimalSubstance(entry) {
 }
 /**
  * Map a single-letter type tag to the stored memory_type. Unknown/absent →
- * episode (the pre-#216 default). `[L]` is explicitly rejected → episode: the
- * distiller must NEVER emit lessons (that's the reflection stage's job), so a
- * model that emits `[L]` is wrong and we do not propagate it as a lesson.
+ * experience (the pre-#216 default). `[L]` is explicitly rejected →
+ * experience: the distiller must NEVER emit learnings (that's the reflection
+ * stage's job), so a model that emits `[L]` is wrong and we do not propagate
+ * it as a learning.
+ *
+ * The single-letter tags ([E]/[K]/[D]) are unchanged from the raw-enum era —
+ * the model is taught these as "EXPERIENCE/KNOWLEDGE/DECISIONS" concepts in prompts.ts
+ * (ordinary English the model understands), and only the resulting STORED
+ * value changed in #264 (episode→experience, fact→knowledge, decision→
+ * decisions). The tag letters stay stable so neither the prompt nor the
+ * parser needs to change; only this mapping table moves.
  */
 function typeFromTag(letter) {
     switch (letter) {
-        case "F":
+        case "K":
+        case "k":
+        case "F": // legacy tag (was Fact)
         case "f":
-            return "fact";
+            return "knowledge";
         case "D":
         case "d":
-            return "decision";
-        // E, e, L, l (rejected), undefined, or anything else → episode.
+            return "decisions";
+        // E, e, L, l (rejected), undefined, or anything else → experience.
         default:
-            return "episode";
+            return "experience";
     }
 }
 /**
@@ -448,7 +466,7 @@ function typeFromTag(letter) {
  * Each bullet becomes a separate memory. The leading `[E]`/`[F]`/`[D]` type
  * tag is extracted (→ memoryType), stripped from the stored content, and
  * passed to `insertMemory` via the `memoryType` option (#216). Bullets with
- * no tag default to "episode" (backward compatible with pre-#216 distiller
+ * no tag default to "experience" (backward compatible with pre-#216 distiller
  * output that never carried a tag).
  */
 function parseDistilledEntries(markdown) {
@@ -472,15 +490,15 @@ function parseDistilledEntries(markdown) {
             // Extract an optional leading single-letter type tag: "[E]", "[F]",
             // "[D]" (case-insensitive). The tag must be the very first token of the
             // bullet — a bracket that appears later is payload, not a type tag.
-            const tagMatch = body.match(/^\[([EFDefdLl])\]\s*/);
+            const tagMatch = body.match(/^\[([EFDKefdklL])\]\s*/);
             if (tagMatch) {
                 const memoryType = typeFromTag(tagMatch[1].toUpperCase());
                 entries.push({ content: body.slice(tagMatch[0].length), memoryType });
             }
             else {
-                // No tag → episode (pre-#216 distiller output, or a model that
+                // No tag → experience (pre-#216 distiller output, or a model that
                 // skipped the tag). Keep the content verbatim.
-                entries.push({ content: body, memoryType: "episode" });
+                entries.push({ content: body, memoryType: "experience" });
             }
         }
     }

package/dist/eval/recall-sweep.js

@@ -431,7 +431,7 @@ async function buildCorpusDb(dbPath) {
         const vec = await (0, embedder_js_1.embed)(mem.text);
         const id = storage.insertMemory(db, mem.text, vec, {
             sourceAgent: "eval-corpus",
-            memoryType: "episode",
+            memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
         });
         idToTopic.set(id, mem.topic);
@@ -455,7 +455,7 @@ async function buildScopeDb(dbPath) {
         const vec = await (0, embedder_js_1.embed)(mem.text);
         const id = storage.insertMemory(db, mem.text, vec, {
             sourceAgent: "eval-scope",
-            memoryType: "episode",
+            memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
             project: mem.project, // #203 scope label
         });

package/dist/eval/reflection-census.js

@@ -11,11 +11,11 @@ exports.runReflectionCensus = runReflectionCensus;
 function runReflectionCensus(db) {
     const lessonsByDate = db
         .prepare(`SELECT date(created_at) AS date, COUNT(*) AS count
-       FROM memories WHERE memory_type = 'lesson'
+       FROM memories WHERE memory_type = 'learnings'
        GROUP BY date ORDER BY date`)
         .all();
-    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'").get().c;
-    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'episode'").get().c;
+    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'learnings'").get().c;
+    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'experience'").get().c;
     return {
         lessonsByDate,
         totalLessons,

package/dist/hosted-boot.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Hosted-mode boot assertions (#110 §1-§2, #271 — Phase 0B).
+ *
+ * Pure decision function — the side-effect (console.error + process.exit) is
+ * the caller's job (mcp-server.ts at boot), so the assertion logic is unit-
+ * testable in-process without spawning a child or intercepting process.exit.
+ *
+ * INERT unless hostedMode is true (self-hosted default). When true, the server
+ * must refuse to start under either condition:
+ *   - HICORTEX_DB_PATH set (a tenant must not be redirectable to an attacker-
+ *     chosen DB location — path-override attack);
+ *   - the localhost auth-bypass marker file present (hosted is fail-closed —
+ *     no bypass; a tenant dir provisioned from a restored tar could otherwise
+ *     ship with the bypass active).
+ *
+ * Spec: specs/2026-07-27-hosted-service.md §1-§2 (Phase 0B, issue #271).
+ */
+export interface HostedBootInput {
+    /** Resolved hostedMode flag from config (absent/false → self-hosted). */
+    hostedMode: boolean;
+    /** Whether HICORTEX_DB_PATH is currently set in the environment. */
+    dbPathEnvSet: boolean;
+    /** Whether the localhost-bypass marker file exists in the home dir. */
+    bypassMarkerPresent: boolean;
+}
+export type HostedBootDecision = {
+    ok: true;
+    hostedMode: boolean;
+} | {
+    ok: false;
+    hostedMode: true;
+    reason: "db-path-override" | "bypass-marker";
+    message: string;
+};
+/**
+ * Decide whether the server may boot under hosted-mode constraints. Returns
+ * `{ok:true}` for self-hosted (always — assertions never fire) or hosted with
+ * a clean environment; returns `{ok:false, message}` when a hosted constraint
+ * is violated (caller logs + exits non-zero).
+ */
+export declare function checkHostedBoot(input: HostedBootInput): HostedBootDecision;
+/**
+ * Decide whether to emit the "Localhost auth bypass is disabled" boot warning
+ * (#271 — CR warning 4). Pure: the caller owns the console.warn side-effect,
+ * so this is unit-testable across the four input combinations without spawning
+ * a process or capturing stderr.
+ *
+ * Emits ONLY in self-hosted mode when the bypass marker is absent — the upgrade
+ * path (a user who upgraded without re-running init loses the bypass and sees
+ * 401s from localhost). Returns null in every other state:
+ *   - self-hosted + marker present: bypass active, nothing to warn about;
+ *   - hosted + marker absent: hosted is fail-closed by design, no bypass to warn;
+ *   - hosted + marker present: checkHostedBoot already refused (unreachable here
+ *     when called after a passed boot decision), and the failure message is the
+ *     operator-facing one — a second warning would be noise.
+ *
+ * The marker is read from the canonical Hicortex home (HICORTEX_HOME), matching
+ * where `init` writes it — NOT from stateDir, which can drift when
+ * HICORTEX_DB_PATH relocates the DB (#271 CR warning 1).
+ */
+export declare function shouldEmitBypassWarning(hostedMode: boolean, bypassMarkerPresent: boolean): string | null;

package/dist/hosted-boot.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkHostedBoot = checkHostedBoot;
+exports.shouldEmitBypassWarning = shouldEmitBypassWarning;
+/**
+ * Decide whether the server may boot under hosted-mode constraints. Returns
+ * `{ok:true}` for self-hosted (always — assertions never fire) or hosted with
+ * a clean environment; returns `{ok:false, message}` when a hosted constraint
+ * is violated (caller logs + exits non-zero).
+ */
+function checkHostedBoot(input) {
+    // KNOWN ESCAPE HATCH (CR M1, deferred to #110 Phase 0B item #2 — Docker):
+    // HICORTEX_HOME is the same class of env-var redirect as HICORTEX_DB_PATH
+    // (paths.ts honors it → a tenant who sets it points hostedMode/marker reads
+    // at an attacker-chosen dir with no config → hostedMode reads false → every
+    // assertion bypassed). It is NOT refused here because the per-tenant Docker
+    // template (#2) may legitimately use HICORTEX_HOME to give each tenant its
+    // own home dir. Resolution belongs with #2's tenant-home provisioning: either
+    // the orchestrator sanitizes HICORTEX_HOME (container sets it, tenant can't
+    // override), or this gate refuses it once the Docker design lands. Do NOT
+    // ship a hosted tenant before that decision is made.
+    const { hostedMode, dbPathEnvSet, bypassMarkerPresent } = input;
+    if (!hostedMode)
+        return { ok: true, hostedMode: false };
+    if (dbPathEnvSet) {
+        return {
+            ok: false,
+            hostedMode: true,
+            reason: "db-path-override",
+            message: `[hicortex] hostedMode is ON but HICORTEX_DB_PATH is set. ` +
+                `Hosted tenants must not allow DB-path overrides — refusing to start. ` +
+                `Unset HICORTEX_DB_PATH on hosted tenants.`,
+        };
+    }
+    if (bypassMarkerPresent) {
+        return {
+            ok: false,
+            hostedMode: true,
+            reason: "bypass-marker",
+            message: `[hicortex] hostedMode is ON but the localhost auth-bypass marker file ` +
+                `(.allow-localhost-bypass) is present. Hosted must be fail-closed — ` +
+                `refusing to start. Remove the marker file.`,
+        };
+    }
+    return { ok: true, hostedMode: true };
+}
+/**
+ * Decide whether to emit the "Localhost auth bypass is disabled" boot warning
+ * (#271 — CR warning 4). Pure: the caller owns the console.warn side-effect,
+ * so this is unit-testable across the four input combinations without spawning
+ * a process or capturing stderr.
+ *
+ * Emits ONLY in self-hosted mode when the bypass marker is absent — the upgrade
+ * path (a user who upgraded without re-running init loses the bypass and sees
+ * 401s from localhost). Returns null in every other state:
+ *   - self-hosted + marker present: bypass active, nothing to warn about;
+ *   - hosted + marker absent: hosted is fail-closed by design, no bypass to warn;
+ *   - hosted + marker present: checkHostedBoot already refused (unreachable here
+ *     when called after a passed boot decision), and the failure message is the
+ *     operator-facing one — a second warning would be noise.
+ *
+ * The marker is read from the canonical Hicortex home (HICORTEX_HOME), matching
+ * where `init` writes it — NOT from stateDir, which can drift when
+ * HICORTEX_DB_PATH relocates the DB (#271 CR warning 1).
+ */
+function shouldEmitBypassWarning(hostedMode, bypassMarkerPresent) {
+    if (!hostedMode && !bypassMarkerPresent) {
+        return ("[hicortex] Localhost auth bypass is disabled — run " +
+            "`npx @gamaze/hicortex init` to restore it.");
+    }
+    return null;
+}

package/dist/index.js

@@ -150,7 +150,7 @@ async function fetchOcIdentityBlock(agentId) {
     return (0, learnings_identity_js_1.gateAndRenderIdentity)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
 }
 /**
- * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
+ * Fetch /lessons and build the `## Hicortex Learnings` block, or null on any
  * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
  * output; the caller prepends the `## Identity` block and adds separators.
  */
@@ -177,8 +177,8 @@ async function buildLessonsBlock(project) {
         const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
         return `- ${title}${meta ? ` (${meta})` : ""}`;
     });
-    return (`## Hicortex Lessons (auto-injected from long-term memory)\n` +
-        `These are actionable lessons learned from past sessions:\n\n` +
+    return (`## Hicortex Learnings (auto-injected from long-term memory)\n` +
+        `These are actionable Learnings from past sessions:\n\n` +
         formatted.join("\n"));
 }
 // ---------------------------------------------------------------------------
@@ -354,7 +354,7 @@ exports.default = {
                 const agentId = (0, identity_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
                 // Fetch all three concurrently with INDEPENDENT fail-soft: no block
                 // may ever cost another. Order in the injected output: `## Identity`
-                // (standing identity, 0.13) → `## Hicortex Lessons` → the per-turn
+                // (standing identity, 0.13) → `## Hicortex Learnings` → the per-turn
                 // `## Memory recall (auto)` index (#193, closest to the prompt).
                 const [identityBlock, lessonsBlock, recallBlock] = await Promise.all([
                     fetchOcIdentityBlock(agentId).catch(() => null),
@@ -481,7 +481,7 @@ exports.default = {
         }), { name: "hicortex_recent" });
         api.registerTool((_ctx) => ({
             name: "hicortex_ingest",
-            description: "Store a new memory in long-term storage. Use for important facts, decisions, or lessons.",
+            description: "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.",
             parameters: {
                 type: "object",
                 properties: {
@@ -489,8 +489,8 @@ exports.default = {
                     project: { type: "string", description: "Project this memory belongs to" },
                     memory_type: {
                         type: "string",
-                        enum: ["episode", "lesson", "fact", "decision"],
-                        description: "Type of memory (default: episode)",
+                        enum: ["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"],
+                        description: "Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term).",
                     },
                 },
                 required: ["content"],
@@ -501,7 +501,7 @@ exports.default = {
                         content: args.content,
                         source_agent: `openclaw/${context?.agentId ?? "manual"}`,
                         project: args.project,
-                        memory_type: args.memory_type ?? "episode",
+                        memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : "experience",
                     }, 15000);
                     if (!result.ok) {
                         return { error: `Ingest failed: ${result.data?.error ?? `HTTP ${result.status}`}` };
@@ -516,7 +516,7 @@ exports.default = {
         }), { name: "hicortex_ingest" });
         api.registerTool((_ctx) => ({
             name: "hicortex_lessons",
-            description: "Get actionable lessons learned from past sessions. Auto-generated insights about mistakes to avoid.",
+            description: "Get actionable Learnings distilled from past sessions. Auto-generated insights about mistakes to avoid.",
             parameters: {
                 type: "object",
                 properties: {
@@ -530,7 +530,7 @@ exports.default = {
                         return { error: `Lessons fetch failed: ${describeGetFailure(status, "/lessons")}` };
                     const lessons = data.lessons ?? [];
                     if (lessons.length === 0) {
-                        return { content: [{ type: "text", text: "No lessons found." }] };
+                        return { content: [{ type: "text", text: "No Learnings found." }] };
                     }
                     const text = lessons.map((l) => `- ${l.content.slice(0, 500)}`).join("\n");
                     return { content: [{ type: "text", text }] };
@@ -612,8 +612,8 @@ exports.default = {
                     project: { type: "string", description: "New project name" },
                     memory_type: {
                         type: "string",
-                        enum: ["episode", "lesson", "fact", "decision"],
-                        description: "New memory type",
+                        enum: ["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"],
+                        description: "New memory type. Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term).",
                     },
                 },
                 required: ["id"],
@@ -624,7 +624,7 @@ exports.default = {
                         id: args.id,
                         content: args.content,
                         project: args.project,
-                        memory_type: args.memory_type,
+                        memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : undefined,
                     }, 15000);
                     if (result.status === 404) {
                         return { error: `Memory not found: ${args.id}` };

package/dist/init.d.ts

@@ -289,6 +289,21 @@ export declare function getPackageSpec(configDir?: string): string;
  * later — the "looks configured but isn't" trap (#176). Never persist it.
  */
 export declare function isEphemeralNpxPath(binPath: string): boolean;
+/**
+ * Build the PATH the launchd/systemd supervisors receive (#276). Order:
+ *   1. the binary's own dir — so a SIBLING node wins for nvm/volta/npm-global
+ *      installs (the version the global was installed under);
+ *   2. the dir of the node the supervisor should run under — resolved via
+ *      `which node` (the symlink path, stable across upgrades); see
+ *      resolveNodeDir(). This is the generic rescue: for bun/pnpm/yarn globals
+ *      the bin dir has NO node sibling, and on Apple Silicon node lives in
+ *      /opt/homebrew/bin. Baking the resolved node dir in fixes every package
+ *      manager without enumerating them;
+ *   3. the standard locations — including /opt/homebrew/bin (Apple Silicon
+ *      homebrew) as a belt-and-suspenders fallback for the no-sibling case.
+ * Deduped (preserving first-seen order); empties dropped.
+ */
+export declare function buildSupervisorPath(binaryArgs: string[]): string;
 /**
  * Install (or verify) the CC SessionStart hook that runs the canonical command
  * `hicortex learnings-identity` (aliased as the legacy `lessons-context`,