@gamaze/hicortex 0.18.2 → 0.18.3

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

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,7 +263,7 @@ 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) {
@@ -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")) {

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/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`,

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/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"));
@@ -406,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}`);
@@ -431,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) {
@@ -615,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
@@ -1027,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();
@@ -1090,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).

package/dist/token-budget.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve the effective cap: env (HICORTEX_TOKEN_CAP) takes precedence over the
+ * config key. A positive, finite env wins; otherwise the config value (0/absent
+ * = unlimited). Pure — exported for tests.
+ */
+export declare function resolveTokenCap(configCap: unknown): number;
+/**
+ * Initialise at server boot (after stateDir is known). Resolves + caches the cap
+ * and seeds the 80%-warn dedup so a restart mid-period doesn't re-warn.
+ */
+export declare function initTokenBudget(stateDir: string, configCap: unknown): void;
+/** The resolved monthly cap (0 = unlimited / enforcement off). */
+export declare function getTokenCap(): number;
+/**
+ * Pre-call check for /distill: refuse (429) when the tenant is already at/over
+ * the monthly cap. Reuses `shouldThrottleTokens(cap, period, 0)` — lastRunTokens
+ * is 0 because we cannot predict a call's cost before making it, so this refuses
+ * only when already over (a tenant exactly at the cap is refused on the next
+ * call). Reads state.json fresh so the nightly process's writes are reflected.
+ */
+export declare function isTokenBudgetExceeded(stateDir: string): boolean;
+/**
+ * After a successful distill, add the consumed tokens to the monthly counter and
+ * emit the 80% warning once per period. Synchronous read-modify-write via
+ * `updateState` (serializes concurrent in-process /distill; picks up the nightly
+ * process's writes via the fresh read). Accumulates the full breakdown
+ * (prompt/completion/total) so the dashboard's prompt+completion stays
+ * consistent with total (distill + consolidation).
+ */
+export declare function recordDistillUsage(stateDir: string, usage: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): void;

