@aitne/daemon 0.1.9 → 0.1.11

package/dist/core/skills-compiler.js

@@ -5,7 +5,7 @@ import { composeSkillSet, getProfileForEvent, getProfileForProcess, resolveSkill
 import { applyCharacterBlockRewrite, buildCharacterBlock } from "./character-block.js";
 import { applyOutputLanguagePointerRewrite } from "./output-language-policy.js";
 import { createLogger } from "../logging.js";
-import { loadFetchWindowSystemPrompt } from "./fetch-window-prompt-loader.js";
+import { loadSlimSystemPrompt } from "./slim-system-prompt-loader.js";
 import { substituteIntegrationRoutingTables } from "./management-md.js";
 import { loadCurationDeclaration, } from "./skill-curation/declarations.js";
 import { resolveBuiltinSkillDir } from "./skill-source-paths.js";
@@ -21,18 +21,43 @@ import { cliInstructionFileName, cliSkillsDirName, prependCodexReadSensitiveBann
 // spliceCurationAnchorsInSkill). Not exported — sibling modules carry
 // their own peer loggers; the test suite spies on those.
 const logger = createLogger("skills-compiler");
-// docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — single shared constant
-// for the pre-pass process key. Typed as `ProcessKey` (not the inferred
-// string literal) so a rename in `@aitne/shared/process-key.ts` lights up
-// here rather than silently dead-branching the slim materializer.
-const FETCH_WINDOW_PROCESS_KEY = "routine.fetch_window";
-// Single skill kept in the slim fetch_window CLI session: the
-// `observations` SKILL.md is the POST contract for
-// `/api/observations/batch` and the fetcher's only structural assertion.
-// The other skills the wide path inlines (`mail`, `notion`,
-// `external-services`, `attach`) are already restated by the integration
-// partial the runner inlines into the user prompt.
-const FETCH_WINDOW_SLIM_SKILL = "observations";
+// Per-slim-key CLI skill bundle copied into the slim Codex / Gemini session
+// (RESEARCH_CLUSTER_COST_FIX_PLAN.md F4 generalizes fetch-window-cost-reduction.md
+// Phase 1.5). The slim materializer writes the slim system-prompt body — the
+// SAME template the Claude SDK gets, via the shared `slim-system-prompt-loader`
+// registry — as AGENTS.md / GEMINI.md and copies ONLY these skill dirs; the
+// wide manifest's other slugs are restated by the task-flow / user prompt, so
+// inlining them would re-bloat the session.
+//
+// Keys MUST mirror `SLIM_SYSTEM_PROMPT_LOADERS` (drift-guarded by a unit test):
+// a slim system prompt with no CLI skill set — or vice versa — is a wiring bug.
+// Typed `Partial<Record<ProcessKey, …>>` so a key rename in
+// `@aitne/shared/process-key.ts` lights up here rather than dead-branching.
+//   - routine.fetch_window — the `observations` SKILL.md is the
+//     `/api/observations/batch` POST contract and the fetcher's only
+//     structural assertion; the integration partial the runner inlines covers
+//     the rest (`mail` / `notion` / `external-services` / `attach` dropped).
+//   - routine.research_cluster_update — `browser-history` (the
+//     `/api/browser-history/*` curl surface) + `context` (the research-journal
+//     write path); the task-flow inlines the endpoints + journal template.
+export const SLIM_CLI_SKILL_SETS = {
+    "routine.fetch_window": ["observations"],
+    "routine.research_cluster_update": ["browser-history", "context"],
+};
+/**
+ * The slim process key for this session, or null when it is not a slim key.
+ * Accepts the `processKey ?? eventType` union the CLI materializer threads
+ * (an event-type string that is not a registered ProcessKey simply misses the
+ * `in` check). Keyed off `SLIM_CLI_SKILL_SETS`, which the drift guard pins to
+ * `SLIM_SYSTEM_PROMPT_LOADERS`.
+ */
+function slimCliKeyFor(processKeyOrEvent) {
+    if (processKeyOrEvent === undefined)
+        return null;
+    return processKeyOrEvent in SLIM_CLI_SKILL_SETS
+        ? processKeyOrEvent
+        : null;
+}
 /**
  * Materializes backend-specific instruction files for session workdirs
  * by reading directly from the source tree (agent-assets/agent-profiles/ and
@@ -238,15 +263,17 @@ export class SkillsCompiler {
         else {
             this.materializeCliSession(params.sessionDir, profileName, skills, params.backendId, params.processKey ?? params.eventType, profileBodyOverride, params.wikiWorkspaceName);
         }
-        // docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — the slim
-        // CLI materializer drops every manifest skill except `observations`.
-        // The Claude path is wide for fetch_window today (Phase 1 swaps only
-        // the system prompt, not the workdir layout). Report what was
-        // actually written so log lines / callers see truth, not the
-        // manifest's pre-narrow list.
-        const effectiveSkills = params.backendId !== "claude"
-            && (params.processKey ?? params.eventType) === FETCH_WINDOW_PROCESS_KEY
-            ? [FETCH_WINDOW_SLIM_SKILL]
+        // fetch-window-cost-reduction.md Phase 1.5 / RESEARCH_CLUSTER_COST_FIX_PLAN.md
+        // F4 — the slim CLI materializer drops every manifest skill except the
+        // key's `SLIM_CLI_SKILL_SETS` bundle. The Claude path stays wide today
+        // (Phase 1/F4 swap only the system prompt + settingSources, not the
+        // workdir layout). Report what was actually written so log lines /
+        // callers see truth, not the manifest's pre-narrow list.
+        const slimCliKey = params.backendId !== "claude"
+            ? slimCliKeyFor(params.processKey ?? params.eventType)
+            : null;
+        const effectiveSkills = slimCliKey
+            ? [...(SLIM_CLI_SKILL_SETS[slimCliKey] ?? [])]
             : skills;
         return { profile: profileName, skills: effectiveSkills };
     }
@@ -689,95 +716,104 @@ export class SkillsCompiler {
     }
     /**
      * docs/design/appendices/skills-unification.md Phase 1 item 15 — the slim path does NOT
-     * emit a `<skill-index>` block or the skill-discovery preamble. The
-     * fetch_window system prompt is a self-contained operational contract
-     * (one-window-one-curl, no sub-tasks, exactly-one JSON-on-stdout) and
-     * the only skill copied (`observations`) is referenced inline by the
-     * runner-emitted user prompt. Adding the index would mis-signal the
-     * fetcher to scan for skills before executing the acquisition plan.
+     * emit a `<skill-index>` block or the skill-discovery preamble. The slim
+     * system prompt is a self-contained operational contract and its copied
+     * skills are referenced inline by the dispatched user prompt / task-flow.
+     * Adding the index would mis-signal the agent to scan for skills before
+     * executing its mechanical task.
      *
-     * docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — slim instruction-file
-     * materializer for `routine.fetch_window` on Codex / Gemini CLI.
+     * fetch-window-cost-reduction.md Phase 1.5 / RESEARCH_CLUSTER_COST_FIX_PLAN.md
+     * F4 — slim instruction-file materializer for a `SLIM_CLI_SKILL_SETS` process
+     * key on Codex / Gemini CLI.
      *
-     * Mirrors the Claude SDK's Phase 1 systemPrompt swap (the same
-     * `agent-assets/system-prompts/routine-fetch-window.md` template is the
-     * single source of truth): write the slim body verbatim as AGENTS.md /
-     * GEMINI.md and copy only the `observations` skill — the
-     * `/api/observations/batch` POST contract is the fetcher's sole
-     * structural assertion. The integration partial inlined by the runner
-     * (`routine-fetch-window-runner.ts:reassemblePrompt`) covers the
-     * per-attempt call shape, so `mail` / `notion` / `external-services` /
-     * `attach` skill bodies are deliberately omitted.
+     * Mirrors the Claude SDK's slim-systemPrompt swap (the same
+     * `agent-assets/system-prompts/<key>.md` template is the single source of
+     * truth, read through the shared `loadSlimSystemPrompt` registry): write the
+     * slim body verbatim as AGENTS.md / GEMINI.md and copy only the key's
+     * `SLIM_CLI_SKILL_SETS` bundle — the wide manifest's other slugs are restated
+     * by the dispatched user prompt / task-flow, so their bodies are omitted.
      *
-     * No safety preamble / character / behavioral-rules / daemon-API
-     * sections — the slim template restates the only rules the fetcher
-     * needs (localhost-only curl, no sub-tasks, no context writes, no
-     * notify, JSON-on-stdout-and-exit). The destructive-action policy layer
-     * (absolute-block list, Codex sandbox, Gemini admin TOML) still applies
-     * unchanged at runtime.
+     * No safety preamble / character / behavioral-rules / daemon-API sections —
+     * the slim template restates the only rules the session needs. The
+     * destructive-action policy layer (absolute-block list, Codex sandbox,
+     * Gemini admin TOML) still applies unchanged at runtime.
      *
      * The `<mcp-servers>` section is appended downstream by
      * `services/mcp/session-materializer.ts:appendMcpSection` exactly as on
-     * the wide path — Phase 3's allowlist filter, when it lands, will scope
-     * that section without further changes here.
+     * the wide path.
      */
-    materializeFetchWindowCliSession(sessionDir, backendId) {
+    materializeSlimCliSession(sessionDir, backendId, processKey) {
+        const skillSlugs = SLIM_CLI_SKILL_SETS[processKey];
+        // Defensive: the caller only diverts registered slim keys, but guard so a
+        // future divert bug fails loud rather than writing an empty session.
+        if (skillSlugs === undefined)
+            return;
+        const slim = loadSlimSystemPrompt(processKey);
+        if (slim === null)
+            return; // Unreachable for registered keys; satisfies the type.
         mkdirSync(sessionDir, { recursive: true });
-        const slim = loadFetchWindowSystemPrompt();
         writeFileSync(join(sessionDir, cliInstructionFileName(backendId)), slim, "utf-8");
-        // Copy ONLY the `observations` skill dir. The wide path's prune step
-        // is replaced by an explicit single-slug list — `pruneStaleBuiltinSkillDirs`
+        // Copy ONLY the key's slim skill dirs. The wide path's prune step is
+        // replaced by the explicit slug list — `pruneStaleBuiltinSkillDirs`
         // removes any other built-in skill dir that a prior re-materialization
         // (e.g. a fallback-driven wide path on the same workdir) may have left.
         const cliSkillsRoot = cliSkillsDirName(backendId);
         if (cliSkillsRoot === null)
-            return; // Claude-only — fetch_window slim runs on Claude SDK natively.
+            return; // Claude-only — slim keys run on Claude SDK natively.
         const skillsRoot = this.getSourceSkillsRoot();
         const destSkillsRoot = join(sessionDir, cliSkillsRoot, "skills");
         mkdirSync(destSkillsRoot, { recursive: true });
-        pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, [FETCH_WINDOW_SLIM_SKILL]);
-        const src = resolveBuiltinSkillDir(skillsRoot, FETCH_WINDOW_SLIM_SKILL);
+        pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, [...skillSlugs]);
+        for (const slug of skillSlugs) {
+            this.copySlimSkillDir(destSkillsRoot, skillsRoot, slug, backendId);
+        }
+    }
+    /**
+     * Copy one built-in skill dir into a slim CLI session, applying the same
+     * adaptation pipeline the wide CLI path runs (brand tokens, partial /
+     * reference includes, integration-mode filter, tool-deny prose, curation
+     * anchors). Frontmatter stays intact (skills-unification.md §R6). A
+     * no-op when the source SKILL.md is absent.
+     */
+    copySlimSkillDir(destSkillsRoot, skillsRoot, slug, backendId) {
+        const src = resolveBuiltinSkillDir(skillsRoot, slug);
         const skillMdPath = join(src, "SKILL.md");
         if (!existsSync(skillMdPath))
             return;
-        const destDir = join(destSkillsRoot, FETCH_WINDOW_SLIM_SKILL);
+        const destDir = join(destSkillsRoot, slug);
         cpSync(src, destDir, { recursive: true });
         substituteBrandTokensInDir(destDir);
-        // No `substituteWikiWorkspaceTokensInDir` — fetch_window never touches
-        // wiki workspace state, and the resolver is a no-op for non-wiki
-        // process keys anyway.
+        // No `substituteWikiWorkspaceTokensInDir` — no slim key touches wiki
+        // workspace state, and the resolver is a no-op for non-wiki keys anyway.
         let adapted = substituteBrandTokens(readFileSync(skillMdPath, "utf-8"));
-        // observations/SKILL.md ships no `{{> base }}` or `{{> ref:* }}`
-        // directives today, but run the resolvers anyway so a future curation
+        // Run the partial / reference resolvers even on bodies that ship no
+        // `{{> base }}` / `{{> ref:* }}` directives today, so a future curation
         // edit cannot silently drop content. Idempotent on plain content.
         adapted = substituteBrandTokens(renderPartialIncludes(adapted, join(src, "SKILL.base.md")));
         adapted = substituteBrandTokens(renderReferenceIncludes(adapted, src));
-        // Mode-conditional filter — observations/SKILL.md carries
-        // `<!-- mode:<predicate>:notion -->` markers (lines 273-345 today)
-        // because the source / consume contract differs across `direct` /
-        // `delegated-same` / `delegated-cross` / `native` / `disabled`. The
-        // wide path applies this filter at `materializeCliSession`; the
-        // slim path must match so the agent doesn't get every mode's prose
-        // for every integration. Idempotent on bodies that lack markers.
+        // Mode-conditional filter — skills (e.g. observations/SKILL.md) carry
+        // `<!-- mode:<predicate>:<integration> -->` markers because the
+        // source / consume contract differs across `direct` / `delegated-same` /
+        // `delegated-cross` / `native` / `disabled`. The wide path applies this
+        // at `materializeCliSession`; the slim path must match so the agent
+        // doesn't get every mode's prose. Idempotent on bodies that lack markers.
         adapted = applyIntegrationModeFilter(adapted, this.integrations, backendId);
-        // Tool-deny policy stays in force — even though the fetcher is fed a
-        // narrow allowlist, the soft-enforcement prose lands in the body
-        // BEFORE the CLI frontmatter strip so it's not lost.
-        adapted = applyAllDeniedToolsForSkill(adapted, FETCH_WINDOW_SLIM_SKILL, backendId, this.integrations);
-        // docs/design/appendices/skills-unification.md Phase 1 §R6 — frontmatter stays intact
-        // across all backends. `adaptSkillForCli` is gone; the source body's
-        // YAML preamble flows through verbatim.
+        // Tool-deny policy stays in force — even with a narrow allowlist, the
+        // soft-enforcement prose lands in the body BEFORE the CLI frontmatter
+        // strip so it's not lost.
+        adapted = applyAllDeniedToolsForSkill(adapted, slug, backendId, this.integrations);
         writeFileSync(join(destDir, "SKILL.md"), adapted, "utf-8");
-        this.spliceCurationAnchorsInSkill(destDir, FETCH_WINDOW_SLIM_SKILL);
+        this.spliceCurationAnchorsInSkill(destDir, slug);
     }
     materializeCliSession(sessionDir, profileName, skillSlugs, backendId, processKey, profileBodyOverride, wikiWorkspaceName) {
-        // docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — divert
-        // `routine.fetch_window` to a slim materializer that mirrors the
-        // Claude SDK's Phase 1 systemPrompt swap. Custom bang commands cannot
-        // reach this branch (they bind to `messaging.custom_command`), so
+        // fetch-window-cost-reduction.md Phase 1.5 / RESEARCH_CLUSTER_COST_FIX_PLAN.md
+        // F4 — divert a slim process key to the slim materializer that mirrors the
+        // Claude SDK's slim-systemPrompt swap. Custom bang commands cannot reach
+        // this branch (they bind to `messaging.custom_command`), so
         // `profileBodyOverride` is intentionally NOT forwarded.
-        if (processKey === FETCH_WINDOW_PROCESS_KEY) {
-            this.materializeFetchWindowCliSession(sessionDir, backendId);
+        const slimKey = slimCliKeyFor(processKey);
+        if (slimKey) {
+            this.materializeSlimCliSession(sessionDir, backendId, slimKey);
             return;
         }
         // docs/design/appendices/skills-unification.md Phase 1 — directory-based skill delivery.

package/dist/core/skills-manifest.d.ts

@@ -106,6 +106,43 @@ export declare function resolveSkillManifestForProcess(processKey: ProcessKey, o
     db?: Database.Database | null;
     messageText?: string | null;
 }): string[];
+/**
+ * Event-type / process-key families whose sessions do NOT receive the
+ * owner's user-authored skill library (`<contextDir>/policies/skills/`).
+ *
+ * User skills are general assistant extensions the owner writes for their
+ * conversational agent; `syncAllUserSkills` provisions them into a session
+ * workdir ON TOP of the process key's built-in manifest. Narrow-persona
+ * sessions run under dedicated profiles with tight, purpose-built manifests
+ * — dumping the full user-skill library into them is pure cold-start cost +
+ * attention dilution and never load-bearing (their work is fully covered by
+ * the built-in bundle, and the wiki/research skills are themselves
+ * built-ins, not user-authored).
+ *
+ * Excluded families:
+ *   - `wiki.*`             — the wiki-agent persona (ingest_url / compile /
+ *                            ask / lint / trace / connect).
+ *   - `routine.research_*` — the browser-history research routines
+ *                            (cluster_update / offer_dm / dispatch /
+ *                            wiki_summary).
+ *
+ * Everything else (the conversational DM agent, DM-tone scheduled sessions,
+ * the daily/weekly/monthly routines, setup, knowledge import, git/github
+ * observers, scheduled tasks) keeps the prior "every user skill, every
+ * session" behaviour.
+ */
+export declare const USER_SKILL_EXCLUDED_PREFIXES: readonly string[];
+/**
+ * Whether a session for `eventTypeOrProcessKey` should be provisioned with
+ * the owner's user-authored skills. Keyed on the SAME string the skill
+ * manifest resolves against (`processKey ?? eventType`) so the gate and the
+ * built-in manifest agree on what a session is.
+ *
+ * Gates the `syncAllUserSkills` call at every materialisation chokepoint
+ * (`createSessionWorkdir`, `ensureSessionWorkdir`, and the backend-fallback
+ * re-materialiser). See `USER_SKILL_EXCLUDED_PREFIXES`.
+ */
+export declare function eventTypeAcceptsUserSkills(eventTypeOrProcessKey: string): boolean;
 export declare function getProfileForEvent(eventType: string): string;
 export declare function getSkillsForEvent(eventType: string): string[];
 export declare function getProfileForProcess(processKey: ProcessKey): string;

package/dist/core/skills-manifest.js

@@ -127,7 +127,7 @@ export const EVENT_SKILL_SETS = {
         "roadmap",
         "management-policy",
     ],
-    "routine.hourly_check": [
+    "routine.activity_scan": [
         "context",
         "today",
         "observations",
@@ -260,6 +260,14 @@ export const EVENT_SKILL_SETS = {
         // (no prior research offer to respond to) — that exclusion does
         // not generalise.
         "browser-task",
+        // BACKGROUND_TASK_RUNNER_DESIGN.md §5 / Phase 3 — DM-driven entry
+        // point to hand a long-running / open-ended task to the detached
+        // background runner. Loaded for the first DM too: the user's literal
+        // first message ("research X for me", "audit my repos") is exactly
+        // the spawn surface. The `background-task-reply` clarify skill is
+        // correctly absent here — no prior task can be parked on the very
+        // first DM of a session — exactly as `browser-history-respond` is.
+        "background-task",
     ],
     "message.received.dm": [
         "context",
@@ -305,6 +313,20 @@ export const EVENT_SKILL_SETS = {
         // the agent simply does not call its endpoints when the user's
         // request doesn't ask for a browser task.
         "browser-task",
+        // BACKGROUND_TASK_RUNNER_DESIGN.md §5 / Phase 3 — the generic
+        // long-running-task surface. `background-task` teaches the DM agent
+        // to compose a self-contained brief, set the notification policy,
+        // POST + ack + end the turn, and read `GET /:id` for follow-up
+        // detail. `background-task-reply` is the narrow clarify-relay (mirror
+        // of `browser-history-respond`) that translates the owner's answer to
+        // a parked task's question into `POST /:id/clarify`. Loaded for
+        // `message.received.dm` (which `message.dm` + `dashboard.chat`
+        // inherit via PROCESS_TO_EVENT_TYPE). The reply skill is NOT on
+        // `message.received.dm_first` (no task can be parked on a session's
+        // first DM). No conditional gate: both skill bodies no-op when their
+        // endpoints have nothing to act on, and the in-context cost is small.
+        "background-task",
+        "background-task-reply",
     ],
     // ── Task events ──
     "schedule.approaching": [
@@ -564,6 +586,13 @@ export const ALL_SKILLS = [
     // `browser-history-managed` skill that fronted the frozen workflow
     // registry was retired alongside the route + routines in Phase 6.
     "browser-task",
+    // BACKGROUND_TASK_RUNNER_DESIGN.md §5 / Phase 3 — generic detached
+    // long-task surface. `background-task` (spawn) loads on
+    // `message.received.dm` + `message.received.dm_first`;
+    // `background-task-reply` (clarify relay) loads on `message.received.dm`
+    // only. Both are DM-agent-exclusive, like browser-task.
+    "background-task",
+    "background-task-reply",
     // Scheduling split — `/schedule` is one-shot only; recurring tasks are
     // Agents. This skill teaches the DM agent to author a detailed recurring
     // Agent (`POST /api/agents`) when the user asks for an ongoing cadence.
@@ -579,7 +608,7 @@ const PROCESS_TO_EVENT_TYPE = {
     "routine.evening_review": "routine.evening_review",
     "routine.weekly_review": "routine.weekly_review",
     "routine.monthly_review": "routine.monthly_review",
-    "routine.hourly_check": "routine.hourly_check",
+    "routine.activity_scan": "routine.activity_scan",
     "routine.roadmap_refresh": "routine.roadmap_refresh",
     "routine.today_refresh": "routine.today_refresh",
     "routine.user_profile_sweep": "routine.user_profile_sweep",
@@ -887,6 +916,48 @@ export function resolveSkillManifest(eventType, opts) {
 export function resolveSkillManifestForProcess(processKey, opts) {
     return resolveSkillManifest(PROCESS_TO_EVENT_TYPE[processKey] ?? processKey, opts);
 }
+/**
+ * Event-type / process-key families whose sessions do NOT receive the
+ * owner's user-authored skill library (`<contextDir>/policies/skills/`).
+ *
+ * User skills are general assistant extensions the owner writes for their
+ * conversational agent; `syncAllUserSkills` provisions them into a session
+ * workdir ON TOP of the process key's built-in manifest. Narrow-persona
+ * sessions run under dedicated profiles with tight, purpose-built manifests
+ * — dumping the full user-skill library into them is pure cold-start cost +
+ * attention dilution and never load-bearing (their work is fully covered by
+ * the built-in bundle, and the wiki/research skills are themselves
+ * built-ins, not user-authored).
+ *
+ * Excluded families:
+ *   - `wiki.*`             — the wiki-agent persona (ingest_url / compile /
+ *                            ask / lint / trace / connect).
+ *   - `routine.research_*` — the browser-history research routines
+ *                            (cluster_update / offer_dm / dispatch /
+ *                            wiki_summary).
+ *
+ * Everything else (the conversational DM agent, DM-tone scheduled sessions,
+ * the daily/weekly/monthly routines, setup, knowledge import, git/github
+ * observers, scheduled tasks) keeps the prior "every user skill, every
+ * session" behaviour.
+ */
+export const USER_SKILL_EXCLUDED_PREFIXES = [
+    "wiki.",
+    "routine.research_",
+];
+/**
+ * Whether a session for `eventTypeOrProcessKey` should be provisioned with
+ * the owner's user-authored skills. Keyed on the SAME string the skill
+ * manifest resolves against (`processKey ?? eventType`) so the gate and the
+ * built-in manifest agree on what a session is.
+ *
+ * Gates the `syncAllUserSkills` call at every materialisation chokepoint
+ * (`createSessionWorkdir`, `ensureSessionWorkdir`, and the backend-fallback
+ * re-materialiser). See `USER_SKILL_EXCLUDED_PREFIXES`.
+ */
+export function eventTypeAcceptsUserSkills(eventTypeOrProcessKey) {
+    return !USER_SKILL_EXCLUDED_PREFIXES.some((prefix) => eventTypeOrProcessKey.startsWith(prefix));
+}
 export function getProfileForEvent(eventType) {
     for (const rule of PROFILE_RULES) {
         if (rule.exact ? eventType === rule.prefix : eventType.startsWith(rule.prefix)) {

package/dist/core/sleep-inhibitor.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Keep-awake posture while the daemon runs (`preventSleepMode` setting):
+ *
+ * - `"off"`    — never inhibit sleep.
+ * - `"ac"`     — inhibit system sleep only while on AC power
+ *                (macOS `caffeinate -s`; battery drain stays impossible).
+ * - `"always"` — additionally inhibit idle sleep on battery
+ *                (macOS `caffeinate -i -s`).
+ *
+ * Why this exists: every timer in the daemon (node-cron, WakeDetector,
+ * in-flight agent sessions) freezes while the host sleeps. A sleeping
+ * laptop turns the 04:00 day-boundary flow into hours of wake-catchup
+ * replays riding macOS maintenance DarkWakes — each replay re-fires
+ * day-boundary work in a 1–2 minute window before the machine re-sleeps,
+ * and cold prompt caches make those runs 10× the normal cost. Keeping
+ * the machine awake while plugged in removes that failure mode at the
+ * source; server installs (which never sleep) are unaffected.
+ *
+ * macOS only. `caffeinate` cannot override lid-close (clamshell) sleep —
+ * that needs root (`pmset disablesleep 1`), which the daemon must not
+ * touch. Windows/Linux hosts running this daemon are assumed to be
+ * servers or desktops with OS-level power management; the inhibitor is a
+ * no-op there and logs once at debug level.
+ */
+export declare const PREVENT_SLEEP_MODES: readonly ["off", "ac", "always"];
+export type PreventSleepMode = (typeof PREVENT_SLEEP_MODES)[number];
+/** Respawns allowed after an unexpected `caffeinate` exit before giving up. */
+export declare const SLEEP_INHIBITOR_MAX_RESPAWNS = 3;
+/** Pause before a respawn so a persistently-dying binary cannot tight-loop. */
+export declare const SLEEP_INHIBITOR_RESPAWN_DELAY_MS = 5000;
+export interface SleepInhibitCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * Pure command resolver — `null` means "do not inhibit" (mode off or
+ * unsupported platform). `-w <pid>` ties the power assertion to the
+ * daemon process itself, so the assertion is released even if the daemon
+ * is SIGKILLed and `stop()` never runs.
+ */
+export declare function resolveSleepInhibitCommand(platform: NodeJS.Platform, mode: PreventSleepMode, pid: number): SleepInhibitCommand | null;
+export interface SleepInhibitorChild {
+    on(event: "error", listener: (err: Error) => void): unknown;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
+    unref(): void;
+    pid?: number;
+}
+export type SleepInhibitorSpawn = (command: string, args: readonly string[]) => SleepInhibitorChild;
+export interface SleepInhibitorOptions {
+    mode: PreventSleepMode;
+    /** Injectable for tests; defaults to the host platform. */
+    platform?: NodeJS.Platform;
+    /** Injectable for tests; defaults to the daemon's own pid. */
+    pid?: number;
+    spawnFn?: SleepInhibitorSpawn;
+    respawnDelayMs?: number;
+}
+/**
+ * Holds a `caffeinate` child for the daemon's lifetime. Crash-safe by
+ * construction (`-w pid` above); `stop()` exists for symmetric shutdown
+ * and to suppress the respawn path during graceful exit.
+ */
+export declare class SleepInhibitor {
+    private readonly mode;
+    private readonly platform;
+    private readonly pid;
+    private readonly spawnFn;
+    private readonly respawnDelayMs;
+    private child;
+    private respawnTimer;
+    private respawns;
+    private started;
+    private stopped;
+    constructor(options: SleepInhibitorOptions);
+    start(): void;
+    stop(): void;
+    private spawnChild;
+}

package/dist/core/sleep-inhibitor.js

@@ -0,0 +1,132 @@
+import { spawn } from "node:child_process";
+import { createLogger } from "../logging.js";
+const logger = createLogger("sleep-inhibitor");
+/**
+ * Keep-awake posture while the daemon runs (`preventSleepMode` setting):
+ *
+ * - `"off"`    — never inhibit sleep.
+ * - `"ac"`     — inhibit system sleep only while on AC power
+ *                (macOS `caffeinate -s`; battery drain stays impossible).
+ * - `"always"` — additionally inhibit idle sleep on battery
+ *                (macOS `caffeinate -i -s`).
+ *
+ * Why this exists: every timer in the daemon (node-cron, WakeDetector,
+ * in-flight agent sessions) freezes while the host sleeps. A sleeping
+ * laptop turns the 04:00 day-boundary flow into hours of wake-catchup
+ * replays riding macOS maintenance DarkWakes — each replay re-fires
+ * day-boundary work in a 1–2 minute window before the machine re-sleeps,
+ * and cold prompt caches make those runs 10× the normal cost. Keeping
+ * the machine awake while plugged in removes that failure mode at the
+ * source; server installs (which never sleep) are unaffected.
+ *
+ * macOS only. `caffeinate` cannot override lid-close (clamshell) sleep —
+ * that needs root (`pmset disablesleep 1`), which the daemon must not
+ * touch. Windows/Linux hosts running this daemon are assumed to be
+ * servers or desktops with OS-level power management; the inhibitor is a
+ * no-op there and logs once at debug level.
+ */
+export const PREVENT_SLEEP_MODES = ["off", "ac", "always"];
+/** Respawns allowed after an unexpected `caffeinate` exit before giving up. */
+export const SLEEP_INHIBITOR_MAX_RESPAWNS = 3;
+/** Pause before a respawn so a persistently-dying binary cannot tight-loop. */
+export const SLEEP_INHIBITOR_RESPAWN_DELAY_MS = 5_000;
+/**
+ * Pure command resolver — `null` means "do not inhibit" (mode off or
+ * unsupported platform). `-w <pid>` ties the power assertion to the
+ * daemon process itself, so the assertion is released even if the daemon
+ * is SIGKILLed and `stop()` never runs.
+ */
+export function resolveSleepInhibitCommand(platform, mode, pid) {
+    if (mode === "off")
+        return null;
+    if (platform !== "darwin")
+        return null;
+    const flags = mode === "always" ? ["-i", "-s"] : ["-s"];
+    return { command: "caffeinate", args: [...flags, "-w", String(pid)] };
+}
+const defaultSpawn = (command, args) => spawn(command, args, { stdio: "ignore" });
+/**
+ * Holds a `caffeinate` child for the daemon's lifetime. Crash-safe by
+ * construction (`-w pid` above); `stop()` exists for symmetric shutdown
+ * and to suppress the respawn path during graceful exit.
+ */
+export class SleepInhibitor {
+    mode;
+    platform;
+    pid;
+    spawnFn;
+    respawnDelayMs;
+    child = null;
+    respawnTimer = null;
+    respawns = 0;
+    started = false;
+    stopped = false;
+    constructor(options) {
+        this.mode = options.mode;
+        this.platform = options.platform ?? process.platform;
+        this.pid = options.pid ?? process.pid;
+        this.spawnFn = options.spawnFn ?? defaultSpawn;
+        this.respawnDelayMs =
+            options.respawnDelayMs ?? SLEEP_INHIBITOR_RESPAWN_DELAY_MS;
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const cmd = resolveSleepInhibitCommand(this.platform, this.mode, this.pid);
+        if (!cmd) {
+            logger.debug({ mode: this.mode, platform: this.platform }, "Sleep inhibitor inactive (mode off or unsupported platform)");
+            return;
+        }
+        this.spawnChild(cmd);
+    }
+    stop() {
+        this.stopped = true;
+        if (this.respawnTimer) {
+            clearTimeout(this.respawnTimer);
+            this.respawnTimer = null;
+        }
+        // Kill but leave `this.child` set — the exit handler clears it and the
+        // `stopped` flag suppresses the respawn path.
+        this.child?.kill("SIGTERM");
+    }
+    spawnChild(cmd) {
+        let child;
+        try {
+            child = this.spawnFn(cmd.command, cmd.args);
+        }
+        catch (err) {
+            logger.warn({ err, command: cmd.command }, "Sleep inhibitor spawn failed — system sleep stays OS-managed");
+            return;
+        }
+        this.child = child;
+        // The inhibitor must never keep the event loop alive on its own.
+        child.unref();
+        child.on("error", (err) => {
+            // ENOENT and friends — the binary is missing or unrunnable, which a
+            // respawn cannot fix. Warn once and fall back to OS-managed sleep.
+            this.child = null;
+            logger.warn({ err, command: cmd.command }, "Sleep inhibitor process errored — system sleep stays OS-managed");
+        });
+        child.on("exit", (code, signal) => {
+            if (this.child !== child)
+                return; // killed by stop() or replaced
+            this.child = null;
+            if (this.stopped)
+                return;
+            if (this.respawns >= SLEEP_INHIBITOR_MAX_RESPAWNS) {
+                logger.error({ code, signal, respawns: this.respawns }, "Sleep inhibitor exited repeatedly — giving up; system sleep stays OS-managed");
+                return;
+            }
+            this.respawns += 1;
+            logger.warn({ code, signal, attempt: this.respawns }, "Sleep inhibitor exited unexpectedly — respawning");
+            this.respawnTimer = setTimeout(() => {
+                this.respawnTimer = null;
+                if (!this.stopped)
+                    this.spawnChild(cmd);
+            }, this.respawnDelayMs);
+            this.respawnTimer.unref?.();
+        });
+        logger.info({ command: cmd.command, args: cmd.args, mode: this.mode }, "Sleep inhibitor active");
+    }
+}