@gamaze/hicortex 0.17.6 → 0.18.1

package/dist/index.js

@@ -10,13 +10,13 @@
  * Run server:   `npx @gamaze/hicortex init`
  *
  * Responsibilities (recall-only adapter, like the Hermes plugin):
- *   - before_agent_start  → GET /context + GET /lessons + POST /recall-index
- *     (fail-soft, 3s timeout each, concurrent) → inject context. In OpenClaw
- *     every inbound message spawns an embedded run, so this hook fires PER
- *     TURN with the current prompt and session id — it is the per-turn
+ *   - before_agent_start  → GET /identity + GET /lessons + POST /recall-index
+ *     (fail-soft, 3s timeout each, concurrent) → inject identity + lessons. In
+ *     OpenClaw every inbound message spawns an embedded run, so this hook fires
+ *     PER TURN with the current prompt and session id — it is the per-turn
  *     /recall-index surface, not just session start.
  *   - after_compaction / before_reset → POST /recall-index {reset:true}
- *     (context rebuilt → the server's per-session shown-set is stale)
+ *     (context window rebuilt → the server's per-session shown-set is stale)
  *   - Tools               → HTTP proxies to /search, /memory, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
@@ -25,24 +25,26 @@
  * canonical nightly-from-logs, same as CC JSONL and Hermes state.db.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToolResults = formatToolResults;
 const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
-const context_store_js_1 = require("./context-store.js");
-const lessons_context_js_1 = require("./lessons-context.js");
+const identity_store_js_1 = require("./identity-store.js");
+const learnings_identity_js_1 = require("./learnings-identity.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
+const type_labels_js_1 = require("./type-labels.js");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const DEFAULT_SERVER_URL = "http://127.0.0.1:8787";
 const LESSONS_TIMEOUT_MS = 3000;
-const CONTEXT_TIMEOUT_MS = 3000;
+const IDENTITY_TIMEOUT_MS = 3000;
 const RECALL_TIMEOUT_MS = 3000;
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
-/** Harness name this plugin injects for — used to self-gate on GET /context `clients`. */
+/** Harness name this plugin injects for — used to self-gate on GET /identity `clients`. */
 const THIS_HARNESS = "oc";
 // ---------------------------------------------------------------------------
 // Module state — initialized in registerService.start()
@@ -130,26 +132,27 @@ async function serverPost(path, body, timeoutMs) {
     }
 }
 // ---------------------------------------------------------------------------
-// Context layer (L2) — per-agent standing context (0.13)
+// Identity layer — per-agent standing identity (0.13; renamed from context
+// layer in 0.18 #264)
 // ---------------------------------------------------------------------------
 /**
- * Fetch GET /context (per-agent when an id is supplied) and build the
- * `## Context` block via the shared gate (gateAndRenderContext), or null when
+ * Fetch GET /identity (per-agent when an id is supplied) and build the
+ * `## Identity` block via the shared gate (gateAndRenderIdentity), or null when
  * nothing should be injected. The old-server guard is required only when an
  * agent id was actually sent (amendment A2 — a bare fetch skips it). The server
  * does the merge; the plugin stays dumb (no client-side mode logic).
  */
-async function fetchOcContextBlock(agentId) {
-    const path = agentId ? `/context?agent=${encodeURIComponent(agentId)}` : "/context";
-    const { data } = await serverGet(path, CONTEXT_TIMEOUT_MS);
+async function fetchOcIdentityBlock(agentId) {
+    const path = agentId ? `/identity?agent=${encodeURIComponent(agentId)}` : "/identity";
+    const { data } = await serverGet(path, IDENTITY_TIMEOUT_MS);
     if (!data)
         return null;
-    return (0, lessons_context_js_1.gateAndRenderContext)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
+    return (0, learnings_identity_js_1.gateAndRenderIdentity)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
 }
 /**
  * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
  * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
- * output; the caller prepends the `## Context` block and adds separators.
+ * output; the caller prepends the `## Identity` block and adds separators.
  */
 async function buildLessonsBlock(project) {
     const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
@@ -248,7 +251,7 @@ function formatToolResults(results) {
         return { content: [{ type: "text", text: "No memories found." }] };
     }
     const text = results
-        .map((r) => `[${r.memory_type}] (score: ${r.score.toFixed(3)}, strength: ${r.effective_strength.toFixed(3)}) ${r.content.slice(0, 500)}`)
+        .map((r) => `[${(0, type_labels_js_1.labelForType)(r.memory_type)}] (score: ${r.score.toFixed(3)}, strength: ${r.effective_strength.toFixed(3)}) ${r.content.slice(0, 500)}`)
         .join("\n\n");
     return { content: [{ type: "text", text }] };
 }
@@ -284,15 +287,40 @@ exports.default = {
                 log(`[hicortex] Thin-client mode — server: ${serverUrl}`);
                 // License: init feature cache (only needs licenseKey, no DB access)
                 await (0, features_js_1.initFeatures)(config.licenseKey, hicortexHome);
-                // Verify server reachability at startup (non-fatal — warn only)
+                // Verify server reachability at startup (non-fatal — warn only).
+                // /health is the public minimal {status:"ok"} probe (#253) — fine for
+                // a liveness check. Diagnostics (version, memories) live on
+                // /health/detail; the OC plugin is authenticated by its server token,
+                // so use that path for the richer log line.
                 try {
-                    const resp = await fetch(`${serverUrl}/health`, {
+                    // Authenticated diagnostics probe. Only send the Authorization
+                    // header when a token actually exists — an empty `Bearer ` header
+                    // is worse than absent (it can trip strict middlewares and signals
+                    // a misconfigured client). When there's no token, fall straight to
+                    // the public /health liveness probe below.
+                    const headers = {};
+                    if (config.authToken)
+                        headers.Authorization = `Bearer ${config.authToken}`;
+                    const resp = await fetch(`${serverUrl}/health/detail`, {
                         signal: AbortSignal.timeout(5000),
+                        headers,
                     });
                     if (resp.ok) {
                         const data = await resp.json();
                         log(`[hicortex] Server OK: v${data.version}, ${data.memories} memories`);
                     }
+                    else if (resp.status === 401) {
+                        // Token-less fallback: the public probe confirms liveness; the
+                        // diagnostic fields aren't available without auth. The public
+                        // probe carries no version, so log reachability honestly rather
+                        // than a fabricated "vok"/"vn/a".
+                        const pub = await fetch(`${serverUrl}/health`, {
+                            signal: AbortSignal.timeout(5000),
+                        });
+                        log(pub.ok
+                            ? `[hicortex] Server OK (reachable, diagnostics gated)`
+                            : `[hicortex] Server returned HTTP ${pub.status} on public /health`);
+                    }
                     else {
                         log(`[hicortex] Server returned HTTP ${resp.status} — capture and tools may fail`);
                     }
@@ -310,7 +338,7 @@ exports.default = {
             },
         });
         // -----------------------------------------------------------------------
-        // Hook: before_agent_start — fetch context + lessons + recall index
+        // Hook: before_agent_start — fetch identity + lessons + recall index
         // (fail-soft). Fires per embedded run = per inbound message in OpenClaw,
         // so the recall index rides the same hook as the per-turn surface.
         // -----------------------------------------------------------------------
@@ -320,20 +348,20 @@ exports.default = {
             // synchronous sanitize below runs before any per-fetch .catch — so the
             // whole body is wrapped, not just the fetches.
             try {
-                // Per-agent context id: sanitize the OC agent id (a symbols-only id
-                // sanitizes to null → bare /context → global set). Null id never sends
+                // Per-agent identity id: sanitize the OC agent id (a symbols-only id
+                // sanitizes to null → bare /identity → global set). Null id never sends
                 // ?agent=, so an old server behaves exactly as before.
-                const agentId = (0, context_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
+                const agentId = (0, identity_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
                 // Fetch all three concurrently with INDEPENDENT fail-soft: no block
-                // may ever cost another. Order in the injected context: `## Context`
-                // (standing context, 0.13) → `## Hicortex Lessons` → the per-turn
+                // may ever cost another. Order in the injected output: `## Identity`
+                // (standing identity, 0.13) → `## Hicortex Lessons` → the per-turn
                 // `## Memory recall (auto)` index (#193, closest to the prompt).
-                const [contextBlock, lessonsBlock, recallBlock] = await Promise.all([
-                    fetchOcContextBlock(agentId).catch(() => null),
+                const [identityBlock, lessonsBlock, recallBlock] = await Promise.all([
+                    fetchOcIdentityBlock(agentId).catch(() => null),
                     buildLessonsBlock(ctx?.project).catch(() => null),
                     fetchRecallIndexBlock(ctx?.sessionId, event?.prompt, ctx?.project).catch(() => null),
                 ]);
-                const blocks = [contextBlock, lessonsBlock, recallBlock].filter((b) => b !== null && b !== "");
+                const blocks = [identityBlock, lessonsBlock, recallBlock].filter((b) => b !== null && b !== "");
                 if (blocks.length === 0)
                     return {};
                 return { appendSystemContext: `\n\n${blocks.join("\n\n")}\n` };

package/dist/init.d.ts

@@ -57,7 +57,8 @@ 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` / `contextClients` all gone.
+ * `llmApiKey` / `domains` / `weakPrimaryFloor` / `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.
  *
@@ -180,10 +181,10 @@ export declare function ensureAndPersistAgentId(configPath: string): {
     generated: boolean;
 };
 /**
- * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * Decide the per-agent identity id to persist at init (#179; CC default = global,
  * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
  * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
- * and shares the global context (one user = one identity across machines).
+ * and shares the global identity (one user = one identity across machines).
  *
  * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
  * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
@@ -289,11 +290,18 @@ export declare function getPackageSpec(configDir?: string): string;
  */
 export declare function isEphemeralNpxPath(binPath: string): boolean;
 /**
- * Install (or verify) the CC SessionStart hook that runs `hicortex lessons-context`.
- * The hook fetches lessons from the configured server at session start and injects
- * them as context — replacing the old static CLAUDE.md block.
+ * Install (or verify) the CC SessionStart hook that runs the canonical command
+ * `hicortex learnings-identity` (aliased as the legacy `lessons-context`,
+ * #264). The hook fetches the identity layer + lessons from the configured
+ * server at session start and injects them as a Markdown block — replacing the
+ * old static CLAUDE.md block.
+ *
+ * Idempotent: skips if a SessionStart hook containing EITHER `learnings-identity`
+ * OR the legacy `lessons-context` already exists (so re-init never duplicates,
+ * whether the existing hook was written by a pre- or post-#264 install). It does
+ * NOT rewrite an existing legacy `lessons-context` hook — the alias keeps old
+ * installs working as-is.
  *
- * Idempotent: skips if a SessionStart hook containing "lessons-context" already exists.
  * Uses JSON.parse/JSON.stringify to safely merge into ~/.claude/settings.json.
  *
  * @param settingsPath Override for the settings.json path (used in tests; defaults to CC_SETTINGS).
@@ -311,6 +319,23 @@ export declare function runInit(options?: {
     agentName?: string;
     repairConfig?: boolean;
 }): Promise<void>;
+/**
+ * Resolve the timer-jitter spread (seconds) from config. 0 = disabled. Uses
+ * readNonNegativeConfig (0 is a valid "off", mirroring ollamaFlushEvery).
+ */
+export declare function resolveTimerJitterSeconds(configDir?: string): number;
+/**
+ * #256 — per-install randomized Minute offset for the launchd consolidation
+ * plist. launchd has no native `RandomizedDelaySec`; the idiomatic equivalent
+ * is a per-job `Minute` shift baked into each `StartCalendarInterval` dict.
+ * The value is generated ONCE at init time so the plist is stable across
+ * reboots (no flapping), and the SAME offset applies to every slot so the
+ * relative spacing between slots is preserved.
+ *
+ * `jitterSec` < 60 → 0 (cannot span a minute). Inject `rand` for deterministic
+ * tests; defaults to Math.random (init-time generation, not the hot path).
+ */
+export declare function randomMinuteOffset(jitterSec: number, rand?: () => number): number;
 /**
  * Resolve the CONSOLIDATION hours (the only slot-based timer in 0.17). The
  * CAPTURE mechanism is the watchdog (an interval timer, not slots) — uniform
@@ -338,5 +363,16 @@ export declare function formatOnCalendarLines(hours: number[]): string;
  * The launchd `StartCalendarInterval` ARRAY body — one `<dict>` per hour.
  * launchd fires the job at each dict; a single dict is the 1-slot special case
  * but the array form is uniform across 1..N. Exported for testing.
+ *
+ * `minuteOffset` (#256): a per-install randomized Minute applied uniformly to
+ * every slot (0 = no offset = pre-#256 behaviour). See `randomMinuteOffset`.
+ */
+export declare function formatLaunchdIntervals(hours: number[], minuteOffset?: number): string;
+/**
+ * The systemd `[Timer]` body (everything between `[Timer]` and the next stanza).
+ * Exported for testing the #256 jitter line. `isInterval` selects the watchdog
+ * poll form (OnBootSec + OnUnitActiveSec); otherwise one `OnCalendar` line per
+ * hour. When `jitterSec > 0` a single `RandomizedDelaySec=<n>` is appended — it
+ * applies to every OnCalendar entry AND to OnUnitActiveSec (systemd semantics).
  */
-export declare function formatLaunchdIntervals(hours: number[]): string;
+export declare function formatSystemdTimerBody(isInterval: boolean, intervalSec: number, hours: number[], jitterSec: number): string;

package/dist/init.js

@@ -37,10 +37,13 @@ exports.isEphemeralNpxPath = isEphemeralNpxPath;
 exports.installSessionStartHook = installSessionStartHook;
 exports.installRecallHooks = installRecallHooks;
 exports.runInit = runInit;
+exports.resolveTimerJitterSeconds = resolveTimerJitterSeconds;
+exports.randomMinuteOffset = randomMinuteOffset;
 exports.resolveConsolidationHours = resolveConsolidationHours;
 exports.resolveNightlyHour = resolveNightlyHour;
 exports.formatOnCalendarLines = formatOnCalendarLines;
 exports.formatLaunchdIntervals = formatLaunchdIntervals;
+exports.formatSystemdTimerBody = formatSystemdTimerBody;
 const paths_js_1 = require("./paths.js");
 const telemetry_js_1 = require("./telemetry.js");
 const node_fs_1 = require("node:fs");
@@ -51,7 +54,7 @@ const node_readline_1 = require("node:readline");
 const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
 const config_read_js_1 = require("./config-read.js");
-const context_store_js_1 = require("./context-store.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). */
 function pkgVersion() {
@@ -85,9 +88,11 @@ async function detect() {
         hermesFound: false,
         existingDb: false,
     };
-    // Check local server
+    // Check local server. /health/detail carries the diagnostics (memories,
+    // version, llm) — /health itself is the public minimal {status:"ok"} probe
+    // (#253). localhost bypasses auth, so co-located detect gets the fields.
     try {
-        const resp = await fetch(`http://127.0.0.1:${DEFAULT_PORT}/health`, {
+        const resp = await fetch(`http://127.0.0.1:${DEFAULT_PORT}/health/detail`, {
             signal: AbortSignal.timeout(2000),
         });
         if (resp.ok) {
@@ -98,7 +103,13 @@ async function detect() {
         }
     }
     catch { /* not running */ }
-    // Check remote server (env var)
+    // Check remote server (env var). detect() runs BEFORE any config/token
+    // exists, so this MUST use the PUBLIC /health probe (liveness only) —
+    // /health/detail sits behind the auth middleware and would 401 on any
+    // authed remote server, making a healthy remote look "unreachable" and
+    // silently mis-routing the install branch (#253 CR fix). The memory count
+    // is not available on the public probe; the local-server path above still
+    // gets it via localhost-bypassed /health/detail.
     const remoteUrl = process.env.HICORTEX_SERVER_URL;
     if (remoteUrl && !result.localServer) {
         try {
@@ -108,8 +119,6 @@ async function detect() {
             if (resp.ok) {
                 result.remoteServer = true;
                 result.remoteServerUrl = remoteUrl;
-                const data = await resp.json();
-                result.memoryCount = data.memories;
             }
         }
         catch { /* not reachable */ }
@@ -734,7 +743,8 @@ 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` / `contextClients` all gone.
+ * `llmApiKey` / `domains` / `weakPrimaryFloor` / `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.
  *
@@ -931,10 +941,10 @@ function ensureAndPersistAgentId(configPath) {
     return result;
 }
 /**
- * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * Decide the per-agent identity id to persist at init (#179; CC default = global,
  * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
  * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
- * and shares the global context (one user = one identity across machines).
+ * and shares the global identity (one user = one identity across machines).
  *
  * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
  * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
@@ -952,12 +962,12 @@ function decideAgentName(existing, flag) {
         // Explicit empty / whitespace-only value → clear back to global (unset).
         if (flag.trim() === "")
             return { write: false, value: null, clear: true };
-        const s = (0, context_store_js_1.sanitizeAgentId)(flag);
+        const s = (0, identity_store_js_1.sanitizeAgentId)(flag);
         if (s === null) {
             return {
                 write: false,
                 value: null,
-                error: `Invalid --agent-name '${flag}'. Must contain letters or digits and sanitize to ^[a-z0-9][a-z0-9_-]*$ (max 64 chars). Pass --agent-name "" to clear it (global context).`,
+                error: `Invalid --agent-name '${flag}'. Must contain letters or digits and sanitize to ^[a-z0-9][a-z0-9_-]*$ (max 64 chars). Pass --agent-name "" to clear it (global identity).`,
             };
         }
         return { write: true, value: s };
@@ -1176,17 +1186,24 @@ function resolveBinaryArgs() {
     return [npxPath, "-y", packageSpec];
 }
 /**
- * Install (or verify) the CC SessionStart hook that runs `hicortex lessons-context`.
- * The hook fetches lessons from the configured server at session start and injects
- * them as context — replacing the old static CLAUDE.md block.
+ * Install (or verify) the CC SessionStart hook that runs the canonical command
+ * `hicortex learnings-identity` (aliased as the legacy `lessons-context`,
+ * #264). The hook fetches the identity layer + lessons from the configured
+ * server at session start and injects them as a Markdown block — replacing the
+ * old static CLAUDE.md block.
+ *
+ * Idempotent: skips if a SessionStart hook containing EITHER `learnings-identity`
+ * OR the legacy `lessons-context` already exists (so re-init never duplicates,
+ * whether the existing hook was written by a pre- or post-#264 install). It does
+ * NOT rewrite an existing legacy `lessons-context` hook — the alias keeps old
+ * installs working as-is.
  *
- * Idempotent: skips if a SessionStart hook containing "lessons-context" already exists.
  * Uses JSON.parse/JSON.stringify to safely merge into ~/.claude/settings.json.
  *
  * @param settingsPath Override for the settings.json path (used in tests; defaults to CC_SETTINGS).
  */
 function installSessionStartHook(settingsPath) {
-    installCcHook("SessionStart", "lessons-context", 10, settingsPath);
+    installCcHook("SessionStart", "learnings-identity", 10, settingsPath, ["lessons-context"]);
 }
 /**
  * Install (or verify) the #192 pushed-recall hooks: `hicortex recall-hook`
@@ -1201,14 +1218,17 @@ function installRecallHooks(settingsPath) {
 /**
  * Shared CC-hook installer: add `hicortex <subcommand>` under the given hook
  * event in ~/.claude/settings.json. Idempotent per (event, subcommand): skips
- * if any existing entry for that event already runs the subcommand. `timeout`
- * is CC's hook-process kill timeout in SECONDS (the network timeout inside the
- * command is separate and shorter).
+ * if any existing entry for that event already runs the subcommand — or, when
+ * `aliases` is passed, ANY of the alias names. The alias match is what lets a
+ * post-#264 install recognize a pre-#264 `lessons-context` hook as "already
+ * installed" without rewriting it (the legacy name keeps working via
+ * resolveCommandAlias). `timeout` is CC's hook-process kill timeout in SECONDS
+ * (the network timeout inside the command is separate and shorter).
  */
-function installCcHook(eventName, subcommand, timeout, settingsPath) {
+function installCcHook(eventName, subcommand, timeout, settingsPath, aliases = []) {
     const targetPath = settingsPath ?? CC_SETTINGS;
     const binaryArgs = resolveBinaryArgs();
-    // e.g. "/path/to/hicortex lessons-context" or "npx -y @gamaze/hicortex recall-hook"
+    // e.g. "/path/to/hicortex learnings-identity" or "npx -y @gamaze/hicortex recall-hook"
     const command = [...binaryArgs, subcommand].join(" ");
     let settings = {};
     if ((0, node_fs_1.existsSync)(targetPath)) {
@@ -1232,10 +1252,13 @@ function installCcHook(eventName, subcommand, timeout, settingsPath) {
         hooks[eventName] = [];
     }
     const entries = hooks[eventName];
-    // Idempotent: skip if any existing entry's command runs this subcommand.
-    // Word-boundary guard so "recall-hook" never matches a hypothetical
-    // "recall-hook-foo" command.
-    const subcommandRe = new RegExp(`(^|\\s)${subcommand}(\\s|$)`);
+    // Idempotent: skip if any existing entry's command runs this subcommand OR
+    // one of its aliases (e.g. a pre-#264 `lessons-context` hook when installing
+    // the canonical `learnings-identity`). Word-boundary guard so "recall-hook"
+    // never matches a hypothetical "recall-hook-foo" command, and so the
+    // `learnings-identity`/`lessons-context` pair are distinct (no prefix clash).
+    const names = [subcommand, ...aliases];
+    const subcommandRe = new RegExp(`(^|\\s)(?:${names.map(escapeRegex).join("|")})(\\s|$)`);
     const alreadyInstalled = entries.some((entry) => {
         if (typeof entry !== "object" || entry === null)
             return false;
@@ -1262,6 +1285,14 @@ function installCcHook(eventName, subcommand, timeout, settingsPath) {
     (0, node_fs_1.writeFileSync)(targetPath, JSON.stringify(settings, null, 2));
     console.log(`  ✓ Installed ${eventName} hook: ${command}`);
 }
+/**
+ * Escape a literal string for safe embedding in a RegExp (alias names like
+ * `lessons-context` happen to be regex-safe, but escape anyway so the
+ * idempotency check can never break if a future alias contains a metachar).
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function installLaunchd(binaryArgs) {
     const plistDir = (0, node_path_1.join)((0, node_os_1.homedir)(), "Library", "LaunchAgents");
     const plistPath = (0, node_path_1.join)(plistDir, "com.gamaze.hicortex.plist");
@@ -1469,9 +1500,9 @@ async function runInit(options = {}) {
     // Classification activates automatically once an LLM is configured; until
     // then domains sit inert (strict-skip path).
     scaffoldDefaultDomains(configPath);
-    // Per-agent context id (#179): server mode writes it ONLY when the operator
+    // 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 context (global by default). Explicit flag
+    // co-located CC shares the global identity (global by default). Explicit flag
     // overwrites on re-init; `--agent-name ""` clears it back to global.
     if (options.agentName !== undefined) {
         const decision = decideAgentName(undefined, options.agentName);
@@ -1481,7 +1512,7 @@ async function runInit(options = {}) {
         }
         if (decision.clear) {
             clearAgentNameConfig(configPath);
-            console.log("  ✓ Agent name cleared — global context");
+            console.log("  ✓ Agent name cleared — global identity");
         }
         else if (decision.write && decision.value) {
             writeAgentNameConfig(configPath, decision.value);
@@ -1631,7 +1662,7 @@ async function runClientInit(serverUrl, agentName) {
     // Step 3: Save client config
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
-    // Per-agent context id (#179): explicit opt-in only. resolve the flag via
+    // Per-agent identity id (#179): explicit opt-in only. resolve the flag via
     // decideAgentName (it owns the process.exit on an invalid --agent-name). A
     // no-flag run yields a {write:false} decision → writeClientConfig leaves any
     // existing agentName untouched (preserving what the loaded config carries).
@@ -1641,7 +1672,7 @@ async function runClientInit(serverUrl, agentName) {
         process.exit(1);
     }
     if (nameDecision.clear) {
-        console.log("  ✓ Agent name cleared — global context");
+        console.log("  ✓ Agent name cleared — global identity");
     }
     else if (nameDecision.write && nameDecision.value && agentName && nameDecision.value !== agentName) {
         console.log(`  ℹ Agent name sanitized to '${nameDecision.value}'`);
@@ -1718,7 +1749,7 @@ async function runClientInit(serverUrl, agentName) {
     // failures are swallowed inside sendLifecycleEvent.
     await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
     console.log("How it works:");
-    console.log("  • MCP tools (search, context, ingest) talk to the remote server");
+    console.log("  • MCP tools (search, identity, ingest) talk to the remote server");
     console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");
     console.log("  • Lessons fetched live at each CC session start (SessionStart hook)");
     console.log("  • No local database — all memories stored on the server");
@@ -1755,6 +1786,54 @@ async function runClientInit(serverUrl, agentName) {
  * only when `consolidationHours` is absent (preserves "one daily job at H").
  */
 const DEFAULT_CONSOLIDATION_HOURS = [10, 22];
+/**
+ * #256 — timer jitter default (seconds). Applied to newly-generated timers so a
+ * fleet of installs on the same default schedule doesn't all hit the LLM
+ * backend at the same minute (thundering-herd avoidance). systemd emits this as
+ * `RandomizedDelaySec`; launchd has no native equivalent so the launchd path
+ * bakes a per-install randomized `Minute` offset into each
+ * `StartCalendarInterval` dict (generated once at init, stable across reboots).
+ *
+ * 3600s = 1h spread on a 2-slot/day consolidation cadence = up to ±30 min around
+ * each slot — enough to flatten the peak without stretching into the next slot
+ * window. Tunable via `timerJitterSeconds` (0 disables). NOTE: only affects
+ * NEWLY generated timers; re-init rewrites the unit files (the 0.17 migration
+ * decision), so an explicit re-init is how an existing install adopts jitter.
+ */
+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).
+ */
+function resolveTimerJitterSeconds(configDir = HICORTEX_HOME) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(configDir, "config.json"), "utf-8"));
+    }
+    catch { /* no config yet — use the default */ }
+    // Floor to an integer for a clean contract (systemd accepts fractional
+    // seconds, but a whole-second value is unambiguous across systemd + launchd).
+    return Math.floor((0, config_read_js_1.readNonNegativeConfig)(config, "timerJitterSeconds", DEFAULT_TIMER_JITTER_SEC));
+}
+/**
+ * #256 — per-install randomized Minute offset for the launchd consolidation
+ * plist. launchd has no native `RandomizedDelaySec`; the idiomatic equivalent
+ * is a per-job `Minute` shift baked into each `StartCalendarInterval` dict.
+ * The value is generated ONCE at init time so the plist is stable across
+ * reboots (no flapping), and the SAME offset applies to every slot so the
+ * relative spacing between slots is preserved.
+ *
+ * `jitterSec` < 60 → 0 (cannot span a minute). Inject `rand` for deterministic
+ * tests; defaults to Math.random (init-time generation, not the hot path).
+ */
+function randomMinuteOffset(jitterSec, rand = Math.random) {
+    if (!Number.isFinite(jitterSec) || jitterSec < 60)
+        return 0;
+    const max = Math.min(59, Math.floor(jitterSec / 60));
+    if (max <= 0)
+        return 0;
+    return Math.floor(rand() * (max + 1));
+}
 /**
  * Capture-watchdog poll interval (minutes). The capture timer fires
  * `nightly --capture-only --watchdog` this often; the watchdog itself throttles
@@ -1826,18 +1905,36 @@ function formatOnCalendarLines(hours) {
  * The launchd `StartCalendarInterval` ARRAY body — one `<dict>` per hour.
  * launchd fires the job at each dict; a single dict is the 1-slot special case
  * but the array form is uniform across 1..N. Exported for testing.
+ *
+ * `minuteOffset` (#256): a per-install randomized Minute applied uniformly to
+ * every slot (0 = no offset = pre-#256 behaviour). See `randomMinuteOffset`.
  */
-function formatLaunchdIntervals(hours) {
+function formatLaunchdIntervals(hours, minuteOffset = 0) {
+    const minute = Math.max(0, Math.min(59, Math.floor(minuteOffset)));
     return [...hours]
         .sort((a, b) => a - b)
         .map((h) => `    <dict>
       <key>Hour</key>
       <integer>${h}</integer>
       <key>Minute</key>
-      <integer>0</integer>
+      <integer>${minute}</integer>
     </dict>`)
         .join("\n");
 }
+/**
+ * The systemd `[Timer]` body (everything between `[Timer]` and the next stanza).
+ * Exported for testing the #256 jitter line. `isInterval` selects the watchdog
+ * poll form (OnBootSec + OnUnitActiveSec); otherwise one `OnCalendar` line per
+ * hour. When `jitterSec > 0` a single `RandomizedDelaySec=<n>` is appended — it
+ * applies to every OnCalendar entry AND to OnUnitActiveSec (systemd semantics).
+ */
+function formatSystemdTimerBody(isInterval, intervalSec, hours, jitterSec) {
+    const base = isInterval
+        ? `OnBootSec=2min\nOnUnitActiveSec=${Math.round(intervalSec / 60)}min`
+        : formatOnCalendarLines(hours);
+    const jitter = jitterSec > 0 ? `\nRandomizedDelaySec=${jitterSec}` : "";
+    return base + jitter;
+}
 /**
  * Write + enable one schedule unit (timer + service on Linux, plist on macOS),
  * multi-slot. Shared by the capture and consolidation installers. Always
@@ -1873,9 +1970,17 @@ function writeScheduleUnit(opts) {
         // gets a first capture tick on load (~parity with systemd's OnBootSec=2min),
         // not 20 min later. The cooldown gate makes a load-time fire a cheap no-op
         // if a capture ran recently.
+        //
+        // #256 — jitter: launchd has no native RandomizedDelaySec, so the slot
+        // plist bakes a per-install randomized Minute offset into every dict
+        // (generated here, stable across reboots). The interval/watchdog plist
+        // keeps its StartInterval untouched — interval timers drift naturally and
+        // don't share the fixed-slot thundering-herd risk.
+        const jitterSec = opts.jitterSec ?? resolveTimerJitterSeconds();
+        const minuteOffset = !isInterval ? randomMinuteOffset(jitterSec) : 0;
         const scheduleBlock = isInterval
             ? `  <key>StartInterval</key>\n  <integer>${opts.intervalSec}</integer>\n  <key>RunAtLoad</key>\n  <true/>`
-            : `  <key>StartCalendarInterval</key>\n  <array>\n${formatLaunchdIntervals(opts.hours)}\n  </array>`;
+            : `  <key>StartCalendarInterval</key>\n  <array>\n${formatLaunchdIntervals(opts.hours, minuteOffset)}\n  </array>`;
         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">
@@ -1933,9 +2038,9 @@ Environment=HOME=${(0, node_os_1.homedir)()}
 WorkingDirectory=${(0, node_os_1.homedir)()}`;
         // Timer body: OnUnitActiveSec (interval, watchdog) or one OnCalendar line
         // per hour (multi-slot). systemd ORs multiple OnCalendar entries.
-        const timerBody = isInterval
-            ? `OnBootSec=2min\nOnUnitActiveSec=${Math.round(opts.intervalSec / 60)}min`
-            : formatOnCalendarLines(opts.hours);
+        // #256 — a single RandomizedDelaySec=<jitterSec> applies to all entries.
+        const jitterSec = opts.jitterSec ?? resolveTimerJitterSeconds();
+        const timerBody = formatSystemdTimerBody(isInterval, opts.intervalSec ?? 0, opts.hours ?? [], jitterSec);
         const timer = `[Unit]
 Description=${opts.timerDesc}