package/dist/token-budget.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenCap = resolveTokenCap;
+exports.initTokenBudget = initTokenBudget;
+exports.getTokenCap = getTokenCap;
+exports.isTokenBudgetExceeded = isTokenBudgetExceeded;
+exports.recordDistillUsage = recordDistillUsage;
+/**
+ * Per-tenant monthly token-budget enforcement (#110 Phase 0B item #5).
+ *
+ * Limits LLM token consumption over /distill (the cost-generating path the
+ * nightly consolidation throttle did NOT cover). Mode-agnostic — gates on
+ * `cap > 0`, never on `hostedMode`:
+ *   - Self-hosted: the cap is the operator's own `llmTokensPerMonth` config
+ *     (default 0 = unlimited → never throttles). Protects the operator's wallet
+ *     from a runaway nightly on an expensive model.
+ *   - Hosted: the cap is provider-set via the `HICORTEX_TOKEN_CAP` env, which
+ *     takes PRECEDENCE over config. The tenant process cannot mutate boot-time
+ *     env, so a hosted tenant cannot raise its own cap (the config.json
+ *     self-edit loophole is closed). Protects the provider's wallet.
+ *
+ * Reuses the existing machinery: `shouldThrottleTokens` (consolidate.ts) for the
+ * decision (incl. monthly reset), and `llmTokensThisPeriod` + `updateState`
+ * (state.ts) for the counter + atomic persistence.
+ *
+ * Concurrency: state.json is read fresh for each check and written via
+ * `updateState` (a synchronous read-modify-write; Node's single thread
+ * serializes concurrent /distill calls within the server process, so no
+ * in-process tally is needed). The nightly consolidation is a SEPARATE process
+ * that also writes state.json; a rare cross-process write collision can lose a
+ * small increment — negligible on a multi-million-token monthly budget. A
+ * DB-backed counter (WAL transactions serialize across processes) is the future
+ * hardening if it ever matters.
+ */
+const state_js_1 = require("./state.js");
+const consolidate_js_1 = require("./consolidate.js");
+/** Env override (hosted: provider-set, tenant-immutable at runtime). */
+const TOKEN_CAP_ENV = "HICORTEX_TOKEN_CAP";
+let cap = 0;
+/** periodStart we last emitted the 80% warning at, to dedup within a period. */
+let warnedPeriod = null;
+/**
+ * Resolve the effective cap: env (HICORTEX_TOKEN_CAP) takes precedence over the
+ * config key. A positive, finite env wins; otherwise the config value (0/absent
+ * = unlimited). Pure — exported for tests.
+ */
+function resolveTokenCap(configCap) {
+    const envCap = Number(process.env[TOKEN_CAP_ENV]);
+    if (Number.isFinite(envCap) && envCap > 0)
+        return envCap;
+    const cfg = Number(configCap);
+    return Number.isFinite(cfg) && cfg > 0 ? cfg : 0;
+}
+/**
+ * Initialise at server boot (after stateDir is known). Resolves + caches the cap
+ * and seeds the 80%-warn dedup so a restart mid-period doesn't re-warn.
+ */
+function initTokenBudget(stateDir, configCap) {
+    cap = resolveTokenCap(configCap);
+    if (cap > 0) {
+        const p = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+        warnedPeriod = p && p.total >= cap * 0.8 ? (p.periodStart ?? null) : null;
+        // Label the source truthfully: only claim env if the env value was actually
+        // used (a malformed env falls back to config, so the label must not lie).
+        const fromEnv = Number(process.env[TOKEN_CAP_ENV]) === cap;
+        console.log(`[hicortex] Token budget: ${cap.toLocaleString()}/month${fromEnv ? " (HICORTEX_TOKEN_CAP)" : ""}`);
+    }
+}
+/** The resolved monthly cap (0 = unlimited / enforcement off). */
+function getTokenCap() {
+    return cap;
+}
+/**
+ * Pre-call check for /distill: refuse (429) when the tenant is already at/over
+ * the monthly cap. Reuses `shouldThrottleTokens(cap, period, 0)` — lastRunTokens
+ * is 0 because we cannot predict a call's cost before making it, so this refuses
+ * only when already over (a tenant exactly at the cap is refused on the next
+ * call). Reads state.json fresh so the nightly process's writes are reflected.
+ */
+function isTokenBudgetExceeded(stateDir) {
+    if (cap <= 0)
+        return false;
+    const period = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+    return (0, consolidate_js_1.shouldThrottleTokens)(cap, period, 0).throttle;
+}
+/**
+ * After a successful distill, add the consumed tokens to the monthly counter and
+ * emit the 80% warning once per period. Synchronous read-modify-write via
+ * `updateState` (serializes concurrent in-process /distill; picks up the nightly
+ * process's writes via the fresh read). Accumulates the full breakdown
+ * (prompt/completion/total) so the dashboard's prompt+completion stays
+ * consistent with total (distill + consolidation).
+ */
+function recordDistillUsage(stateDir, usage) {
+    if (cap <= 0 || usage.total <= 0)
+        return;
+    let newTotal = 0;
+    let periodStart = "";
+    (0, state_js_1.updateState)((s) => {
+        const prev = s.llmTokensThisPeriod;
+        // Monthly reset (year+month) — matches shouldThrottleTokens's staleness check.
+        const stale = !prev?.periodStart ||
+            new Date(prev.periodStart).getUTCFullYear() !== new Date().getUTCFullYear() ||
+            new Date(prev.periodStart).getUTCMonth() !== new Date().getUTCMonth();
+        if (stale) {
+            s.llmTokensThisPeriod = {
+                prompt: usage.prompt,
+                completion: usage.completion,
+                total: usage.total,
+                periodStart: new Date().toISOString(),
+            };
+        }
+        else {
+            const base = prev;
+            s.llmTokensThisPeriod = {
+                prompt: (base.prompt ?? 0) + usage.prompt,
+                completion: (base.completion ?? 0) + usage.completion,
+                total: (base.total ?? 0) + usage.total,
+                periodStart: base.periodStart,
+            };
+        }
+        newTotal = s.llmTokensThisPeriod.total;
+        periodStart = s.llmTokensThisPeriod.periodStart;
+    }, stateDir);
+    // 80% warning — dedup per period (once per month per threshold crossing).
+    if (periodStart && warnedPeriod !== periodStart && newTotal >= cap * 0.8) {
+        warnedPeriod = periodStart;
+        const pct = Math.round((newTotal / cap) * 100);
+        console.warn(`[hicortex] Token usage at ${pct}% of monthly cap (${newTotal.toLocaleString()}/${cap.toLocaleString()}).`);
+    }
+}

