@aitne/daemon 0.1.9 → 0.1.11

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

@@ -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,20 +18,22 @@
  *     `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 { existsSync, readFileSync } from "node:fs";
 import { writeFileAtomically } from "./atomic-write.js";
 import { serializeContextFileWrite } from "./context-file-serializer.js";
 import { fullPath, CONTEXT_RELATIVE_PATHS } from "./context-paths.js";
+import { FALLBACK_PLACEHOLDERS } from "./skeleton.js";
 import { createLogger } from "../logging.js";
 const logger = createLogger("today-direct-writer");
 const AGENT_LOG_HEADER = "## Agent Log";
@@ -87,6 +95,75 @@ export async function appendAgentLogLine(input) {
         input.todayWriteLock.release(lock.lockId);
     }
 }
+/**
+ * Canonical empty `today.md` skeleton, reused byte-for-byte from the
+ * boot-time seeder (`skeleton.ts`) so a refresh-path seed and a
+ * fresh-install seed produce identical structure. `skeleton.test.ts`
+ * asserts this placeholder matches `agent-assets/templates/state/today.md`
+ * byte-for-byte, so the two definitions never drift. The non-null
+ * assertion is safe: the key is a literal entry of `FALLBACK_PLACEHOLDERS`.
+ */
+const TODAY_SKELETON = FALLBACK_PLACEHOLDERS[CONTEXT_RELATIVE_PATHS.today];
+/**
+ * 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 async function ensureTodaySkeleton(input) {
+    const lock = input.todayWriteLock.acquire();
+    if (!lock.ok) {
+        logger.info({ holder: lock.holder }, "Skipping today.md skeleton seed — today-write-lock held");
+        return { seeded: false, reason: "lock_unavailable" };
+    }
+    try {
+        const path = fullPath(input.contextDir, CONTEXT_RELATIVE_PATHS.today);
+        return await serializeContextFileWrite(path, () => {
+            if (existsSync(path)) {
+                return {
+                    seeded: false,
+                    reason: "already_present",
+                };
+            }
+            try {
+                writeFileAtomically(path, TODAY_SKELETON);
+                logger.info({ path }, "Seeded today.md skeleton for refresh — file was absent (morning routine not yet run for the agent-day)");
+                return { seeded: true };
+            }
+            catch (err) {
+                logger.error({ err, path }, "Failed to seed today.md skeleton");
+                return { seeded: false, reason: "io_error" };
+            }
+        });
+    }
+    finally {
+        input.todayWriteLock.release(lock.lockId);
+    }
+}
 /**
  * Splice a new bullet line into the `## Agent Log` section, immediately
  * before the next `## ` heading or end-of-file. Returns null when the

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/wiki/wiki-fts.js

@@ -110,15 +110,22 @@ function extractTitleAndBody(content) {
     return { title, body };
 }
 function stripFrontmatter(content) {
-    if (!content.startsWith("---\n")) {
-        return { frontmatterKeys: {}, body: content };
+    // Obsidian vaults authored/synced on Windows (or checked out under
+    // git core.autocrlf=true) are CRLF. The frontmatter fence gate below is
+    // LF-only, so without this normalize a `---\r\n…---\r\n` block leaks into
+    // the indexed body and the title fallback never populates. Indexed
+    // body/title are search tokens only and never round-trip to disk, so
+    // collapsing interior CRLF to LF is harmless (LF input is unchanged).
+    const normalized = content.replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---\n")) {
+        return { frontmatterKeys: {}, body: normalized };
     }
-    const end = content.indexOf("\n---\n", 4);
+    const end = normalized.indexOf("\n---\n", 4);
     if (end < 0) {
-        return { frontmatterKeys: {}, body: content };
+        return { frontmatterKeys: {}, body: normalized };
     }
-    const frontmatter = content.slice(4, end);
-    const body = content.slice(end + 5);
+    const frontmatter = normalized.slice(4, end);
+    const body = normalized.slice(end + 5);
     const keys = {};
     for (const line of frontmatter.split("\n")) {
         const match = line.match(/^title:\s*(.*?)\s*$/);

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;