@gamaze/hicortex 0.18.1 → 0.18.3

package/dist/init.js

@@ -34,6 +34,7 @@ exports.writeClientConfig = writeClientConfig;
 exports.scaffoldDefaultDomains = scaffoldDefaultDomains;
 exports.getPackageSpec = getPackageSpec;
 exports.isEphemeralNpxPath = isEphemeralNpxPath;
+exports.buildSupervisorPath = buildSupervisorPath;
 exports.installSessionStartHook = installSessionStartHook;
 exports.installRecallHooks = installRecallHooks;
 exports.runInit = runInit;
@@ -45,6 +46,7 @@ exports.formatOnCalendarLines = formatOnCalendarLines;
 exports.formatLaunchdIntervals = formatLaunchdIntervals;
 exports.formatSystemdTimerBody = formatSystemdTimerBody;
 const paths_js_1 = require("./paths.js");
+const localhost_bypass_js_1 = require("./localhost-bypass.js");
 const telemetry_js_1 = require("./telemetry.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -1134,6 +1136,10 @@ function getPackageSpec(configDir = HICORTEX_HOME) {
 function installDaemon() {
     const os = (0, node_os_1.platform)();
     const binaryArgs = resolveBinaryArgs();
+    // #276: verify the supervisor can actually run (node resolvable on the
+    // generated PATH) before writing the plist/unit — turns a silent DOA into a
+    // loud install-time warning.
+    verifySupervisorRuntime(binaryArgs);
     if (os === "darwin") {
         return installLaunchd(binaryArgs);
     }
@@ -1185,6 +1191,71 @@ function resolveBinaryArgs() {
     const packageSpec = getPackageSpec();
     return [npxPath, "-y", packageSpec];
 }
+/**
+ * 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.
+ */
+function buildSupervisorPath(binaryArgs) {
+    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
+    const nodeDir = resolveNodeDir();
+    return [binDir, nodeDir, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"]
+        .filter((d, i, a) => d && a.indexOf(d) === i)
+        .join(":");
+}
+/**
+ * Resolve the dir of the node the supervisor should use (#276). Prefers
+ * `which node` — the SYMLINK path, stable across version upgrades (homebrew
+ * rotates the Cellar target but keeps /opt/homebrew/bin/node) — over
+ * process.execPath, which on macOS is the resolved realpath (the versioned
+ * Cellar dir, e.g. /opt/homebrew/Cellar/node/X.Y.Z/bin) and STALES on a
+ * `brew upgrade node`, re-introducing the silent-death the fix targets. Falls
+ * back to process.execPath's dir only if `which node` is unavailable.
+ */
+function resolveNodeDir() {
+    try {
+        const which = (0, node_child_process_1.execSync)("which node", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+        if (which)
+            return (0, node_path_1.dirname)(which);
+    }
+    catch { /* node not on PATH — fall through to execPath */ }
+    return (0, node_path_1.dirname)(process.execPath);
+}
+/** Dedup flag so the supervisor-runtime warning prints once per `init` run. */
+let supervisorRuntimeWarned = false;
+/**
+ * Install-time smoke test (#276): spawn the resolved binary with the SAME PATH
+ * the supervisor will use and confirm it can run (`--version`). Turns the
+ * silent-dead-on-arrival case (node unresolvable under launchd's empty PATH →
+ * the agent dies at the `#!/usr/bin/env node` shebang with exit 127, capture
+ * stops silently, no signal in `status` because the shell PATH masks it) into a
+ * LOUD install-time warning. Does NOT block install — the plist/unit is still
+ * written so a PATH fix + reload recovers it without re-init.
+ */
+function verifySupervisorRuntime(binaryArgs) {
+    if (supervisorRuntimeWarned)
+        return;
+    const supervisorEnv = { ...process.env, PATH: buildSupervisorPath(binaryArgs) };
+    try {
+        (0, node_child_process_1.execSync)([...binaryArgs, "--version"].join(" "), { stdio: "pipe", env: supervisorEnv });
+    }
+    catch {
+        supervisorRuntimeWarned = true;
+        console.error("  ⚠ WARNING: the scheduled daemon/nightly could not run with the generated PATH — " +
+            "`node` was not found, so the supervisor will fail silently at runtime (capture stops). " +
+            "Reinstall via `npm install -g @gamaze/hicortex` (recommended) or ensure node is at a " +
+            "standard location, then re-run `npx @gamaze/hicortex init`.");
+    }
+}
 /**
  * Install (or verify) the CC SessionStart hook that runs the canonical command
  * `hicortex learnings-identity` (aliased as the legacy `lessons-context`,
@@ -1305,7 +1376,7 @@ function installLaunchd(binaryArgs) {
     // PATH must start with the binary's own directory so the sibling node
     // binary (correct version for nvm installs) is found first.
     // launchd has no PATH by default; without this, node itself won't be found.
-    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
+    const supervisorPath = buildSupervisorPath(binaryArgs);
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1327,7 +1398,7 @@ ${programArgs}
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${binDir}:/usr/local/bin:/usr/bin:/bin</string>
+    <string>${supervisorPath}</string>
   </dict>
 </dict>
 </plist>`;
@@ -1354,7 +1425,7 @@ function installSystemd(binaryArgs) {
     const servicePath = (0, node_path_1.join)(unitDir, "hicortex.service");
     const execStart = [...binaryArgs, "server"].join(" ");
     // PATH must start with the binary's own directory (see installLaunchd for rationale).
-    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
+    const supervisorPath = buildSupervisorPath(binaryArgs);
     const service = `[Unit]
 Description=Hicortex MCP server — long-term memory for AI agents
 
@@ -1365,7 +1436,7 @@ Restart=on-failure
 RestartSec=10
 StandardOutput=journal
 StandardError=journal
-Environment=PATH=${binDir}:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=${supervisorPath}
 
 [Install]
 WantedBy=default.target
@@ -1404,6 +1475,13 @@ async function runInit(options = {}) {
     // first — every writer downstream loads through loadConfigStrict.
     if (options.repairConfig) {
         quarantineMalformedConfig((0, node_path_1.join)(HICORTEX_HOME, "config.json"));
+        // CR warning 2 (#271): repair-config is a plausible post-upgrade recovery
+        // action, so it MUST (re)write the localhost-bypass marker itself — defensive
+        // against a future early-return in this block. The full-init path writes it
+        // again at line ~1615 (idempotent: same content, returns false the second
+        // time). Never written in hosted mode (the boot assertion refuses to start
+        // with the marker present).
+        (0, localhost_bypass_js_1.writeLocalhostBypassMarker)(HICORTEX_HOME);
     }
     if (options.serverUrl) {
         await runClientInit(options.serverUrl, options.agentName);
@@ -1500,6 +1578,16 @@ async function runInit(options = {}) {
     // Classification activates automatically once an LLM is configured; until
     // then domains sit inert (strict-skip path).
     scaffoldDefaultDomains(configPath);
+    // Write the localhost auth-bypass marker (#110 §2, #271 — Phase 0B). The
+    // bypass is marker-gated from 0.18: self-hosted init writes the marker so
+    // existing installs keep the bypass after upgrade + re-init; a hosted tenant
+    // dir is fail-closed by default. Idempotent (overwrites an existing marker,
+    // refreshing the note). Never written in hosted mode (the boot assertion
+    // would refuse to start with the marker present).
+    const markerCreated = (0, localhost_bypass_js_1.writeLocalhostBypassMarker)(HICORTEX_HOME);
+    if (markerCreated) {
+        console.log("  ✓ Localhost auth-bypass marker written");
+    }
     // Per-agent identity id (#179): server mode writes it ONLY when the operator
     // passes --agent-name. Without the flag no agentName is written and the
     // co-located CC shares the global identity (global by default). Explicit flag
@@ -1944,9 +2032,12 @@ function formatSystemdTimerBody(isInterval, intervalSec, hours, jitterSec) {
  */
 function writeScheduleUnit(opts) {
     const binaryArgs = resolveBinaryArgs();
+    // #276: verify the scheduled nightly/capture can run before writing its unit.
+    verifySupervisorRuntime(binaryArgs);
     const os = (0, node_os_1.platform)();
-    // PATH must start with the binary's own directory (see installLaunchd for rationale).
-    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
+    // PATH the supervisor receives — includes the dir of the node running init
+    // (process.execPath) so bun/pnpm/yarn globals resolve node under launchd (#276).
+    const supervisorPath = buildSupervisorPath(binaryArgs);
     // One canonical nightly log path across platforms — status output, docs,
     // and support instructions all reference this single location.
     const logPath = (0, node_path_1.join)(HICORTEX_HOME, "nightly.log");
@@ -1999,7 +2090,7 @@ ${scheduleBlock}
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${binDir}:/usr/local/bin:/usr/bin:/bin</string>
+    <string>${supervisorPath}</string>
   </dict>
 </dict>
 </plist>`;
@@ -2033,7 +2124,7 @@ Type=oneshot
 ExecStart=${execStart}
 ${opts.timeoutMin ? `TimeoutStartSec=${opts.timeoutMin}min\n` : ""}StandardOutput=append:${logPath}
 StandardError=append:${logPath}
-Environment=PATH=${binDir}:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=${supervisorPath}
 Environment=HOME=${(0, node_os_1.homedir)()}
 WorkingDirectory=${(0, node_os_1.homedir)()}`;
         // Timer body: OnUnitActiveSec (interval, watchdog) or one OnCalendar line

package/dist/learnings-identity.js

@@ -117,7 +117,7 @@ async function fetchLessonsBlock(cfg) {
     parts.push("BEFORE making decisions, search memory: `hicortex_search` for prior decisions on the same topic.");
     parts.push("Use `hicortex_recent` at session start for recent project state.");
     if (lessonLines.length > 0) {
-        parts.push("", "### Lessons (updated nightly)");
+        parts.push("", "### Learnings (updated nightly)");
         parts.push(...lessonLines);
     }
     const { index } = data;
@@ -125,16 +125,16 @@ async function fetchLessonsBlock(cfg) {
         parts.push("", "### Memory Index");
         for (const domain of moduleIndex.domains) {
             const kwStr = domain.keywords.length > 0 ? `: ${domain.keywords.join(", ")}` : "";
-            parts.push(`${domain.name} (${domain.memoryCount} memories, ${domain.lessonCount} lessons)${kwStr}`);
+            parts.push(`${domain.name} (${domain.memoryCount} memories, ${domain.lessonCount} Learnings)${kwStr}`);
             if (domain.projects.length > 0)
                 parts.push(`  ${domain.projects.join(" | ")}`);
         }
-        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+        parts.push(`${index.total} memories, ${index.lessonCount} Learnings, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
     }
     else if (index.projects.length > 0) {
         parts.push("", "### Memory Index");
         parts.push(index.projects.map(p => `${p.name}: ${p.count}`).join(" | "));
-        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+        parts.push(`${index.total} memories, ${index.lessonCount} Learnings, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
     }
     return parts.join("\n");
 }

package/dist/localhost-bypass.d.ts

@@ -0,0 +1,27 @@
+/** Marker filename inside the Hicortex home dir. */
+export declare const LOCALHOST_BYPASS_MARKER = ".allow-localhost-bypass";
+/** Marker contents — a one-line note. Its mere PRESENCE is the signal. */
+export declare const LOCALHOST_BYPASS_MARKER_CONTENT: string;
+/**
+ * Resolve the marker file path for a given home dir. Defaults to the canonical
+ * Hicortex home (honors HICORTEX_HOME), so callers in tests can point the env
+ * override at a temp dir.
+ */
+export declare function localhostBypassMarkerPath(home?: string): string;
+/**
+ * Does the localhost auth-bypass marker exist? Pure filesystem check — no
+ * logging, no side-effects. Used by both createAuthMiddleware (gates the
+ * bypass per-request via a boot-time capture in mcp-server.ts) and the
+ * hosted-mode boot assertion.
+ */
+export declare function localhostBypassEnabled(home?: string): boolean;
+/**
+ * Write the localhost auth-bypass marker file (self-hosted init only — never
+ * in hosted mode). Idempotent: overwrites an existing marker so a re-init
+ * refreshes the explanatory note. Ensures the parent dir exists. Does NOT
+ * touch auth or any other config — just the one marker file.
+ *
+ * Returns true when a NEW marker was created (for init's "✓" reporting), false
+ * when one already existed (refreshed in place).
+ */
+export declare function writeLocalhostBypassMarker(home?: string): boolean;

package/dist/localhost-bypass.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCALHOST_BYPASS_MARKER_CONTENT = exports.LOCALHOST_BYPASS_MARKER = void 0;
+exports.localhostBypassMarkerPath = localhostBypassMarkerPath;
+exports.localhostBypassEnabled = localhostBypassEnabled;
+exports.writeLocalhostBypassMarker = writeLocalhostBypassMarker;
+/**
+ * Localhost auth-bypass marker file (#110 §2, #271 — Phase 0B).
+ *
+ * The localhost auth bypass in createAuthMiddleware (viz.ts) is marker-GATED
+ * from 0.18: it applies ONLY when this marker file exists in the Hicortex
+ * home dir. Self-hosted `init` writes the marker, so existing installs keep
+ * working after upgrade + re-init; a hosted tenant dir provisioned by any
+ * means (script, hand, restored tar) is fail-closed by default — no marker,
+ * no bypass, every connection (localhost included) needs the bearer token.
+ *
+ * Rationale (spec 2026-07-27 §2): with the bypass unconditional, a future
+ * `trust proxy` enablement would make `req.ip` header-spoofable and the
+ * bypass remotely triggerable. Inverting the default to "off unless marked"
+ * makes the bypass opt-in via a filesystem side-effect of self-hosted init,
+ * so a tenant home built from a bare config + DB restore cannot accidentally
+ * ship with the bypass active. The hosted-mode boot assertion (mcp-server.ts)
+ * refuses to start if BOTH hostedMode=true AND the marker is present, so even
+ * a stray marker cannot open a hosted tenant.
+ *
+ * Marker file name: `.allow-localhost-bypass` (dot-prefixed; not a secret —
+ * its mere presence is the signal; no contents needed).
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_js_1 = require("./paths.js");
+/** Marker filename inside the Hicortex home dir. */
+exports.LOCALHOST_BYPASS_MARKER = ".allow-localhost-bypass";
+/** Marker contents — a one-line note. Its mere PRESENCE is the signal. */
+exports.LOCALHOST_BYPASS_MARKER_CONTENT = "# Written by `hicortex init` (self-hosted). Opt-in to the localhost auth\n" +
+    "# bypass. DELETE this file to require the bearer token on localhost too\n" +
+    "# (fail-closed). Hosted-mode (hostedMode:true) refuses to start with this\n" +
+    "# marker present — see specs/2026-07-27-hosted-service.md §2.\n";
+/**
+ * Resolve the marker file path for a given home dir. Defaults to the canonical
+ * Hicortex home (honors HICORTEX_HOME), so callers in tests can point the env
+ * override at a temp dir.
+ */
+function localhostBypassMarkerPath(home = (0, paths_js_1.hicortexHome)()) {
+    return (0, node_path_1.join)(home, exports.LOCALHOST_BYPASS_MARKER);
+}
+/**
+ * Does the localhost auth-bypass marker exist? Pure filesystem check — no
+ * logging, no side-effects. Used by both createAuthMiddleware (gates the
+ * bypass per-request via a boot-time capture in mcp-server.ts) and the
+ * hosted-mode boot assertion.
+ */
+function localhostBypassEnabled(home = (0, paths_js_1.hicortexHome)()) {
+    return (0, node_fs_1.existsSync)(localhostBypassMarkerPath(home));
+}
+/**
+ * Write the localhost auth-bypass marker file (self-hosted init only — never
+ * in hosted mode). Idempotent: overwrites an existing marker so a re-init
+ * refreshes the explanatory note. Ensures the parent dir exists. Does NOT
+ * touch auth or any other config — just the one marker file.
+ *
+ * Returns true when a NEW marker was created (for init's "✓" reporting), false
+ * when one already existed (refreshed in place).
+ */
+function writeLocalhostBypassMarker(home = (0, paths_js_1.hicortexHome)()) {
+    const markerPath = localhostBypassMarkerPath(home);
+    const existed = (0, node_fs_1.existsSync)(markerPath);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(markerPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(markerPath, exports.LOCALHOST_BYPASS_MARKER_CONTENT, { mode: 0o644 });
+    return !existed;
+}

package/dist/mcp-server.js

@@ -59,6 +59,10 @@ const db_js_1 = require("./db.js");
 const llm_js_1 = require("./llm.js");
 const features_js_1 = require("./features.js");
 const config_read_js_1 = require("./config-read.js");
+const localhost_bypass_js_1 = require("./localhost-bypass.js");
+const hosted_boot_js_1 = require("./hosted-boot.js");
+const token_budget_js_1 = require("./token-budget.js");
+const paths_js_1 = require("./paths.js");
 const state_js_1 = require("./state.js");
 const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
@@ -183,10 +187,10 @@ function createMcpServer() {
         }
     });
     // -- hicortex_ingest --
-    server.tool("hicortex_ingest", "Store a new memory in long-term storage. Use for important facts, decisions, or lessons.", {
+    server.tool("hicortex_ingest", "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.", {
         content: zod_1.z.string().describe("Memory content to store"),
         project: zod_1.z.string().optional().describe("Project this memory belongs to"),
-        memory_type: zod_1.z.enum(["episode", "lesson", "fact", "decision"]).optional().describe("Type of memory (default: episode)"),
+        memory_type: zod_1.z.enum(["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"]).optional().describe("Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term)."),
     }, async ({ content, project, memory_type }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
@@ -195,7 +199,8 @@ function createMcpServer() {
             const id = storage.insertMemory(db, content, embedding, {
                 sourceAgent: "claude-code/manual",
                 project,
-                memoryType: memory_type ?? "episode",
+                // Normalize legacy raw enum to the canonical term the DB stores.
+                memoryType: memory_type ? (0, type_labels_js_1.normalizeMemoryType)(memory_type) : "experience",
             });
             return { content: [{ type: "text", text: `Memory stored (id: ${id.slice(0, 8)})` }] };
         }
@@ -208,7 +213,7 @@ function createMcpServer() {
         id: zod_1.z.string().describe("Memory ID (from search results, first 8 chars or full UUID)"),
         content: zod_1.z.string().optional().describe("New content text"),
         project: zod_1.z.string().optional().describe("New project name"),
-        memory_type: zod_1.z.enum(["episode", "lesson", "fact", "decision"]).optional().describe("New memory type"),
+        memory_type: zod_1.z.enum(["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"]).optional().describe("New memory type. Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term)."),
     }, async ({ id, content, project, memory_type }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
@@ -222,8 +227,9 @@ function createMcpServer() {
                 fields.content = content;
             if (project !== undefined)
                 fields.project = project;
+            // Normalize legacy raw enum to canonical human terms before DB write.
             if (memory_type !== undefined)
-                fields.memory_type = memory_type;
+                fields.memory_type = (0, type_labels_js_1.normalizeMemoryType)(memory_type);
             if (Object.keys(fields).length === 0) {
                 return { content: [{ type: "text", text: "No fields to update" }], isError: true };
             }
@@ -319,7 +325,7 @@ function createMcpServer() {
         const moduleIndex = state.moduleIndex;
         if (moduleIndex && moduleIndex.domains.length > 0) {
             const text = moduleIndex.domains.map((d) => {
-                const head = `**${d.name}** (${d.memoryCount} memories, ${d.lessonCount} lessons)`;
+                const head = `**${d.name}** (${d.memoryCount} memories, ${d.lessonCount} Learnings)`;
                 // Content-based domains carry a description and no projects; legacy
                 // project-grouping domains carry a project list + keywords.
                 if (d.description && d.projects.length === 0) {
@@ -404,6 +410,59 @@ function createMcpServer() {
 async function startServer(options = {}) {
     const port = options.port ?? 8787;
     const host = options.host ?? "0.0.0.0";
+    // ---------------------------------------------------------------------------
+    // Hosted-mode boot gate (#110 §1-§2, #271 — Phase 0B).
+    //
+    // MUST run BEFORE resolveDbPath/initDb: in hosted mode with HICORTEX_DB_PATH
+    // set, the server must refuse the attacker-chosen DB location WITHOUT first
+    // touching it. The hosted signals (hostedMode from config, bypassMarkerPresent
+    // from the marker file) do NOT depend on the DB, so reading them now is safe.
+    // CR warning 3: this block was previously after initDb, letting a hostile
+    // HICORTEX_DB_PATH create/touch a file at the chosen path before the gate.
+    //
+    // CR warning 1: the marker is a HOME-level file (like config.json, written by
+    // init to HICORTEX_HOME). Read it from hicortexHome() — NOT stateDir, which
+    // is dirname(dbPath) and drifts when HICORTEX_DB_PATH relocates the DB. The
+    // config key hostedMode likewise lives at <hicortexHome>/config.json.
+    //
+    // Decision logic lives in hosted-boot.ts (pure, unit-tested); the side-effect
+    // (console.error + process.exit) is local to boot. The marker state is
+    // captured once here and reused below to gate the localhost bypass in
+    // createAuthMiddleware (no per-request stat). CR warning 4: the upgrade-path
+    // warning is decided by the pure shouldEmitBypassWarning helper (behavior-
+    // tested), not an inline branch.
+    const bootConfig = readConfigFile((0, paths_js_1.hicortexHome)());
+    const hostedMode = (0, config_read_js_1.readStrictBoolean)(bootConfig ?? {}, "hostedMode") === true;
+    let bypassMarkerPresent = (0, localhost_bypass_js_1.localhostBypassEnabled)();
+    const bootDecision = (0, hosted_boot_js_1.checkHostedBoot)({
+        hostedMode,
+        dbPathEnvSet: !!process.env.HICORTEX_DB_PATH,
+        bypassMarkerPresent,
+    });
+    if (!bootDecision.ok) {
+        console.error(bootDecision.message);
+        process.exit(1);
+    }
+    // Upgrade migration (CR S1): self-hosted server-mode CC MCP registration
+    // carries NO bearer token (init.ts:192 — only client-mode adds the header),
+    // so it relies entirely on the localhost bypass. An existing install that
+    // upgrades without re-running init has no marker → the bypass silently
+    // disappears → every server-mode CC MCP call 401s. Auto-write the marker on
+    // first post-upgrade boot in self-hosted mode to preserve the prior
+    // unconditional-bypass behaviour. Hosted mode is untouched: checkHostedBoot
+    // refuses to start with a marker present, so this block — gated on
+    // !hostedMode — never runs for a hosted tenant. bypassMarkerPresent is
+    // reassigned so createAuthMiddleware below gates the bypass for THIS boot
+    // too (the file write and the in-memory flag stay in sync).
+    if (!hostedMode && !bypassMarkerPresent) {
+        (0, localhost_bypass_js_1.writeLocalhostBypassMarker)((0, paths_js_1.hicortexHome)());
+        bypassMarkerPresent = true;
+        console.log("[hicortex] Localhost auth-bypass marker written (upgrade migration).");
+    }
+    const bypassWarning = (0, hosted_boot_js_1.shouldEmitBypassWarning)(hostedMode, bypassMarkerPresent);
+    if (bypassWarning) {
+        console.warn(bypassWarning);
+    }
     // Initialize core
     const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
     console.log(`[hicortex] Initializing database at ${dbPath}`);
@@ -429,6 +488,11 @@ async function startServer(options = {}) {
         const { agentId } = (0, init_js_1.ensureAndPersistAgentId)((0, node_path_1.join)(stateDir, "config.json"));
         savedConfig.agentId = agentId;
     }
+    // #5: token-budget enforcement. Mode-agnostic — gates on cap > 0. Self-hosted
+    // uses config llmTokensPerMonth (default 0 = off); hosted uses HICORTEX_TOKEN_CAP
+    // env (provider-set, tenant-immutable) which takes precedence. Initialised here
+    // (after stateDir + savedConfig are known) so the warn-dedup can seed from state.
+    (0, token_budget_js_1.initTokenBudget)(stateDir, savedConfig?.llmTokensPerMonth);
     if (savedConfig?.llmBackend === "claude-cli") {
         const claudePath = (0, llm_js_1.findClaudeBinary)();
         if (claudePath) {
@@ -613,7 +677,7 @@ 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, authTokenPrevious));
+    app.use((0, viz_js_1.createAuthMiddleware)(authToken, authTokenPrevious, bypassMarkerPresent));
     // SSE transport management — each connection gets its own McpServer instance
     const transports = new Map();
     // Health endpoint — PUBLIC minimal probe. Unauthenticated (the auth
@@ -692,11 +756,15 @@ async function startServer(options = {}) {
             res.status(400).json({ error: "Missing or invalid 'content' field" });
             return;
         }
-        const validTypes = ["episode", "lesson", "fact", "decision"];
+        const validTypes = type_labels_js_1.ACCEPTED_MEMORY_TYPES;
         if (memory_type && !validTypes.includes(memory_type)) {
             res.status(400).json({ error: `Invalid memory_type: ${memory_type}` });
             return;
         }
+        // Normalize legacy raw enum (fact/episode/decision/lesson) to the
+        // canonical term the DB stores (knowledge/experience/decisions/learnings).
+        // Canonical values pass through unchanged.
+        const normalizedType = memory_type ? (0, type_labels_js_1.normalizeMemoryType)(memory_type) : memory_type;
         // Dedup by source_session (idempotent — skip if already ingested)
         if (source_session) {
             const existing = db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE source_session = ?").get(source_session);
@@ -714,7 +782,7 @@ async function startServer(options = {}) {
                 sourceDomain: typeof source_domain === "string" ? source_domain : null,
                 sourceSession: source_session ?? undefined,
                 project: project ?? undefined,
-                memoryType: memory_type ?? "episode",
+                memoryType: normalizedType ?? "experience",
                 // 0.16.x: privacy defaults to null (vestigial column). A legacy client
                 // that sends an explicit value is honored; absent → null.
                 privacy: typeof privacy === "string" ? privacy : null,
@@ -1021,12 +1089,27 @@ async function startServer(options = {}) {
         const sourcePrefix = session_id
             ? `${session_id}${segment_id ? `#${segment_id}` : ""}`
             : undefined;
+        // #5: declared outside the try so the finally can record tokens spent even
+        // when distillSession throws partway through (the LLM calls already happened).
+        let distillUsage = { prompt: 0, completion: 0, total: 0 };
         try {
+            // #5: token-budget gate — refuse (429) BEFORE the LLM call if the tenant is
+            // already at/over the monthly cap. Placed after the dedup short-circuits so
+            // a skipped duplicate neither trips the gate nor consumes budget. The client
+            // capture loop holds its cursor on 429 (dup-over-loss, capture.ts:303).
+            if ((0, token_budget_js_1.isTokenBudgetExceeded)(stateDir)) {
+                res.status(429).json({ error: "token budget exceeded", retry: "next billing period" });
+                return;
+            }
             // Collect gate-dropped entries so they can ride back in the response and
             // land in the caller's file-persisted nightly log (#156 audit trail); the
             // server-side per-entry console.log in distillChunk stays as well.
             const dropped = [];
-            const entries = await (0, distiller_js_1.distillSession)(llm, conversationText, project ?? "unknown", date, chunkSize, dropped);
+            const entries = await (0, distiller_js_1.distillSession)(llm, conversationText, project ?? "unknown", date, chunkSize, dropped, (u) => {
+                distillUsage.prompt += u.prompt_tokens ?? 0;
+                distillUsage.completion += u.completion_tokens ?? 0;
+                distillUsage.total += u.total_tokens ?? 0;
+            });
             // Phase 1 — embed every chunk up front (async). If ANY embed fails we
             // never reach the insert, so nothing is stored.
             const createdAt = new Date(date).toISOString();
@@ -1061,9 +1144,9 @@ async function startServer(options = {}) {
                         sourceSession: sourcePrefix ? `${sourcePrefix}#${i}` : undefined,
                         project: project ?? undefined,
                         // #216: the distiller now classifies each entry as
-                        // episode/fact/decision via the [E]/[F]/[D] tag parsed in
+                        // experience/knowledge/decisions via the [E]/[K]/[D] tag parsed in
                         // distiller.ts. Pre-#216 distiller output (no tag) defaults to
-                        // episode in the parser, so this is backward compatible.
+                        // experience in the parser, so this is backward compatible.
                         memoryType,
                         // 0.16.x: privacy defaults to null (vestigial column). A legacy
                         // client that sends an explicit value is honored; absent → null.
@@ -1084,6 +1167,14 @@ async function startServer(options = {}) {
             res.status(500).json({ error: "Distillation failed" });
             console.error(`[hicortex] /distill: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
         }
+        finally {
+            // #5: record tokens spent against the monthly budget — in finally so a
+            // mid-distil throw (some chunks' LLM calls already happened) still counts.
+            // No-op when cap=0 (enforcement off) or distillUsage.total=0 (gate refused
+            // / no chunk reached an LLM call).
+            if (distillUsage.total > 0)
+                (0, token_budget_js_1.recordDistillUsage)(stateDir, distillUsage);
+        }
     });
     // -------------------------------------------------------------------------
     // REST /update — update a memory (and re-embed when content changes).
@@ -1111,19 +1202,24 @@ async function startServer(options = {}) {
             fields.content = content;
         if (project !== undefined)
             fields.project = project;
-        if (memory_type !== undefined)
-            fields.memory_type = memory_type;
         if (privacy !== undefined)
             fields.privacy = privacy;
-        if (Object.keys(fields).length === 0) {
-            res.status(400).json({ error: "No fields to update" });
-            return;
-        }
-        const validTypes = ["episode", "lesson", "fact", "decision"];
+        // Validate + normalize memory_type BEFORE adding to `fields` so the
+        // empty-fields check below correctly counts a memory_type-only update.
+        const validTypes = type_labels_js_1.ACCEPTED_MEMORY_TYPES;
         if (memory_type !== undefined && !validTypes.includes(memory_type)) {
             res.status(400).json({ error: `Invalid memory_type: ${memory_type}` });
             return;
         }
+        // Normalize legacy raw enum (fact/episode/decision/lesson) to the
+        // canonical term the DB stores (knowledge/experience/decisions/learnings).
+        // Canonical values pass through unchanged.
+        if (memory_type !== undefined)
+            fields.memory_type = (0, type_labels_js_1.normalizeMemoryType)(memory_type);
+        if (Object.keys(fields).length === 0) {
+            res.status(400).json({ error: "No fields to update" });
+            return;
+        }
         try {
             storage.updateMemory(db, fullId, fields);
             // Re-embed when content changes

package/dist/prompts.js

@@ -48,7 +48,7 @@ function reflection(memoriesBlock, recentLessons) {
 Like human learning: we grow fastest when we reinforce what works AND correct what doesn't. A system that only learns from mistakes becomes overly cautious. A system that only learns from successes never improves. The combination multiplies.
 
 GENERALITY BAR (read carefully — the most important rule):
-Every lesson MUST be a generalizable operating principle that transfers across contexts, agents, and projects. It is NOT: an incident report, a changelog entry, a one-event fact, a tool-specific recipe, or a note about a named entity. If a memory is only interesting as "what happened today", it is an EPISODE — do not emit a lesson for it. Abstract away specific tool names, hostnames, and incident details from the lesson text; state the transferable rule.
+Every lesson MUST be a generalizable operating principle that transfers across contexts, agents, and projects. It is NOT: an incident report, a changelog entry, a one-event fact, a tool-specific recipe, or a note about a named entity. If a memory is only interesting as "what happened today", it is an EXPERIENCE — do not emit a lesson for it. Abstract away specific tool names, hostnames, and incident details from the lesson text; state the transferable rule.
 
 Quality over quantity. 1-3 lessons is typical. An empty array [] is the CORRECT response when memories show routine competent work without noteworthy patterns, surprises, or friction. Do not manufacture lessons from nothing.
 
@@ -121,8 +121,8 @@ EXTRACT into this markdown format:
 ### Decisions Made
 - [D] [SUBJECT]: [decision] — [reasoning] (${date})
 
-### Facts Learned
-- [F] [SUBJECT]: [fact] — [context/source] (${date})
+### Knowledge Learned
+- [K] [SUBJECT]: [knowledge] — [context/source] (${date})
 
 ### Problems & Solutions
 - [E] [SUBJECT]: [problem] → [solution that worked] (${date})
@@ -131,7 +131,7 @@ EXTRACT into this markdown format:
 - [D] [SUBJECT]: [what changed], [from → to] (${date})
 
 ### Key Entities & Relationships
-- [F] [entity A] → [relationship] → [entity B] (${date})
+- [K] [entity A] → [relationship] → [entity B] (${date})
 
 ### Corrections & Rejections
 - [E] [SUBJECT]: [what AI proposed] → [why rejected/corrected] → [what user wanted instead] (${date})
@@ -139,18 +139,18 @@ EXTRACT into this markdown format:
    user corrections of AI assumptions, quality complaints like "too verbose")
 
 TYPE TAG (critical — prefix EVERY bullet with exactly one letter + space):
-- [E] EPISODE — a specific event, interaction, or narrative: "tried X, failed
+- [E] EXPERIENCE — a specific event, interaction, or narrative: "tried X, failed
   because Y", a correction, a debugging session, a one-time occurrence. The
   DEFAULT when in doubt.
-- [F] FACT — a durable truth that will hold across sessions: "the API is at
+- [K] KNOWLEDGE — a durable truth that will hold across sessions: "the API is at
   :8787", "uv is used for packages", "config lives in ~/.hicortex/". Not tied
   to a single moment.
-- [D] DECISION — a choice made that future work builds on, and that a later
+- [D] DECISIONS — a choice made that future work builds on, and that a later
   decision can SUPERSEDE: "switched from gemma4 to qwen3.5", "adopted the
-  graded-schema tag model". Not a fact (it can change) and not an episode
+  graded-schema tag model". Not knowledge (it can change) and not experience
   (it persists and constrains).
-- NEVER use [L] (lesson). Lessons are extracted by a SEPARATE reflection stage,
-  not here. If the model emits [L], it is wrong — re-tag as episode/fact/decision.
+- NEVER use [L] (learnings). Learnings are extracted by a SEPARATE reflection stage,
+  not here. If the model emits [L], it is wrong — re-tag as experience/knowledge/decisions.
 The type tag goes BEFORE the subject, never as a section/category bracket.
 
 TOPIC-FIRST RULE (critical — read carefully):
@@ -159,8 +159,8 @@ concrete thing it is about — the system, file, component, decision area, or
 entity. The subject is what a future reader would search for.
 - Write:  "[E] Electrical load calculation: don't bundle unknown loads into one figure — user rejected the estimate"
 - NOT:    "[E] User rejected AI's bundling of unknown loads"
-- Write:  "[F] Nightly capture (Hermes): cron sessions are excluded — source='cron' is skipped before distillation"
-- NOT:    "[F] Discovered that cron sessions are filtered out"
+- Write:  "[K] Nightly capture (Hermes): cron sessions are excluded — source='cron' is skipped before distillation"
+- NOT:    "[K] Discovered that cron sessions are filtered out"
 Reason: each item's first words (after the type tag) become the memory's one-line
 index entry AND dominate its search embedding. An item that opens with a category
 label, a sentiment ("Strong Negative"), or "User rejected…" is unfindable — it