package/dist/types.d.ts

@@ -412,6 +412,15 @@ export interface HicortexConfig {
      * so these were not surfacing in the top-k anyway).
      */
     memorySoftCap?: number;
+    /**
+     * Hosted-service mode (issue #110, #271 — spec 2026-07-27 §1-§2). When true,
+     * the server enforces hosted-tenant constraints at boot: it refuses to start
+     * if `HICORTEX_DB_PATH` is set (path-override attacks) or if the localhost
+     * auth-bypass marker file is present (hosted must be fail-closed — no bypass).
+     * Absent/false (the self-hosted default) → the assertions never fire and
+     * behaviour is unchanged. Read at server boot via readStrictBoolean.
+     */
+    hostedMode?: boolean;
     /**
      * Monthly fair-use ceiling on consolidation LLM token consumption (#246).
      * Default `0` = unlimited (the self-hosted default — no cap, never throttled).

package/dist/viz.d.ts

@@ -45,8 +45,16 @@ export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
  * 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.
+ *
+ * `allowLocalhostBypass` (0.18, #110 §2/#271): when false (or omitted), the
+ * localhost bypass is DISABLED — localhost connections need the bearer token
+ * like any other (fail-closed). When true, localhost loopback (127.0.0.1,
+ * ::1, ::ffff:127.0.0.1) bypasses auth as before. The marker file
+ * `~/.hicortex/.allow-localhost-bypass` (written by self-hosted init) gates
+ * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
+ * the marker state once at boot and passes it in (no per-request stat).
  */
-export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string): express.RequestHandler;
+export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string, allowLocalhostBypass?: boolean): 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.

package/dist/viz.js

@@ -92,9 +92,18 @@ function safeBearerMatch(headerValue, expectedToken) {
  * 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.
+ *
+ * `allowLocalhostBypass` (0.18, #110 §2/#271): when false (or omitted), the
+ * localhost bypass is DISABLED — localhost connections need the bearer token
+ * like any other (fail-closed). When true, localhost loopback (127.0.0.1,
+ * ::1, ::ffff:127.0.0.1) bypasses auth as before. The marker file
+ * `~/.hicortex/.allow-localhost-bypass` (written by self-hosted init) gates
+ * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
+ * the marker state once at boot and passes it in (no per-request stat).
  */
-function createAuthMiddleware(authToken, authTokenPrevious) {
+function createAuthMiddleware(authToken, authTokenPrevious, allowLocalhostBypass) {
     const previous = authTokenPrevious && authTokenPrevious.length > 0 ? authTokenPrevious : undefined;
+    const bypassEnabled = allowLocalhostBypass === true;
     return (req, res, next) => {
         if (req.path === "/health")
             return next();
@@ -142,7 +151,7 @@ function createAuthMiddleware(authToken, authTokenPrevious) {
                 return next();
         }
         const ip = req.ip ?? req.socket.remoteAddress ?? "";
-        if (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1")
+        if (bypassEnabled && (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1"))
             return next();
         // Constant-time bearer check (#254). When authTokenPrevious is set, BOTH
         // tokens are compared every request (no short-circuit) so timing cannot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "Persistent agent identity for AI agents — a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {