@aitne/daemon 0.1.10 → 0.1.11

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");
+    }
+}

package/dist/core/slim-system-prompt-loader.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Single source of truth for the daemon's per-process **slim** system-prompt
+ * templates. A slim prompt replaces the verbose `preset: "claude_code"` system
+ * prompt (Claude SDK) / the wide profile + skill-index instruction file
+ * (Codex / Gemini CLI) with a tight, self-contained operational contract for
+ * one short, mechanical, lite-tier process key — shedding ~30 K tokens of
+ * built-in tool descriptions, the skills index, the memory-system docs, and
+ * tone/style guidance the key never uses.
+ *
+ * Two cost-reduction efforts share this registry:
+ *   - `routine.fetch_window` — docs/design/appendices/fetch-window-cost-reduction.md
+ *     Phase 1 / 1.5 (the original slim prompt).
+ *   - `routine.research_cluster_update` — RESEARCH_CLUSTER_COST_FIX_PLAN.md F4
+ *     (Phase 2): the nightly per-cluster journal-append session.
+ *
+ * Adding a slim key is a one-line entry in `SLIM_SYSTEM_PROMPT_LOADERS` below
+ * (plus the asset file under agent-assets/system-prompts/ and, for CLI parity,
+ * the skill set in skills-compiler.ts:`SLIM_CLI_SKILL_SETS`).
+ *
+ * The same template is consumed by two backend paths so the body stays
+ * byte-identical across backends:
+ *   - Claude SDK — passed as `query()`'s `systemPrompt` string by
+ *     `claude-code-core.ts:buildSystemPrompt`.
+ *   - Codex / Gemini CLI — written verbatim as `AGENTS.md` / `GEMINI.md` by
+ *     `skills-compiler.ts:materializeSlimCliSession`.
+ *
+ * Hoisting the loaders out of `claude-code-core.ts` lets the skills compiler
+ * import them without a cross-backend dependency, and keeps the disk read +
+ * cache amortised across both code paths (one read per template per daemon
+ * boot regardless of how many sessions of either backend run).
+ *
+ * Each template is immutable for the daemon's lifetime, so a single
+ * per-template module-level cache is sufficient. The test reset helpers let
+ * unit tests simulate a fresh boot without reaching into module internals.
+ */
+import { type ProcessKey } from "@aitne/shared";
+/**
+ * Load the slim `routine.fetch_window` system-prompt template, caching the
+ * result for the daemon's lifetime.
+ */
+export declare function loadFetchWindowSystemPrompt(): string;
+/**
+ * Load the slim `routine.research_cluster_update` system-prompt template
+ * (RESEARCH_CLUSTER_COST_FIX_PLAN.md F4), caching for the daemon's lifetime.
+ */
+export declare function loadResearchClusterUpdateSystemPrompt(): string;
+/**
+ * Registry of process keys whose session uses a slim system prompt instead of
+ * the wide preset / profile. Typed as `Partial<Record<ProcessKey, …>>` (not an
+ * inferred string-literal map) so a rename in `@aitne/shared/process-key.ts`
+ * lights up here rather than silently dead-branching every consumer.
+ *
+ * Both call sites (Claude SDK `buildSystemPrompt`, CLI `materializeSlimCliSession`)
+ * resolve membership through `loadSlimSystemPrompt` / `isSlimSystemPromptKey`,
+ * so adding a key here is the single edit that wires both backends.
+ */
+export declare const SLIM_SYSTEM_PROMPT_LOADERS: Partial<Record<ProcessKey, () => string>>;
+/** True when `processKey` has a slim system-prompt template registered. */
+export declare function isSlimSystemPromptKey(processKey: ProcessKey | undefined): boolean;
+/**
+ * Load the slim system-prompt body for `processKey`, or `null` when the key
+ * has no slim template (callers fall through to the wide preset / profile).
+ * The disk read is amortised by the per-template cache.
+ */
+export declare function loadSlimSystemPrompt(processKey: ProcessKey | undefined): string | null;
+/**
+ * Test-only — drop every cached slim prompt so a subsequent load re-reads from
+ * disk. Production never needs this; the templates are immutable per boot.
+ */
+export declare function resetSlimSystemPromptsForTest(): void;
+/**
+ * Back-compat alias retained so the existing fetch_window tests / call sites
+ * keep working after the Phase 2 generalization. Resets every slim cache (a
+ * superset of the prior fetch_window-only reset — harmless for tests). Prefer
+ * `resetSlimSystemPromptsForTest` in new code.
+ */
+export declare function resetFetchWindowSystemPromptForTest(): void;

package/dist/core/slim-system-prompt-loader.js

@@ -0,0 +1,141 @@
+/**
+ * Single source of truth for the daemon's per-process **slim** system-prompt
+ * templates. A slim prompt replaces the verbose `preset: "claude_code"` system
+ * prompt (Claude SDK) / the wide profile + skill-index instruction file
+ * (Codex / Gemini CLI) with a tight, self-contained operational contract for
+ * one short, mechanical, lite-tier process key — shedding ~30 K tokens of
+ * built-in tool descriptions, the skills index, the memory-system docs, and
+ * tone/style guidance the key never uses.
+ *
+ * Two cost-reduction efforts share this registry:
+ *   - `routine.fetch_window` — docs/design/appendices/fetch-window-cost-reduction.md
+ *     Phase 1 / 1.5 (the original slim prompt).
+ *   - `routine.research_cluster_update` — RESEARCH_CLUSTER_COST_FIX_PLAN.md F4
+ *     (Phase 2): the nightly per-cluster journal-append session.
+ *
+ * Adding a slim key is a one-line entry in `SLIM_SYSTEM_PROMPT_LOADERS` below
+ * (plus the asset file under agent-assets/system-prompts/ and, for CLI parity,
+ * the skill set in skills-compiler.ts:`SLIM_CLI_SKILL_SETS`).
+ *
+ * The same template is consumed by two backend paths so the body stays
+ * byte-identical across backends:
+ *   - Claude SDK — passed as `query()`'s `systemPrompt` string by
+ *     `claude-code-core.ts:buildSystemPrompt`.
+ *   - Codex / Gemini CLI — written verbatim as `AGENTS.md` / `GEMINI.md` by
+ *     `skills-compiler.ts:materializeSlimCliSession`.
+ *
+ * Hoisting the loaders out of `claude-code-core.ts` lets the skills compiler
+ * import them without a cross-backend dependency, and keeps the disk read +
+ * cache amortised across both code paths (one read per template per daemon
+ * boot regardless of how many sessions of either backend run).
+ *
+ * Each template is immutable for the daemon's lifetime, so a single
+ * per-template module-level cache is sufficient. The test reset helpers let
+ * unit tests simulate a fresh boot without reaching into module internals.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { substituteBrandTokens } from "@aitne/shared";
+/**
+ * Resolve + read a slim-prompt asset by file basename (without the `.md`
+ * extension), applying brand-token substitution.
+ *
+ * Path resolution follows the same shape as `prompts.ts:resolveTaskFlowsDir`:
+ * `__dirname` lives at `packages/daemon/src/core/` (or the matching
+ * `dist/core/` after build), so the repo's `agent-assets/` directory is four
+ * levels up. The cwd fallback only fires in unusual harness layouts.
+ *
+ * Brand tokens (`{APP_NAME}`) are substituted here so the slim template stays
+ * aligned with the wide path's substitution contract: the Claude SDK
+ * systemPrompt and the CLI AGENTS.md / GEMINI.md both see the substituted
+ * product name instead of a literal `{APP_NAME}` leaking through. APP_NAME is
+ * a compile-time constant, so the per-boot cache stays byte-stable.
+ */
+function readSlimSystemPromptAsset(basename) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "..", "..", "..", "..", "agent-assets", "system-prompts", `${basename}.md`),
+        // Defensive fallback — if the module is invoked from an unexpected layout
+        // we still find the asset by walking up from cwd. Last-resort only; the
+        // relative path above is the canonical resolution.
+        join(process.cwd(), "agent-assets", "system-prompts", `${basename}.md`),
+    ];
+    for (const path of candidates) {
+        if (existsSync(path)) {
+            return substituteBrandTokens(readFileSync(path, "utf-8"));
+        }
+    }
+    throw new Error(`slim system prompt "${basename}" not found. Looked in: ${candidates.join(", ")}`);
+}
+// Per-template module-level caches. Each template is byte-stable per boot, so
+// a single cached string is sufficient; the reset helper drops them for tests.
+let cachedFetchWindowSystemPrompt = null;
+let cachedResearchClusterUpdateSystemPrompt = null;
+/**
+ * Load the slim `routine.fetch_window` system-prompt template, caching the
+ * result for the daemon's lifetime.
+ */
+export function loadFetchWindowSystemPrompt() {
+    if (cachedFetchWindowSystemPrompt !== null)
+        return cachedFetchWindowSystemPrompt;
+    cachedFetchWindowSystemPrompt = readSlimSystemPromptAsset("routine-fetch-window");
+    return cachedFetchWindowSystemPrompt;
+}
+/**
+ * Load the slim `routine.research_cluster_update` system-prompt template
+ * (RESEARCH_CLUSTER_COST_FIX_PLAN.md F4), caching for the daemon's lifetime.
+ */
+export function loadResearchClusterUpdateSystemPrompt() {
+    if (cachedResearchClusterUpdateSystemPrompt !== null) {
+        return cachedResearchClusterUpdateSystemPrompt;
+    }
+    cachedResearchClusterUpdateSystemPrompt = readSlimSystemPromptAsset("routine-research-cluster-update");
+    return cachedResearchClusterUpdateSystemPrompt;
+}
+/**
+ * Registry of process keys whose session uses a slim system prompt instead of
+ * the wide preset / profile. Typed as `Partial<Record<ProcessKey, …>>` (not an
+ * inferred string-literal map) so a rename in `@aitne/shared/process-key.ts`
+ * lights up here rather than silently dead-branching every consumer.
+ *
+ * Both call sites (Claude SDK `buildSystemPrompt`, CLI `materializeSlimCliSession`)
+ * resolve membership through `loadSlimSystemPrompt` / `isSlimSystemPromptKey`,
+ * so adding a key here is the single edit that wires both backends.
+ */
+export const SLIM_SYSTEM_PROMPT_LOADERS = {
+    "routine.fetch_window": loadFetchWindowSystemPrompt,
+    "routine.research_cluster_update": loadResearchClusterUpdateSystemPrompt,
+};
+/** True when `processKey` has a slim system-prompt template registered. */
+export function isSlimSystemPromptKey(processKey) {
+    return processKey !== undefined && processKey in SLIM_SYSTEM_PROMPT_LOADERS;
+}
+/**
+ * Load the slim system-prompt body for `processKey`, or `null` when the key
+ * has no slim template (callers fall through to the wide preset / profile).
+ * The disk read is amortised by the per-template cache.
+ */
+export function loadSlimSystemPrompt(processKey) {
+    if (processKey === undefined)
+        return null;
+    const loader = SLIM_SYSTEM_PROMPT_LOADERS[processKey];
+    return loader ? loader() : null;
+}
+/**
+ * Test-only — drop every cached slim prompt so a subsequent load re-reads from
+ * disk. Production never needs this; the templates are immutable per boot.
+ */
+export function resetSlimSystemPromptsForTest() {
+    cachedFetchWindowSystemPrompt = null;
+    cachedResearchClusterUpdateSystemPrompt = null;
+}
+/**
+ * Back-compat alias retained so the existing fetch_window tests / call sites
+ * keep working after the Phase 2 generalization. Resets every slim cache (a
+ * superset of the prior fetch_window-only reset — harmless for tests). Prefer
+ * `resetSlimSystemPromptsForTest` in new code.
+ */
+export function resetFetchWindowSystemPromptForTest() {
+    resetSlimSystemPromptsForTest();
+}

package/dist/core/spawn-gates.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Pre-spawn gates for autonomous routine sessions —
+ * PREPASS_COST_REDUCTION_PLAN.md N2.
+ *
+ * Two cheap checks run before the daemon spawns an autonomous backend
+ * session (routine dispatch + pre-pass fan-out sub-sessions), so a
+ * session that would deterministically fail is skipped instead of
+ * billed/spawned:
+ *
+ *  1. **Offline gate** — DNS-resolve the *backend API host* (the daemon
+ *     never talks to integration APIs in delegated/native mode, so the
+ *     backend host is the only one that matters). Uses `dns.lookup`
+ *     (getaddrinfo — the same resolver path that produces the observed
+ *     ENOTFOUND failures), NOT `dns.resolve` (c-ares bypasses the OS
+ *     resolver / hosts file and can disagree with what the session would
+ *     see). Results are cached ~60s per host so a fan-out of N
+ *     integrations costs one lookup.
+ *  2. **Auth gate** — consult the cached auth-health row
+ *     (`readCachedAuthStatus`) and treat the backend as non-viable only
+ *     when `shouldSkip` is true (expired/missing with a ≤10-min-fresh
+ *     cache, or a recovery subprocess owning the row). The hourly
+ *     `checkAll()` probe and the reactive `recordReactiveAuth*` writers
+ *     refresh the cache independently of routine sessions, so a
+ *     recovered backend un-skips within minutes.
+ *
+ * **A spawn is skipped only when EVERY candidate backend (main +
+ * fallback) is non-viable.** The BackendRouter already skips an
+ * auth-unhealthy main straight to its fallback, so gating on the main
+ * alone would suppress sessions the router could have completed —
+ * exactly the accuracy degradation the now-scope forbids.
+ *
+ * Skips never touch pre-pass freshness state, so the next tick retries.
+ * Every decision is fail-open: an unknown backend host, a gate-internal
+ * error, or a DB failure lets the spawn proceed — the gate exists to
+ * save doomed sessions, never to block live ones.
+ */
+import type Database from "better-sqlite3";
+import type { BackendId } from "@aitne/shared";
+/**
+ * Backend → API host the SDK/CLI must reach for a session to be viable.
+ * Hosts chosen per the default auth path of each backend's runtime:
+ * Claude Code → Anthropic API; Codex CLI (ChatGPT-plan auth) →
+ * chatgpt.com; Gemini CLI (OAuth code-assist) → cloudcode-pa. The gate
+ * only needs a DNS answer for outage detection, so an API-key install
+ * resolving a sibling host of the same provider is equally conclusive.
+ * Backends without an entry (e.g. opencode, which routes to arbitrary
+ * providers) are fail-open: the offline gate passes them.
+ */
+export declare const BACKEND_API_HOSTS: Partial<Record<BackendId, string>>;
+export type SpawnGateSkipReason = "offline" | "auth_unhealthy";
+/** Per-candidate diagnostics carried into the skip audit row. */
+export interface SpawnGateBackendVerdict {
+    backendId: BackendId;
+    /** Host probed by the offline gate; null = no mapping (gate passed). */
+    host: string | null;
+    /** True when the host failed to resolve (within the cache TTL). */
+    offline: boolean;
+    /** Cached auth status string (`ok` / `expired` / `missing` / …). */
+    authStatus: string;
+    /** True when the cached auth row says a spawn is doomed. */
+    authShouldSkip: boolean;
+    /** Net verdict: this backend could run the session. */
+    viable: boolean;
+}
+export interface SpawnGateDecision {
+    skip: boolean;
+    /**
+     * Present iff `skip`. `offline` when every candidate was blocked by
+     * DNS; `auth_unhealthy` when at least one candidate resolved but had
+     * a confirmed-bad auth cache.
+     */
+    reason?: SpawnGateSkipReason;
+    backends: SpawnGateBackendVerdict[];
+}
+export interface AutonomousSpawnGateOptions {
+    /** Injected for tests; defaults to `node:dns/promises.lookup`. */
+    lookup?: (host: string) => Promise<unknown>;
+    /** Injected clock for tests; defaults to `Date.now`. */
+    now?: () => number;
+    /** DNS verdict cache TTL; defaults to 60s. */
+    dnsCacheTtlMs?: number;
+    /** Per-lookup deadline (fail-open past it); defaults to 2.5s. */
+    dnsLookupTimeoutMs?: number;
+    /**
+     * Freshness window forwarded to `readCachedAuthStatus`. Omit to use
+     * that module's 10-minute default; callers with a configured
+     * `authPreflightFreshnessMs` should thread it through so the gate and
+     * the router agree on what "recently confirmed bad" means.
+     */
+    authFreshnessMs?: number;
+    /** Host mapping override for tests. */
+    backendApiHosts?: Partial<Record<BackendId, string>>;
+}
+export declare class AutonomousSpawnGate {
+    private readonly db;
+    private readonly lookup;
+    private readonly now;
+    private readonly dnsCacheTtlMs;
+    private readonly dnsLookupTimeoutMs;
+    private readonly authFreshnessMs;
+    private readonly hosts;
+    private readonly dnsCache;
+    constructor(db: Database.Database, options?: AutonomousSpawnGateOptions);
+    /**
+     * Evaluate the gates for the candidate backends that could run the
+     * session (binding main first, then fallback). Returns `skip: false`
+     * for an empty candidate list (nothing to assert) and on any internal
+     * error (fail-open).
+     */
+    evaluate(candidates: readonly BackendId[]): Promise<SpawnGateDecision>;
+    private evaluateBackend;
+    private hostResolves;
+    /**
+     * One bounded lookup attempt. Three fail-OPEN (`true`) outcomes that
+     * deliberately do not count as "offline":
+     *  - the resolver answered (any address);
+     *  - `EAI_AGAIN` — the resolver said "try again", which is a transient
+     *    resolver condition, not an outage verdict;
+     *  - the deadline elapsed — no answer is not a negative answer.
+     * Only a definitive resolution failure (ENOTFOUND et al.) returns
+     * `false`. The verdict — including a fail-open one — is cached by the
+     * caller for the TTL so a hung resolver costs at most one deadline
+     * per host per minute.
+     */
+    private lookupWithDeadline;
+}