@aitne/daemon 0.1.9 → 0.1.11

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

package/dist/core/spawn-gates.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { lookup as dnsLookup } from "node:dns/promises";
+import { readCachedAuthStatus } from "./backends/auth-health-monitor.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("spawn-gates");
+/**
+ * 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 const BACKEND_API_HOSTS = {
+    claude: "api.anthropic.com",
+    codex: "chatgpt.com",
+    gemini: "cloudcode-pa.googleapis.com",
+};
+/** Default TTL for cached per-host DNS verdicts (~60s per the N2 spec). */
+const DEFAULT_DNS_CACHE_TTL_MS = 60 * 1000;
+/**
+ * Deadline for a single `dns.lookup` call. getaddrinfo has no timeout
+ * of its own — a degraded resolver can block for the OS resolver
+ * timeout (5-30s), serially per candidate host, stalling the
+ * autonomous lane and every fan-out sub-session start. Past the
+ * deadline the gate fails OPEN (treats the host as resolvable): an
+ * answer we don't have is not an outage signal.
+ */
+const DEFAULT_DNS_LOOKUP_TIMEOUT_MS = 2_500;
+export class AutonomousSpawnGate {
+    db;
+    lookup;
+    now;
+    dnsCacheTtlMs;
+    dnsLookupTimeoutMs;
+    authFreshnessMs;
+    hosts;
+    dnsCache = new Map();
+    constructor(db, options = {}) {
+        this.db = db;
+        // `dnsLookup` is referenced directly (no wrapper arrow) so the
+        // default arm carries no never-invoked closure — tests cover the
+        // `??` branch by constructing without options, without doing real
+        // DNS.
+        this.lookup = options.lookup ?? dnsLookup;
+        this.now = options.now ?? (() => Date.now());
+        this.dnsCacheTtlMs = options.dnsCacheTtlMs ?? DEFAULT_DNS_CACHE_TTL_MS;
+        this.dnsLookupTimeoutMs =
+            options.dnsLookupTimeoutMs ?? DEFAULT_DNS_LOOKUP_TIMEOUT_MS;
+        this.authFreshnessMs = options.authFreshnessMs;
+        this.hosts = options.backendApiHosts ?? BACKEND_API_HOSTS;
+    }
+    /**
+     * 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).
+     */
+    async evaluate(candidates) {
+        try {
+            if (candidates.length === 0) {
+                return { skip: false, backends: [] };
+            }
+            const backends = [];
+            for (const backendId of candidates) {
+                backends.push(await this.evaluateBackend(backendId));
+            }
+            if (backends.some((b) => b.viable)) {
+                return { skip: false, backends };
+            }
+            const reason = backends.every((b) => b.offline)
+                ? "offline"
+                : "auth_unhealthy";
+            return { skip: true, reason, backends };
+        }
+        catch (err) {
+            logger.warn({ err, candidates }, "Spawn-gate evaluation failed — failing open");
+            return { skip: false, backends: [] };
+        }
+    }
+    async evaluateBackend(backendId) {
+        const host = this.hosts[backendId] ?? null;
+        const offline = host === null ? false : !(await this.hostResolves(host));
+        // readCachedAuthStatus is fail-open by contract (returns
+        // `{status:"unknown", shouldSkip:false}` on any DB error), and
+        // `evaluate()`'s outer catch fails the whole gate open as the last
+        // line of defense — no per-call try/catch needed here.
+        const cached = this.authFreshnessMs === undefined
+            ? readCachedAuthStatus(this.db, backendId)
+            : readCachedAuthStatus(this.db, backendId, this.authFreshnessMs);
+        return {
+            backendId,
+            host,
+            offline,
+            authStatus: cached.status,
+            authShouldSkip: cached.shouldSkip,
+            viable: !offline && !cached.shouldSkip,
+        };
+    }
+    async hostResolves(host) {
+        const nowMs = this.now();
+        const cached = this.dnsCache.get(host);
+        if (cached && cached.expiresAtMs > nowMs) {
+            return cached.ok;
+        }
+        const ok = await this.lookupWithDeadline(host);
+        this.dnsCache.set(host, {
+            ok,
+            expiresAtMs: this.now() + this.dnsCacheTtlMs,
+        });
+        return ok;
+    }
+    /**
+     * 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.
+     */
+    async lookupWithDeadline(host) {
+        let timer;
+        const attempt = this.lookup(host).then(() => true, (err) => {
+            const code = typeof err === "object" && err !== null && "code" in err
+                ? err.code
+                : undefined;
+            return code === "EAI_AGAIN";
+        });
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(true), this.dnsLookupTimeoutMs);
+        });
+        try {
+            return await Promise.race([attempt, deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/core/today-direct-writer.d.ts

@@ -1,9 +1,15 @@
 /**
- * Daemon-direct writer that appends a single bullet to today.md
- * `## Agent Log` without going through the agent at all. Used by the
- * three-stage hourly_check gate (cost-reduction-structural §B) on the
- * stage0_silent / stage2_log_only paths so a "no-op" cron tick still
- * leaves an audit trail in today.md without paying for an LLM session.
+ * Daemon-direct, lock-aware writes to today.md that run *before* (or
+ * instead of) an agent session — bypassing `/api/context/*` because there
+ * is no subprocess to issue the curl call from. Two operations live here:
+ *
+ *   1. {@link appendAgentLogLine} — append a single `## Agent Log` bullet.
+ *      Used by the three-stage activity_scan gate (cost-reduction-structural
+ *      §B) on the stage0_silent / stage2_log_only paths so a "no-op" cron
+ *      tick still leaves an audit trail without paying for an LLM session.
+ *   2. {@link ensureTodaySkeleton} — seed the canonical empty skeleton when
+ *      today.md is **absent**, so a section-only refresh routine has a valid
+ *      PATCH target instead of 404-ing and budget-burning on full-file PUTs.
  *
  * Why this lives in the daemon (not /api/context/* via curl):
  *   - These paths run *before* the agent is spawned. There is no
@@ -12,15 +18,16 @@
  *     `context-staleness.ts`) — the same tier the PATCH route already
  *     classifies for `## Agent Log` appends. Bypassing the route is
  *     fine because we never touch the prompt-context-changed hook here.
- *   - The today-write-lock invariant is preserved: we acquire it before
- *     mutating the file, so morning_routine and direct writes never
- *     interleave.
+ *   - The today-write-lock invariant is preserved: both functions acquire
+ *     it before mutating the file, so morning_routine and direct writes
+ *     never interleave.
  *
- * Failure mode: when today.md is missing, malformed, or lacks the
- * `## Agent Log` heading, the writer logs a warning and returns false
- * rather than synthesizing the structure — that is the morning routine's
- * job. The gate caller treats false as "log not appended; consume
- * observations regardless".
+ * Synthesis boundary: `appendAgentLogLine` NEVER synthesizes structure —
+ * a missing / malformed / heading-less file returns false and the gate
+ * caller proceeds. `ensureTodaySkeleton` synthesizes ONLY the empty
+ * skeleton, ONLY when the file is entirely absent, and never touches a
+ * present file. Neither populates today.md — full creation and repair stay
+ * the morning routine's job.
  */
 import type { TodayWriteLockManager } from "./today-write-lock.js";
 export interface AppendAgentLogLineInput {
@@ -28,7 +35,7 @@ export interface AppendAgentLogLineInput {
     /**
      * Bullet text to append, **without** the leading `- ` prefix and
      * without a trailing newline. The writer normalizes both.
-     * Example: `"12:00 [hourly_check] Quiet — 0 obs"`.
+     * Example: `"12:00 [activity_scan] Quiet — 0 obs"`.
      */
     message: string;
     todayWriteLock: TodayWriteLockManager;
@@ -61,6 +68,45 @@ export interface AppendAgentLogLineResult {
  * writers cleanly.
  */
 export declare function appendAgentLogLine(input: AppendAgentLogLineInput): Promise<AppendAgentLogLineResult>;
+export interface EnsureTodaySkeletonInput {
+    contextDir: string;
+    todayWriteLock: TodayWriteLockManager;
+}
+export interface EnsureTodaySkeletonResult {
+    seeded: boolean;
+    reason?: "already_present" | "lock_unavailable" | "io_error";
+}
+/**
+ * Guarantee a `today.md` working surface exists before a section-only
+ * refresh routine (`routine.today_refresh`) assumes it.
+ *
+ * `rotateDayFiles()` intentionally renames `today.md` → `yesterday.md` at
+ * the day boundary and relies on the morning routine to recreate the
+ * dated file. When the morning routine has not run yet — or failed (e.g.
+ * a quota/budget death with no fallback backend) — `today.md` is absent
+ * and the refresh task flow's `PATCH section=user_schedule` 404s. The
+ * agent then improvises full-file `PUT`s, which the strict
+ * `validateTodayContent` schema rejects line-by-line; on a single-backend
+ * binding with a tight per-turn budget that loop tips into
+ * `BackendQuotaError(max_budget_usd)` and the refresh dies without ever
+ * writing the file — the "Refresh Today does nothing" symptom.
+ *
+ * This deterministic pre-step removes that whole failure mode: when the
+ * file is **entirely absent** we seed the canonical empty skeleton so the
+ * agent's section PATCH always has a valid target. A file that already
+ * exists is left byte-untouched — a valid dated file OR the legacy
+ * `# Today` bridge stub both accept the section PATCH (the route's
+ * `allowLegacyToday` branch). We never repair a malformed-but-present
+ * file and never overwrite user content; full creation/repair stays the
+ * morning routine's job. The seeded skeleton is dateless (`# Today`), so
+ * it does NOT satisfy `hasCurrentAgentDayTodayMd()` and the pending
+ * morning-routine retry still fires and upgrades it.
+ *
+ * Lock-aware exactly like {@link appendAgentLogLine}: if the morning
+ * routine holds the today-write-lock (mid-creation) we skip and let it
+ * win — the refresh session then 409-defers on its own PATCH.
+ */
+export declare function ensureTodaySkeleton(input: EnsureTodaySkeletonInput): Promise<EnsureTodaySkeletonResult>;
 /**
  * Splice a new bullet line into the `## Agent Log` section, immediately
  * before the next `## ` heading or end-of-file. Returns null when the