@aitne/daemon 0.1.10 → 0.1.11

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

@@ -4,7 +4,7 @@
  * 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 hourly_check gate (cost-reduction-structural
+ *      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
@@ -35,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;

package/dist/core/today-direct-writer.js

@@ -4,7 +4,7 @@
  * 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 hourly_check gate (cost-reduction-structural
+ *      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

package/dist/core/today-write-lock.d.ts

@@ -13,8 +13,9 @@ export interface TodayWriteLockManager {
 export declare class InMemoryTodayWriteLockManager implements TodayWriteLockManager {
     private readonly timeoutMs;
     private holder;
-    private timer;
+    private expiresAtMs;
     constructor(timeoutMs: number);
+    private expireIfStale;
     acquire(): {
         ok: true;
         lockId: string;
@@ -38,8 +39,9 @@ export declare function getTodayWriteLockTimeoutMs(executeTimeoutMinutes: number
 export declare class MigrationLock {
     private readonly timeoutMs;
     private holder;
-    private timer;
+    private expiresAtMs;
     constructor(timeoutMs: number);
+    private expireIfStale;
     acquire(): {
         ok: true;
         lockId: string;

package/dist/core/today-write-lock.js

@@ -4,44 +4,50 @@ const logger = createLogger("today-write-lock");
 export class InMemoryTodayWriteLockManager {
     timeoutMs;
     holder = null;
-    timer = null;
+    expiresAtMs = 0;
     constructor(timeoutMs) {
         this.timeoutMs = timeoutMs;
     }
+    // Expiry is wall-clock (Date.now) checked lazily on access, not a
+    // setTimeout: Node timers run on the monotonic clock and don't advance
+    // while the machine sleeps, so a timer armed before sleep would hold the
+    // lock up to the whole sleep duration past its intended TTL.
+    expireIfStale() {
+        if (this.holder && Date.now() >= this.expiresAtMs) {
+            logger.warn({ lockId: this.holder }, "Today write lock expired by timeout");
+            this.holder = null;
+        }
+    }
     acquire() {
+        this.expireIfStale();
         if (this.holder) {
             logger.debug({ existingHolder: this.holder }, "Lock acquire rejected — already held");
             return { ok: false, holder: this.holder };
         }
         const lockId = randomUUID();
         this.holder = lockId;
-        this.timer = setTimeout(() => {
-            logger.warn({ lockId: this.holder }, "Today write lock expired by timeout");
-            this.holder = null;
-            this.timer = null;
-        }, this.timeoutMs);
+        this.expiresAtMs = Date.now() + this.timeoutMs;
         logger.debug({ lockId }, "Today write lock acquired");
         return { ok: true, lockId };
     }
     release(lockId) {
+        this.expireIfStale();
         if (!this.holder || this.holder !== lockId) {
             return false;
         }
         this.holder = null;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
         logger.debug({ lockId }, "Today write lock released");
         return true;
     }
     isHeldBy(lockId) {
+        this.expireIfStale();
         if (!this.holder) {
             return false;
         }
         return this.holder === lockId;
     }
     getHolder() {
+        this.expireIfStale();
         return this.holder;
     }
 }
@@ -62,41 +68,45 @@ export function getTodayWriteLockTimeoutMs(executeTimeoutMinutes) {
 export class MigrationLock {
     timeoutMs;
     holder = null;
-    timer = null;
+    expiresAtMs = 0;
     constructor(timeoutMs) {
         this.timeoutMs = timeoutMs;
     }
+    // Wall-clock lazy expiry — see InMemoryTodayWriteLockManager for why
+    // this is not a setTimeout.
+    expireIfStale() {
+        if (this.holder && Date.now() >= this.expiresAtMs) {
+            logger.warn({ lockId: this.holder }, "Migration lock expired by timeout");
+            this.holder = null;
+        }
+    }
     acquire() {
+        this.expireIfStale();
         if (this.holder) {
             logger.debug({ existingHolder: this.holder }, "Migration lock rejected — already held");
             return { ok: false, holder: this.holder };
         }
         const lockId = randomUUID();
         this.holder = lockId;
-        this.timer = setTimeout(() => {
-            logger.warn({ lockId: this.holder }, "Migration lock expired by timeout");
-            this.holder = null;
-            this.timer = null;
-        }, this.timeoutMs);
+        this.expiresAtMs = Date.now() + this.timeoutMs;
         logger.debug({ lockId }, "Migration lock acquired");
         return { ok: true, lockId };
     }
     release(lockId) {
+        this.expireIfStale();
         if (!this.holder || this.holder !== lockId) {
             return false;
         }
         this.holder = null;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
         logger.debug({ lockId }, "Migration lock released");
         return true;
     }
     isHeld() {
+        this.expireIfStale();
         return this.holder !== null;
     }
     getHolder() {
+        this.expireIfStale();
         return this.holder;
     }
 }

package/dist/core/wake-detector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Default tick cadence. One minute keeps detection latency low while the
+ * per-tick work (one Date.now() subtraction) is negligible.
+ */
+export declare const WAKE_DETECTOR_INTERVAL_MS = 60000;
+/**
+ * Minimum unexplained gap between ticks that counts as a sleep / suspend /
+ * forward clock jump. Five minutes is far above any plausible event-loop
+ * stall on a healthy daemon, and far below the shortest sleep that can
+ * swallow a cron tick worth catching up (the activity scan's default
+ * 60-minute cadence).
+ */
+export declare const WAKE_GAP_THRESHOLD_MS: number;
+export interface WakeDetectorOptions {
+    /**
+     * Invoked once per detected wake with the gap length. Errors (sync or
+     * async) are caught and logged — the detector keeps ticking.
+     */
+    onWake: (gapMs: number) => void | Promise<void>;
+    intervalMs?: number;
+    gapThresholdMs?: number;
+    /** Injectable wall clock for tests. */
+    now?: () => number;
+}
+/**
+ * Detects machine sleep / suspend / forward clock jumps from inside the
+ * process.
+ *
+ * node-cron (and every other timer in the daemon) runs on Node's timer
+ * wheel, which does not fire while the host is suspended — a cron tick
+ * scheduled inside a sleep window is silently lost, not replayed on wake.
+ * The boot-time catchup in `bootstrap/catchup.ts` covers daemon *restarts*,
+ * but a long sleep with the process still alive had no equivalent until
+ * this detector.
+ *
+ * Mechanism: a short `setInterval` notes the wall-clock time of each tick.
+ * Timers freeze during sleep, so the first tick after wake observes a
+ * wall-clock gap of roughly the sleep duration; anything above
+ * `gapThresholdMs` beyond the expected interval fires `onWake`. Backward
+ * clock jumps are ignored — there is nothing to catch up when time moves
+ * backward, and the next tick re-baselines automatically.
+ */
+export declare class WakeDetector {
+    private readonly onWake;
+    private readonly intervalMs;
+    private readonly gapThresholdMs;
+    private readonly now;
+    private timer;
+    private lastTickMs;
+    constructor(options: WakeDetectorOptions);
+    start(): void;
+    stop(): void;
+    /** Test seam — exercises one tick without waiting on real timers. */
+    tick(): void;
+}

package/dist/core/wake-detector.js

@@ -0,0 +1,80 @@
+import { createLogger } from "../logging.js";
+const logger = createLogger("wake-detector");
+/**
+ * Default tick cadence. One minute keeps detection latency low while the
+ * per-tick work (one Date.now() subtraction) is negligible.
+ */
+export const WAKE_DETECTOR_INTERVAL_MS = 60_000;
+/**
+ * Minimum unexplained gap between ticks that counts as a sleep / suspend /
+ * forward clock jump. Five minutes is far above any plausible event-loop
+ * stall on a healthy daemon, and far below the shortest sleep that can
+ * swallow a cron tick worth catching up (the activity scan's default
+ * 60-minute cadence).
+ */
+export const WAKE_GAP_THRESHOLD_MS = 5 * 60_000;
+/**
+ * Detects machine sleep / suspend / forward clock jumps from inside the
+ * process.
+ *
+ * node-cron (and every other timer in the daemon) runs on Node's timer
+ * wheel, which does not fire while the host is suspended — a cron tick
+ * scheduled inside a sleep window is silently lost, not replayed on wake.
+ * The boot-time catchup in `bootstrap/catchup.ts` covers daemon *restarts*,
+ * but a long sleep with the process still alive had no equivalent until
+ * this detector.
+ *
+ * Mechanism: a short `setInterval` notes the wall-clock time of each tick.
+ * Timers freeze during sleep, so the first tick after wake observes a
+ * wall-clock gap of roughly the sleep duration; anything above
+ * `gapThresholdMs` beyond the expected interval fires `onWake`. Backward
+ * clock jumps are ignored — there is nothing to catch up when time moves
+ * backward, and the next tick re-baselines automatically.
+ */
+export class WakeDetector {
+    onWake;
+    intervalMs;
+    gapThresholdMs;
+    now;
+    timer = null;
+    lastTickMs = 0;
+    constructor(options) {
+        this.onWake = options.onWake;
+        this.intervalMs = options.intervalMs ?? WAKE_DETECTOR_INTERVAL_MS;
+        this.gapThresholdMs = options.gapThresholdMs ?? WAKE_GAP_THRESHOLD_MS;
+        this.now = options.now ?? Date.now;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.lastTickMs = this.now();
+        this.timer = setInterval(() => this.tick(), this.intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** Test seam — exercises one tick without waiting on real timers. */
+    tick() {
+        const current = this.now();
+        const gapMs = current - this.lastTickMs - this.intervalMs;
+        this.lastTickMs = current;
+        if (gapMs < this.gapThresholdMs)
+            return;
+        logger.warn({ gapMinutes: Math.round(gapMs / 60_000) }, "Wall-clock gap detected (machine sleep or clock jump) — running wake catch-up");
+        try {
+            const result = this.onWake(gapMs);
+            if (result && typeof result.then === "function") {
+                result.then(undefined, (err) => {
+                    logger.error({ err }, "Wake catch-up handler failed");
+                });
+            }
+        }
+        catch (err) {
+            logger.error({ err }, "Wake catch-up handler threw");
+        }
+    }
+}

package/dist/core/wiki/compile-lock.d.ts

@@ -12,7 +12,7 @@
  *     time. The lock is held until the dispatcher releases it via
  *     `releaseWikiCompileLock` in `executeDefault`'s `finally` block.
  *   - The lock is purely in-process; that matches the dispatcher's
- *     existing concurrency invariants (`hourlyCheckInProgress`,
+ *     existing concurrency invariants (`activityScanInProgress`,
  *     `morningRoutineActive` are also in-memory flags). A second
  *     daemon process would not see the lock — but the daemon is
  *     single-process by design.

package/dist/core/wiki/compile-lock.js

@@ -12,7 +12,7 @@
  *     time. The lock is held until the dispatcher releases it via
  *     `releaseWikiCompileLock` in `executeDefault`'s `finally` block.
  *   - The lock is purely in-process; that matches the dispatcher's
- *     existing concurrency invariants (`hourlyCheckInProgress`,
+ *     existing concurrency invariants (`activityScanInProgress`,
  *     `morningRoutineActive` are also in-memory flags). A second
  *     daemon process would not see the lock — but the daemon is
  *     single-process by design.

package/dist/core/workdir.js

@@ -25,7 +25,7 @@ import { createLogger } from "../logging.js";
 import { SkillsCompiler } from "./skills-compiler.js";
 import { EMPTY_MAIL_ACCOUNTS_MD, renderMailAccountsMd, } from "./skills-compiler-tree.js";
 import { refreshSkillIndexBlock } from "./skills-compiler-skill-index.js";
-import { getProfileForEvent, resolveSkillManifest, resolveSkillManifestForProcess, } from "./skills-manifest.js";
+import { eventTypeAcceptsUserSkills, getProfileForEvent, resolveSkillManifest, resolveSkillManifestForProcess, } from "./skills-manifest.js";
 import { ensureDaemonApiCli } from "./daemon-api-cli.js";
 import { computeInstructionAssetStatus, readInstructionStampManifest, sessionInstructionAssetsStale, writeInstructionAssetStamp, } from "./release-assets.js";
 const logger = createLogger("workdir");
@@ -252,11 +252,15 @@ export function createSessionWorkdir(projectRoot, eventType, userSkillsDir, opti
         // turns, manifest now resolves to a different skill set).
         { processKey: options?.processKey ?? eventType, skillSlugs: deployed.skills });
         ensureDaemonApiCli(sessionDir);
-        // User skills: every skill the user has authored, regardless of event type.
-        // Uses the manifest-backed sync so the initial population is consistent
-        // with the per-message sync the dispatcher runs on Opus events.
+        // User skills: every skill the user has authored, EXCEPT for
+        // narrow-persona keys (wiki.* / routine.research_*) which run a tight
+        // built-in manifest and would only be diluted by the owner's general
+        // skill library — see `eventTypeAcceptsUserSkills`. Uses the
+        // manifest-backed sync so the initial population is consistent with the
+        // per-message sync the dispatcher runs on Opus events.
         let userSync = null;
-        if (userSkillsDir) {
+        if (userSkillsDir &&
+            eventTypeAcceptsUserSkills(options?.processKey ?? eventType)) {
             userSync = syncAllUserSkills(sessionDir, userSkillsDir);
             // docs/design/appendices/skills-unification.md Phase 1 §R4 — splice user-authored
             // slugs into the `<skill-index>` block AFTER they land on disk.
@@ -419,7 +423,12 @@ export function ensureSessionWorkdir(projectRoot, dataDir, dbSessionId, eventTyp
         // CONTEXT_VAULT_REDESIGN — falling back there would resurrect the
         // Obsidian-mode divergence bug v4 V11 fixed.
         const userSkillsDir = join(options?.contextDir ?? join(dataDir, "context"), "policies", "skills");
-        const userSync = syncAllUserSkills(sessionDir, userSkillsDir);
+        // Narrow-persona keys (wiki.* / routine.research_*) skip the owner's
+        // user-skill library; their tight built-in manifest is the whole
+        // surface. See `eventTypeAcceptsUserSkills`.
+        const userSync = eventTypeAcceptsUserSkills(options?.processKey ?? eventType)
+            ? syncAllUserSkills(sessionDir, userSkillsDir)
+            : null;
         // docs/design/appendices/skills-unification.md Phase 1 §R4 — fold user-authored slugs
         // into the `<skill-index>` block now that they're on disk. Idempotent
         // and inexpensive (single instruction-file rewrite).

package/dist/db/activity-scan-signals.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Stage-0 signal compute for the three-stage activity_scan gate
+ * (cost-reduction-structural §B). Pure DB-read shape: every value is
+ * derived from existing tables (`observations`, `mail_messages_index`,
+ * `agent_schedule`, `agent_actions`) plus the optional today.md content
+ * passed in by the caller. No LLM call, no filesystem I/O of its own —
+ * the dispatcher injects the today.md snapshot (when available) so this
+ * module stays unit-testable from a synthetic Database handle.
+ *
+ * The shape mirrors the design doc 1:1 so the gate (Stage 1) can be
+ * a pure function over `ActivityScanSignals` + a config block.
+ */
+import type Database from "better-sqlite3";
+export interface ActivityScanSignals {
+    /** Post dedup-against-today user-actor pending observation count. */
+    pendingObsCount: number;
+    /**
+     * Maximum `novelty_score` across pending user observations whose
+     * `summary_status='done'`. `null` when no observation has a done
+     * summary yet — the gate treats null as a cautious mid-novelty default
+     * (see decideStage).
+     */
+    maxNoveltyScore: number | null;
+    /** Histogram of novelty levels across pending+done observations. */
+    noveltyDistribution: {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    /** Count of unread mail rows whose sender is in the VIP list. */
+    vipMailUnreadCount: number;
+    /** True when at least one pending calendar observation exists. */
+    calendarHas24hChange: boolean;
+    /**
+     * True when at least two pending calendar observations carry
+     * overlapping `start`/`end` ISO timestamps in their JSON payload
+     * within the next 24 hours. Tolerant of missing fields — when the
+     * payload shape isn't recognizable, returns false (the LLM still
+     * sees the underlying observation in Stage 3 if escalated).
+     */
+    calendarHasConflict: boolean;
+    /**
+     * Number of `## Agent Plan` rows in today.md whose HH:MM is before
+     * `now` in the agent timezone. Best-effort regex parse — when
+     * today.md is missing or unparseable, returns 0.
+     */
+    agentPlanOverdueCount: number;
+    /** Count of `agent_schedule` rows due in the next 6 hours. */
+    scheduleApproachingCount: number;
+    /**
+     * Hours since the last activity_scan that escalated to Stage 3 (or
+     * before the gate was deployed, since the last activity_scan run at
+     * all). `Infinity` when no row has been recorded yet.
+     */
+    hoursSinceLastStage3Run: number;
+}
+export interface ComputeActivityScanSignalsOptions {
+    /** Owner-VIP mail addresses, lowercased exact-match. */
+    vipMailSenders?: readonly string[];
+    /** Look-ahead window for `scheduleApproachingCount`. Default 6h. */
+    scheduleHorizonHours?: number;
+    /** Look-ahead window for calendar conflict detection. Default 24h. */
+    calendarHorizonHours?: number;
+    /** today.md content snapshot (or null when missing/unreadable). */
+    todayMd?: string | null;
+    /** Wall-clock anchor — injectable for tests. Defaults to `new Date()`. */
+    now?: Date;
+    /**
+     * Agent timezone (IANA name, e.g. `Asia/Tokyo`) used to compare
+     * `## Agent Plan` HH:MM rows against `now`. When omitted, falls back
+     * to the JS engine's local timezone — fine in the common single-user
+     * deployment but wrong if the daemon runs in UTC and the operator
+     * pinned a different `config.timezone`.
+     */
+    agentTimezone?: string;
+}
+export declare function computeActivityScanSignals(db: Database.Database, options?: ComputeActivityScanSignalsOptions): ActivityScanSignals;