@gamaze/hicortex 0.20.7 → 0.20.10

package/dist/eval/ranking-fixtures.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Planted ranking fixtures for the search-trust calibration gate (#425).
+ *
+ * Two fixture cases, both shaped like the field failure that opened the
+ * issue (the owner's live console test, 2026-09-13): a user searches a
+ * DISTINCTIVE PROPER NOUN they know exists; the one memory carrying that
+ * token has the best similarity of all candidates AND the literal FTS hit,
+ * yet ranks behind hardened but less-relevant memories that win on
+ * effective strength + graph connections.
+ *
+ *   (a) sirnas_exact_match — the AC1 fixture: a low-strength, unlinked,
+ *       never-accessed memory carrying an invented proper noun against
+ *       base-≥0.9 rivals with links among themselves, access history, and
+ *       older creation dates. The rivals share the query's DOMAIN
+ *       vocabulary (harbours, docks, boats) but never the proper noun.
+ *       Declared expectation: the proper-noun row ranks #1.
+ *   (b) no_match_control — the AC2 fixture: a "mamma"-class query with no
+ *       relevant match and NO FTS hits anywhere in the corpus. Whatever
+ *       nearest-neighbor junk vector search returns must be byte-stable
+ *       under the ranking work (no both-channel candidates exist, so the
+ *       boost can never fire — the case pins that the no-regression
+ *       guarantee is structural, not lucky).
+ *
+ * Honesty rules (the planted-pairs #393 A discipline):
+ *  - The texts are synthetic and generic (this package publishes to npm —
+ *    no real infrastructure, people, or fleet detail), but SHAPED like the
+ *    field failure: the proper noun is invented (it must appear nowhere
+ *    else — verified by an invariant test), the rivals are hardened with
+ *    metadata the production pipeline itself writes (base strength, access
+ *    hardening, link counts).
+ *  - Similarities are MEASURED at run time with the real bge-small-en-v1.5
+ *    embedder (ranking-eval.ts) — never asserted into existence. The
+ *    declared expectation is about ORDER under the shipped ranking, and
+ *    the report prints the measured similarity/score of every top row.
+ *  - Strength metadata is written through the production helpers
+ *    (insertMemory + updateMemory + addLink), not hand-rolled SQL, so the
+ *    fixture exercises the same rows retrieval() will see.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REAL_SIRNAS_MEMORY_ID = exports.NO_MATCH_FIXTURE = exports.SIRNAS_FIXTURE = exports.RANKING_SOURCE_AGENT = exports.RANKING_PROJECT = void 0;
+exports.checkFixtureInvariants = checkFixtureInvariants;
+/** All planted rows share project + source_agent (metadata never refuses). */
+exports.RANKING_PROJECT = "ranking-eval";
+exports.RANKING_SOURCE_AGENT = "ranking-eval";
+// ---------------------------------------------------------------------------
+// Case 1 — sirnas_exact_match (AC1)
+// ---------------------------------------------------------------------------
+//
+// The target mirrors the field case's SHAPE with invented names: a home
+// harbour memory carrying one distinctive proper noun, born weak (base 0.35,
+// the "routine-but-curated" band), never accessed, unlinked, a few months
+// old. The rivals are what the decay model produces for early-hardened
+// technical rows: base 0.90-0.95, mutual links, access history, created
+// BEFORE the target. They share the harbour/boating domain vocabulary — so
+// a bare proper-noun query lands in their neighborhood — but none carries
+// the proper noun.
+const SIRNAS_ROWS = [
+    // --- rivals: hardened, connected, older, domain-adjacent ---
+    {
+        key: "rival_fees",
+        content: "Harbour fees and guest dock rules: pay at the machine by the fuel quay, electricity on the guest dock is metered, " +
+            "and visiting boats must clear their berth by ten in the morning during the summer season.",
+        createdAt: "2026-03-02T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.9,
+        accessCount: 4,
+        lastAccessedDaysAgo: 6,
+        linksTo: ["rival_channel", "rival_maintenance"],
+    },
+    {
+        key: "rival_channel",
+        content: "Sailing notes for the home bay: the channel is marked with cardinal buoys, the shallow spit near the outer dock " +
+            "dries at low water, and the ferry has right of way inside the harbour basin.",
+        createdAt: "2026-03-16T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.95,
+        accessCount: 6,
+        lastAccessedDaysAgo: 2,
+        linksTo: ["rival_fees", "rival_maintenance"],
+    },
+    {
+        key: "rival_maintenance",
+        content: "Boat maintenance log: scrub the hull and check the anodes before launch, service the winch every spring, and " +
+            "book the boatyard crane early — the lifting slot list fills up in May.",
+        createdAt: "2026-03-30T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.9,
+        accessCount: 3,
+        lastAccessedDaysAgo: 11,
+        linksTo: ["rival_fees"],
+    },
+    {
+        key: "rival_passage",
+        content: "Passage plan habits: file the float plan before leaving the dock, plot the tidal gate times, and always take the " +
+            "safe water mark side of the reef when the light is obscured.",
+        createdAt: "2026-04-13T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.9,
+        accessCount: 2,
+        lastAccessedDaysAgo: 20,
+        linksTo: ["rival_channel"],
+    },
+    // --- the target: the exact proper-noun match, born humble ---
+    {
+        key: "target_harbour",
+        content: "Home harbour: Vindarsvik (near Stensundet). The guest berth is east of the ferry pier; hold slack when the " +
+            "fishing boats unload.",
+        createdAt: "2026-05-25T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.35,
+        accessCount: 0,
+        lastAccessedDaysAgo: 118,
+        linksTo: [],
+    },
+    // --- neutral filler: keeps neighborhoods non-trivial, off-domain ---
+    {
+        key: "fill_recipe",
+        content: "Batch-cooked a tomato and butter sauce from the Rome cookbook: San Marzano tomatoes, one whole onion halved, and far more butter than seems reasonable.",
+        createdAt: "2026-04-01T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 160,
+        linksTo: [],
+    },
+    {
+        key: "fill_books",
+        content: "Finished the third novel in the frontier trilogy. The middle book dragged through the mining-town chapters, but the finale pays off when the surveyor reads her grandmother's letters.",
+        createdAt: "2026-04-20T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 140,
+        linksTo: [],
+    },
+    {
+        key: "fill_lang",
+        content: "Language study notes: the dative prepositions finally clicked after drilling them as a sung list; irregular verbs still need spaced repetition.",
+        createdAt: "2026-05-10T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 120,
+        linksTo: [],
+    },
+    {
+        key: "fill_garden",
+        content: "The raised beds need refreshing before spring: compost the spent tomato vines, rotate the legume row, and prune the apple espalier before the buds swell.",
+        createdAt: "2026-06-02T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 100,
+        linksTo: [],
+    },
+];
+exports.SIRNAS_FIXTURE = {
+    key: "sirnas_exact_match",
+    description: "AC1: a distinctive proper-noun query must rank the exact-match (both-channel) memory first, " +
+        "ahead of hardened domain-adjacent rivals that win on strength + connections.",
+    rows: SIRNAS_ROWS,
+    query: "Vindarsvik",
+    distinctiveToken: "vindarsvik",
+    expectedTop1: "target_harbour",
+};
+// ---------------------------------------------------------------------------
+// Case 2 — no_match_control (AC2)
+// ---------------------------------------------------------------------------
+//
+// A "mamma"-class query: a common household word in the user's language that
+// appears in NO corpus row — no FTS token, no semantic neighbor. Vector
+// search still returns nearest-neighbor junk (the field's 0.53-similarity
+// technical rows); the case pins the FULL returned list so any drift in
+// how unrelated junk is ordered is caught, and asserts structurally that
+// the ranking work cannot touch it (no both-channel candidates exist).
+exports.NO_MATCH_FIXTURE = {
+    key: "no_match_control",
+    description: "AC2: a no-match query (no FTS hits anywhere) returns a byte-stable list — no both-channel " +
+        "candidates exist, so the boost is structurally inert.",
+    // Same corpus as case 1 (minus nothing): the query matches none of it.
+    rows: SIRNAS_ROWS,
+    query: "mamma",
+    distinctiveToken: "",
+    // No declared top-1 — the assertion is stability, not order (the photo
+    // records the list; the gate compares runs).
+    expectedTop1: "",
+};
+/** The battery runs against a real snapshot copy (ranking-eval.ts case 3). */
+exports.REAL_SIRNAS_MEMORY_ID = "12980c9d-0eba-4963-95eb-0548bc2aa93e";
+// ---------------------------------------------------------------------------
+// Fixture invariants (checked by ranking-eval at run time AND pinned in
+// tests/ranking-eval-tooling.test.ts — a corpus that silently drifts from
+// its declared shape would fake a pass/fail)
+// ---------------------------------------------------------------------------
+function checkFixtureInvariants(f) {
+    const problems = [];
+    const keys = new Set(f.rows.map((r) => r.key));
+    if (keys.size !== f.rows.length)
+        problems.push("duplicate row keys");
+    for (const r of f.rows) {
+        for (const to of r.linksTo) {
+            if (!keys.has(to))
+                problems.push(`${r.key} links to unknown key ${to}`);
+            if (to === r.key)
+                problems.push(`${r.key} links to itself`);
+        }
+    }
+    if (f.expectedTop1 && !keys.has(f.expectedTop1)) {
+        problems.push(`expectedTop1 ${f.expectedTop1} is not a row key`);
+    }
+    if (f.distinctiveToken) {
+        const token = f.distinctiveToken.toLowerCase();
+        const carriers = f.rows.filter((r) => r.content.toLowerCase().includes(token));
+        if (carriers.length !== 1) {
+            problems.push(`distinctive token "${f.distinctiveToken}" carried by ${carriers.length} rows (expected exactly 1)`);
+        }
+        else if (f.expectedTop1 && carriers[0].key !== f.expectedTop1) {
+            problems.push(`distinctive token carried by ${carriers[0].key}, not expectedTop1 ${f.expectedTop1}`);
+        }
+        if (!f.query.toLowerCase().includes(token)) {
+            problems.push(`query does not contain the distinctive token`);
+        }
+    }
+    return problems;
+}

package/dist/identity-store.d.ts

@@ -351,3 +351,24 @@ export declare function serveIdentityBody(handlerResult: HandlerResult, memoryEn
  * symlink safety). Throws are left to the adapter to turn into a 500.
  */
 export declare function handleIdentityPut(identityDir: string, body: unknown, query?: Record<string, unknown>, identityAgents?: Record<string, AgentMode>): HandlerResult;
+/**
+ * PUT /identity/mode (#423 phase 3): switch ONE agent's scope to
+ * override/global/off. Pure validation + merge — the ADAPTER (mcp-server.ts)
+ * does three things with the result: (1) persists `agents` as the config's
+ * `identityAgents` (survives restarts), (2) sets the daemon's live boot-time
+ * map to the same merged map (single-writer: the map changes at boot or
+ * here — never diverges), so the switch is live on the very next
+ * GET /identity?agent= (applies: "immediate"), and (3) responds with this
+ * body. Externally hand-edited config still needs a restart (pre-existing
+ * posture — only this endpoint updates the live map).
+ *
+ * Interplay with PUT /identity: its black-hole guard 409s section writes
+ * while config forces off/global for the agent (sections written under
+ * agents/<id>/ would never be served); switching to 'override' here FIRST
+ * unblocks section editing. `dir_present` tells the caller whether an agent
+ * section dir already exists ('real' — agent content to serve) or not
+ * (override on a fresh dir = global content until sections are written).
+ */
+export declare function handleIdentityModePut(identityDir: string, body: unknown, query: Record<string, unknown>, currentAgents: Record<string, AgentMode>): HandlerResult & {
+    agents?: Record<string, AgentMode>;
+};

package/dist/identity-store.js

@@ -56,6 +56,7 @@ exports.readResolvedSections = readResolvedSections;
 exports.handleIdentityGet = handleIdentityGet;
 exports.serveIdentityBody = serveIdentityBody;
 exports.handleIdentityPut = handleIdentityPut;
+exports.handleIdentityModePut = handleIdentityModePut;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
@@ -875,3 +876,51 @@ function handleIdentityPut(identityDir, body, query = {}, identityAgents = {}) {
     }
     return { status: 200, body: respBody, warn };
 }
+/**
+ * PUT /identity/mode (#423 phase 3): switch ONE agent's scope to
+ * override/global/off. Pure validation + merge — the ADAPTER (mcp-server.ts)
+ * does three things with the result: (1) persists `agents` as the config's
+ * `identityAgents` (survives restarts), (2) sets the daemon's live boot-time
+ * map to the same merged map (single-writer: the map changes at boot or
+ * here — never diverges), so the switch is live on the very next
+ * GET /identity?agent= (applies: "immediate"), and (3) responds with this
+ * body. Externally hand-edited config still needs a restart (pre-existing
+ * posture — only this endpoint updates the live map).
+ *
+ * Interplay with PUT /identity: its black-hole guard 409s section writes
+ * while config forces off/global for the agent (sections written under
+ * agents/<id>/ would never be served); switching to 'override' here FIRST
+ * unblocks section editing. `dir_present` tells the caller whether an agent
+ * section dir already exists ('real' — agent content to serve) or not
+ * (override on a fresh dir = global content until sections are written).
+ */
+function handleIdentityModePut(identityDir, body, query, currentAgents) {
+    const { agentId, error } = extractAgentParam(query);
+    if (error)
+        return { status: 400, body: { error } };
+    if (agentId === null) {
+        return {
+            status: 400,
+            body: { error: "The ?agent= query parameter is required (PUT /identity/mode sets ONE agent's scope)" },
+        };
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return { status: 400, body: { error: "Body must be a JSON object {mode}" } };
+    }
+    const { mode } = body;
+    if (mode !== "override" && mode !== "global" && mode !== "off") {
+        return { status: 400, body: { error: "Invalid 'mode' — expected one of \"override\", \"global\", \"off\"" } };
+    }
+    return {
+        status: 200,
+        body: {
+            agent: agentId,
+            mode,
+            dir_present: agentDirState(identityDir, agentId) === "real",
+            applies: "immediate",
+        },
+        // The merged map the adapter persists AND applies to the live boot-time
+        // map — other agents' entries are preserved untouched.
+        agents: { ...currentAgents, [agentId]: mode },
+    };
+}

package/dist/index.js

@@ -80,9 +80,10 @@ const SEARCH_FALLBACK_TIMEOUT_MS = 5000;
  *  instruction points at a 0.14+ endpoint that 404s on these servers). */
 const LEGACY_CONTENT_CAP = 500;
 /** Default max memories per recall on the legacy /search fallback (config
- *  `recallLimit`, #316). The pushed /recall-index is sized by SERVER config
- *  (`recallMaxItems`) — the server accepts no client limit — so this knob
- *  applies where a client limit actually exists: the pre-0.14 fallback. */
+ *  `recallLimit`, #316). The pushed /recall-index is sized by the server's
+ *  release-managed calibration (#408) — the server accepts no client limit —
+ *  so this knob applies where a client limit actually exists: the pre-0.14
+ *  fallback. */
 const DEFAULT_RECALL_LIMIT = 8;
 /** Cap for the per-session LRU trackers (#316 CR: raised from 50 — a
  *  multi-agent gateway fans sessions across agents; evicting a live session's

package/dist/init.d.ts

@@ -69,7 +69,7 @@ export declare function persistLlmConfig(configPath?: string): Promise<void>;
  * and the writer then OVERWROTE the file — `persistAuthToken` minted a fresh
  * token (fleet-wide 401), `scaffoldDefaultDomains` re-seeded the generic
  * vocabulary over the owner list, etc. `authToken` / `licenseKey` /
- * `llmApiKey` / `domains` / `weakPrimaryFloor` / `identityClients` (was
+ * `llmApiKey` / `domains` / `identityClients` (was
  * `contextClients`) all gone.
  * The early-return guards (existing-key checks) did NOT save them: those only
  * fire on a VALID parse that reads the key, not on a corrupted file.
@@ -94,6 +94,20 @@ export declare function loadConfigStrict(configPath: string): {
     config: Record<string, unknown>;
     hadFile: boolean;
 };
+/**
+ * Apply a sparse set of config updates atomically-ish (strict load → merge →
+ * save): the HTTP-side sibling of persistLlmConfig (which drives the
+ * interactive init flow). `null` values DELETE the key — the console's
+ * "clear field" semantic. Values are assumed VALIDATED by the caller (the
+ * /dashboard/model PUT validates its allowlisted subset BEFORE calling); this
+ * function only owns load-strictly + merge + save, so a malformed existing
+ * config throws here and the file is left UNTOUCHED (the 0.16.x contract —
+ * see loadConfigStrict). Returns the freshly persisted config so the caller
+ * can answer with the post-write truth (re-read, not echo).
+ *
+ * Exported for dashboard.ts's PUT handler + tests.
+ */
+export declare function persistConfigUpdates(configPath: string, updates: Record<string, unknown>): Record<string, unknown>;
 /**
  * `init --repair-config` escape hatch: move a malformed config.json aside so
  * init can rebuild, instead of dead-ending on loadConfigStrict's throw.
@@ -174,7 +188,7 @@ export declare function ensureAgentId(config: Record<string, unknown>): {
  * + unconditional save WIPES config.json when the file exists but is
  * unparseable (a hand-edit syntax slip) — the catch swallows the parse error,
  * {} is seeded, and the save overwrites the file with just {"agentId": ...},
- * destroying authToken / licenseKey / domains / weakPrimaryFloor, then
+ * destroying authToken / licenseKey / domains, then
  * cascades into scaffoldDefaultDomains re-seeding the generic vocabulary.
  * This wrapper refuses that path:
  *   - ENOENT (file genuinely absent) → seed {} is correct (new install).
@@ -348,7 +362,8 @@ export declare function runInit(options?: {
 }): Promise<void>;
 /**
  * Resolve the timer-jitter spread (seconds) from config. 0 = disabled. Uses
- * readNonNegativeConfig (0 is a valid "off", mirroring ollamaFlushEvery).
+ * readNonNegativeConfig (0 is a valid "off", like memorySoftCap's eviction
+ * opt-out).
  */
 export declare function resolveTimerJitterSeconds(configDir?: string): number;
 /**
@@ -403,3 +418,8 @@ export declare function formatLaunchdIntervals(hours: number[], minuteOffset?: n
  * applies to every OnCalendar entry AND to OnUnitActiveSec (systemd semantics).
  */
 export declare function formatSystemdTimerBody(isInterval: boolean, intervalSec: number, hours: number[], jitterSec: number): string;
+/**
+ * Install the CONSOLIDATION timer (full `nightly`). Reuses the existing
+ * `hicortex-nightly` unit name (repurposed from the pre-0.17 single full-nightly).
+ */
+export declare function installConsolidationTimer(hours: number[]): void;

package/dist/init.js

@@ -30,6 +30,7 @@ exports.parseEnvFile = parseEnvFile;
 exports.isLlmConfigured = isLlmConfigured;
 exports.persistLlmConfig = persistLlmConfig;
 exports.loadConfigStrict = loadConfigStrict;
+exports.persistConfigUpdates = persistConfigUpdates;
 exports.quarantineMalformedConfig = quarantineMalformedConfig;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
@@ -52,6 +53,7 @@ exports.resolveNightlyHour = resolveNightlyHour;
 exports.formatOnCalendarLines = formatOnCalendarLines;
 exports.formatLaunchdIntervals = formatLaunchdIntervals;
 exports.formatSystemdTimerBody = formatSystemdTimerBody;
+exports.installConsolidationTimer = installConsolidationTimer;
 const paths_js_1 = require("./paths.js");
 const localhost_bypass_js_1 = require("./localhost-bypass.js");
 const telemetry_js_1 = require("./telemetry.js");
@@ -64,6 +66,8 @@ const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
 const claude_desktop_js_1 = require("./claude-desktop.js");
 const config_read_js_1 = require("./config-read.js");
+const calibration_js_1 = require("./calibration.js");
+const run_deadline_js_1 = require("./run-deadline.js");
 const identity_store_js_1 = require("./identity-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 /** This package's version, for the install lifecycle ping (0.15.2). */
@@ -994,7 +998,7 @@ function saveConfig(configPath, config) {
  * and the writer then OVERWROTE the file — `persistAuthToken` minted a fresh
  * token (fleet-wide 401), `scaffoldDefaultDomains` re-seeded the generic
  * vocabulary over the owner list, etc. `authToken` / `licenseKey` /
- * `llmApiKey` / `domains` / `weakPrimaryFloor` / `identityClients` (was
+ * `llmApiKey` / `domains` / `identityClients` (was
  * `contextClients`) all gone.
  * The early-return guards (existing-key checks) did NOT save them: those only
  * fire on a VALID parse that reads the key, not on a corrupted file.
@@ -1050,6 +1054,30 @@ function loadConfigStrict(configPath) {
     }
     return { config: parsed, hadFile: true };
 }
+/**
+ * Apply a sparse set of config updates atomically-ish (strict load → merge →
+ * save): the HTTP-side sibling of persistLlmConfig (which drives the
+ * interactive init flow). `null` values DELETE the key — the console's
+ * "clear field" semantic. Values are assumed VALIDATED by the caller (the
+ * /dashboard/model PUT validates its allowlisted subset BEFORE calling); this
+ * function only owns load-strictly + merge + save, so a malformed existing
+ * config throws here and the file is left UNTOUCHED (the 0.16.x contract —
+ * see loadConfigStrict). Returns the freshly persisted config so the caller
+ * can answer with the post-write truth (re-read, not echo).
+ *
+ * Exported for dashboard.ts's PUT handler + tests.
+ */
+function persistConfigUpdates(configPath, updates) {
+    const { config } = loadConfigStrict(configPath);
+    for (const [k, v] of Object.entries(updates)) {
+        if (v === null)
+            delete config[k];
+        else
+            config[k] = v;
+    }
+    saveConfig(configPath, config);
+    return config;
+}
 /**
  * `init --repair-config` escape hatch: move a malformed config.json aside so
  * init can rebuild, instead of dead-ending on loadConfigStrict's throw.
@@ -1099,7 +1127,7 @@ function quarantineMalformedConfig(configPath) {
         console.log(`    Keys found in the old file: ${keys.join(", ")}`);
     }
     console.log(`    ACTION REQUIRED: copy any of licenseKey / llmApiKey /`);
-    console.log(`    domains / weakPrimaryFloor back from the backup by hand.`);
+    console.log(`    domains back from the backup by hand.`);
     console.log(`    A NEW authToken will be generated — every thin client pointing at this`);
     console.log(`    server must be updated, or their recall will 401 (silently, fail-soft).`);
     return { quarantined: true, backupPath, keys };
@@ -1167,7 +1195,7 @@ function ensureAgentId(config) {
  * + unconditional save WIPES config.json when the file exists but is
  * unparseable (a hand-edit syntax slip) — the catch swallows the parse error,
  * {} is seeded, and the save overwrites the file with just {"agentId": ...},
- * destroying authToken / licenseKey / domains / weakPrimaryFloor, then
+ * destroying authToken / licenseKey / domains, then
  * cascades into scaffoldDefaultDomains re-seeding the generic vocabulary.
  * This wrapper refuses that path:
  *   - ENOENT (file genuinely absent) → seed {} is correct (new install).
@@ -1941,6 +1969,9 @@ async function runInit(options = {}) {
     // the install → first-nightly → retained funnel is measurable. Never blocks:
     // failures are swallowed inside sendLifecycleEvent.
     await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
+    // #436: the first-run lookback cap is invisible until it bites — tell the
+    // long-history user where the rest went and how to get it, once, at install.
+    console.log(`History import: the first nightly captures the last ${calibration_js_1.DEFAULT_FIRST_RUN_LOOKBACK_DAYS} days of your agents' sessions by default — run \`hicortex nightly --recapture-window <days>\` once to import more.`);
     console.log("Next steps:");
     // Counter-based so the list stays contiguous (1,2,3,4) whether or not Hermes
     // was detected — a conditional middle step used to leave a "1, 3, 4" gap.
@@ -2126,6 +2157,9 @@ async function runClientInit(serverUrl, agentName) {
     // the install → first-nightly → retained funnel is measurable. Never blocks:
     // failures are swallowed inside sendLifecycleEvent.
     await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
+    // #436: the first-run lookback cap is invisible until it bites — tell the
+    // long-history user where the rest went and how to get it, once, at install.
+    console.log(`History import: the first nightly captures the last ${calibration_js_1.DEFAULT_FIRST_RUN_LOOKBACK_DAYS} days of your agents' sessions on this machine by default — run \`hicortex nightly --recapture-window <days>\` once to import more.`);
     console.log("How it works:");
     console.log("  • MCP tools (search, identity, ingest) talk to the remote server");
     console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");
@@ -2181,7 +2215,8 @@ const DEFAULT_CONSOLIDATION_HOURS = [10, 22];
 const DEFAULT_TIMER_JITTER_SEC = 3600;
 /**
  * Resolve the timer-jitter spread (seconds) from config. 0 = disabled. Uses
- * readNonNegativeConfig (0 is a valid "off", mirroring ollamaFlushEvery).
+ * readNonNegativeConfig (0 is a valid "off", like memorySoftCap's eviction
+ * opt-out).
  */
 function resolveTimerJitterSeconds(configDir = HICORTEX_HOME) {
     let config = {};
@@ -2471,6 +2506,12 @@ function installCaptureWatchdogTimer() {
  * `hicortex-nightly` unit name (repurposed from the pre-0.17 single full-nightly).
  */
 function installConsolidationTimer(hours) {
+    // #405: DERIVED from the run deadline — nightlyTimeBudgetMinutes + 60 min
+    // slack. The old fixed 360 was prose-coupled to the old call budget (raise
+    // together!); now the unit backstop tracks the deadline it is backing.
+    // Backstop only (NOT an operating limit) — the slack absorbs backup +
+    // telemetry + a slow shutdown after the deadline stops the stages.
+    const timeoutMin = (0, run_deadline_js_1.resolveNightlyTimeBudgetMinutes)(readInstallConfig()) + 60;
     writeScheduleUnit({
         unitBase: "hicortex-nightly",
         plistLabel: "com.gamaze.hicortex-nightly",
@@ -2478,12 +2519,46 @@ function installConsolidationTimer(hours) {
         timerDesc: "Hicortex Consolidation Timer",
         nightlyArgs: ["nightly"],
         hours,
-        // Backstop only (NOT an operating limit) — set well above the longest
-        // legitimate run so it catches a true hang, never a slow-but-progressing
-        // one. ~5000 LLM calls × ~1–3s/call ≈ 1.4–4.2h → 6h clears it with margin.
-        // Coupled to the consolidateMaxLlmCalls budget (#241): raise together.
-        timeoutMin: 360,
+        // nightlyTimeBudgetMinutes (default 240) + 60 min slack — see above.
+        timeoutMin,
     });
+    // #405 shadow detection: a systemd drop-in can override the derived
+    // TimeoutStartSec silently (a stale pre-#405 drop-in pinning a shorter
+    // timeout would hard-kill legitimate deadline-bounded runs). Detect and
+    // warn — removal is a deploy-time ops step, not an init action.
+    warnSystemdDropInShadow("hicortex-nightly", timeoutMin);
+}
+/** Read the install-time config (~/.hicortex/config.json), null-tolerant. */
+function readInstallConfig() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(HICORTEX_HOME, "config.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Warn when `~/.config/systemd/user/<unit>.service.d/*.conf` drop-ins exist —
+ * they can shadow the generated TimeoutStartSec (and anything else the unit
+ * sets). Linux only; the macOS launchd path has no drop-in mechanism.
+ */
+function warnSystemdDropInShadow(unitBase, derivedTimeoutMin) {
+    if ((0, node_os_1.platform)() !== "linux")
+        return;
+    const dropInDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "systemd", "user", `${unitBase}.service.d`);
+    let entries = [];
+    try {
+        entries = (0, node_fs_1.readdirSync)(dropInDir).filter((f) => f.endsWith(".conf"));
+    }
+    catch {
+        return; // no drop-in dir — the common case
+    }
+    if (entries.length === 0)
+        return;
+    console.warn(`[hicortex] systemd drop-ins present for ${unitBase}.service (${entries.join(", ")}) — ` +
+        `they can SHADOW the generated unit settings (TimeoutStartSec is now derived: ` +
+        `${derivedTimeoutMin}min = nightlyTimeBudgetMinutes + 60 slack). ` +
+        `Remove stale drop-ins so the derived values take effect.`);
 }
 /**
  * Remove the consolidation timer + service (and the macOS plist). Used on