@gamaze/hicortex 0.18.2 → 0.19.0

package/dist/dashboard.d.ts

@@ -42,12 +42,21 @@ export interface DashboardMetrics {
          *  cap; undefined on backfill rows (a stage outcome, not reconstructable). */
         evicted?: number;
         /**
-         * Total LLM tokens consumed by this run's consolidation (#246). Undefined
-         * in lockstep with `tokens_by_stage` (and on backfill rows, which can't
-         * reconstruct a per-run meter).
+         * Total LLM tokens consumed by this run (#246 consolidation meter; #287
+         * widened to the TRUE total — distill + consolidation). Undefined in
+         * lockstep with `tokens_by_stage` (and on backfill rows, which can't
+         * reconstruct a per-run meter). Older snapshots are consolidation-only:
+         * historical rows can't be reconstructed, which is accepted (#287).
+         * Inherent under-count, same acceptance: attribution is response-based,
+         * so tokens a FAILED distill already spent (500 after spend, response
+         * lost after commit) reach the monthly meter but never a run's total —
+         * after such a night, the month's bars sum slightly below the headline.
          */
         tokens?: number;
-        /** Per-stage breakdown of `tokens` (#246). Undefined on backfill rows. */
+        /**
+         * Per-stage breakdown of `tokens` (#246; #287 adds a `distill` entry for
+         * capture-time distillation). Undefined on backfill rows.
+         */
         tokens_by_stage?: Record<string, {
             prompt: number;
             completion: number;
@@ -79,6 +88,19 @@ export interface DashboardMetrics {
          * shape is clean on healthy runs.
          */
         budget_deferred_by_stage?: Record<string, number>;
+        /**
+         * #6 backup stage outcome (Phase 0B). Present whenever the backup stage
+         * ran (full nightly); absent on capture-only / dry-run / backfill rows.
+         * `ok` is false when the snapshot OR the operator's offsite hook failed —
+         * the page flags a night the offsite copy didn't land. `bytes` is the
+         * compressed artifact size; `path` is the on-disk artifact (for "where
+         * did the last backup land?" debugging — not a restore button).
+         */
+        backup?: {
+            ok: boolean;
+            bytes: number;
+            path?: string;
+        };
     };
     /** Corpus capacity (#245). `memory_soft_cap` is the configured ceiling (0 =
      *  disabled); always present in real snapshots, undefined on backfilled
@@ -102,6 +124,17 @@ export interface DashboardSnapshot {
 }
 /** The /dashboard/data response — the full payload the page renders. */
 export interface DashboardData {
+    /**
+     * Account identity (hosted): who the viewer is, so a user holding two
+     * tenant tokens can tell whose data the page shows. Each field is null when
+     * its config key (displayName/orgName/planLabel) is absent — the page
+     * renders nothing when ALL are null (the self-hosted default).
+     */
+    account: {
+        name: string | null;
+        org: string | null;
+        plan: string | null;
+    };
     headline: {
         total_memories: number;
         uses_per_showing: number | null;
@@ -149,9 +182,10 @@ export interface DashboardData {
             supersession: number;
             added: number;
             evicted?: number;
-            /** Total tokens consumed that run (#246). Undefined = no metered run. */
+            /** Total tokens consumed that run (#246; #287: distill + consolidation).
+             *  Undefined = no metered run. */
             tokens?: number;
-            /** Per-stage breakdown of `tokens` (#246). */
+            /** Per-stage breakdown of `tokens` (#246; #287 adds `distill`). */
             tokens_by_stage?: Record<string, {
                 prompt: number;
                 completion: number;
@@ -207,6 +241,19 @@ export interface NightlyDelta {
         completion: number;
         total: number;
     }>;
+    /**
+     * Distill tokens metered by the daemon across this run's capture POSTs
+     * (#287) — summed from the /distill responses by the capture loop. Merged
+     * into the snapshot so `new_this_run.tokens` is the run's TRUE total
+     * (distill + consolidation) and `distill` joins `tokens_by_stage`. Zero
+     * (a daemon predating the usage field, or nothing distilled) is a no-op:
+     * the row keeps its consolidation-only shape.
+     */
+    distillUsage?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
     /**
      * Always-on consolidation-budget usage (#255 CR). Forwarded whenever
      * consolidation ran so the dashboard renders a continuous used/max bar.
@@ -227,6 +274,15 @@ export interface NightlyDelta {
      * with `budgetExhausted`.
      */
     budgetDeferredByStage?: Record<string, number>;
+    /**
+     * #6 backup stage (Phase 0B). Hoisted from the nightly backup block. Present
+     * whenever the backup stage ran (full nightly); undefined on capture-only /
+     * dry-run. `backupOk` flips to false on snapshot OR hook failure so the
+     * digest can flag a night the offsite copy didn't land.
+     */
+    backupPath?: string;
+    backupBytes?: number;
+    backupOk?: boolean;
 }
 /**
  * Write one snapshot row for `runAt` (an ISO timestamp the caller chooses —
@@ -286,3 +342,12 @@ export declare function handleDashboardData(db: Database.Database, query: {
  * Failures surface as a 500 with the usual {error} shape — no silent degrade.
  */
 export declare function dashboardDataHandler(getDb: () => Database.Database, getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;
+/**
+ * Express adapter for GET /account — the account identity ONLY (name/org/plan
+ * from config), so the /viz and /identity/ui pages can render the nav account
+ * element without pulling the full /dashboard/data payload. Same readAccount()
+ * construction as the dashboard payload — one shape, two surfaces. Also the
+ * natural whoami for the future OAuth session (#292). Failures surface as a
+ * 500 with the usual {error} shape (same as dashboardDataHandler).
+ */
+export declare function accountHandler(getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;

package/dist/dashboard.js

@@ -25,6 +25,7 @@ exports.writeSnapshot = writeSnapshot;
 exports.backfillSnapshots = backfillSnapshots;
 exports.handleDashboardData = handleDashboardData;
 exports.dashboardDataHandler = dashboardDataHandler;
+exports.accountHandler = accountHandler;
 const recall_index_js_1 = require("./recall-index.js");
 const config_read_js_1 = require("./config-read.js");
 const consolidate_js_1 = require("./consolidate.js");
@@ -92,17 +93,36 @@ function computeDashboardMetrics(db) {
  */
 function writeSnapshot(db, runAt, delta, memorySoftCap) {
     const metrics = computeDashboardMetrics(db);
+    // #287: merge the run's two meters into the customer-facing total. `tokens`
+    // = consolidation (tokensThisRun) + distill (distillUsage.total); the distill
+    // share joins the stage map under its own key. Both fields stay in lockstep —
+    // emitted when EITHER phase metered, omitted when neither did (the page
+    // treats undefined as "no data for this day"). A zero/absent distillUsage
+    // (old daemon, nothing distilled) changes nothing: tokens/tokens_by_stage
+    // come through exactly as the consolidation report produced them.
+    const hasDistill = (delta.distillUsage?.total ?? 0) > 0;
+    const metered = delta.tokensThisRun !== undefined || hasDistill;
+    const mergedTokens = metered
+        ? (delta.tokensThisRun ?? 0) + (hasDistill ? delta.distillUsage.total : 0)
+        : undefined;
+    const mergedStages = metered
+        ? { ...(delta.tokensByStage ?? {}), ...(hasDistill ? { distill: delta.distillUsage } : {}) }
+        : undefined;
+    // Shape fidelity: `tokens_by_stage` with zero keys never existed pre-#287
+    // (the key was simply absent) — keep it that way so consumers that treat
+    // "present" as "has a breakdown" stay right.
+    const emitStages = mergedStages && Object.keys(mergedStages).length > 0 ? mergedStages : undefined;
     metrics.new_this_run = {
         added: delta.added,
         lessonsGenerated: delta.lessonsGenerated,
         dedup: delta.dedup,
         supersession: delta.supersession,
         evicted: delta.evicted,
-        // #246: forward only when consolidation actually metered tokens this run.
-        // Absent on capture-only / throttled / no-LLM / no-metered-call runs — the
-        // page treats undefined as "no data for this day", matching adoption.
-        ...(delta.tokensThisRun !== undefined ? { tokens: delta.tokensThisRun } : {}),
-        ...(delta.tokensByStage !== undefined ? { tokens_by_stage: delta.tokensByStage } : {}),
+        // #246: forward only when a phase actually metered tokens this run. Absent
+        // on capture-only / throttled / no-LLM / no-metered-call runs — the page
+        // treats undefined as "no data for this day", matching adoption.
+        ...(mergedTokens !== undefined ? { tokens: mergedTokens } : {}),
+        ...(emitStages !== undefined ? { tokens_by_stage: emitStages } : {}),
         // #255 CR: always-on usage metric — forward calls_used + max_calls
         // whenever consolidation ran (regardless of exhaustion) so the page can
         // render a continuous used/max bar. Presence = a run happened; absence =
@@ -121,6 +141,17 @@ function writeSnapshot(db, runAt, delta, memorySoftCap) {
                     : {}),
             }
             : {}),
+        // #6 backup stage — forwarded as a nested object only when the stage ran
+        // (backupOk !== undefined). Absent on capture-only / dry-run / backfill.
+        ...(delta.backupOk !== undefined
+            ? {
+                backup: {
+                    ok: delta.backupOk === true,
+                    bytes: delta.backupBytes ?? 0,
+                    ...(delta.backupPath ? { path: delta.backupPath } : {}),
+                },
+            }
+            : {}),
     };
     if (memorySoftCap !== undefined) {
         metrics.capacity = { memory_soft_cap: memorySoftCap };
@@ -418,8 +449,9 @@ function handleDashboardData(db, query, config) {
             supersession: dayMetrics?.new_this_run?.supersession ?? supersessionCount,
             added: dayMetrics?.new_this_run?.added ?? sampleRows.length,
             evicted: dayMetrics?.new_this_run?.evicted,
-            // #246: only present when the day's nightly metered tokens. Both fields
-            // are forwarded together — the page renders either the breakdown or nothing.
+            // #246/#287: only present when the day's nightly metered tokens (distill
+            // or consolidation). Both fields are forwarded together — the page
+            // renders either the breakdown or nothing.
             tokens: dayMetrics?.new_this_run?.tokens,
             tokens_by_stage: dayMetrics?.new_this_run?.tokens_by_stage,
             // #255 CR: always-on usage metric — present whenever consolidation ran
@@ -441,6 +473,10 @@ function handleDashboardData(db, query, config) {
     return {
         status: 200,
         body: {
+            // Account identity — read defensively like the numeric knobs above:
+            // null when absent/not a string (page renders nothing, never "null").
+            // Shared readAccount() so GET /account renders the identical shape.
+            account: (0, config_read_js_1.readAccount)(config),
             range: rangeParam,
             headline,
             series,
@@ -469,3 +505,21 @@ function dashboardDataHandler(getDb, getConfig) {
         }
     };
 }
+/**
+ * Express adapter for GET /account — the account identity ONLY (name/org/plan
+ * from config), so the /viz and /identity/ui pages can render the nav account
+ * element without pulling the full /dashboard/data payload. Same readAccount()
+ * construction as the dashboard payload — one shape, two surfaces. Also the
+ * natural whoami for the future OAuth session (#292). Failures surface as a
+ * 500 with the usual {error} shape (same as dashboardDataHandler).
+ */
+function accountHandler(getConfig) {
+    return (_req, res) => {
+        try {
+            res.status(200).json({ account: (0, config_read_js_1.readAccount)(getConfig()) });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+}

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