@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/custom-routines.d.ts

@@ -0,0 +1,99 @@
+import { customRoutineSlugFromKey } from "@aitne/shared";
+/**
+ * LEGACY custom-routine file format (B-007 §5.8 Q3) — parsing/enumeration
+ * helpers only.
+ *
+ * The subsystem that FIRED these files (`CustomRoutineScheduler`, a per-file
+ * node-cron job emitting `routine.custom.<slug>` events) was retired at the
+ * Agents-hub redesign (AGENTS_HUB_REDESIGN_PLAN.md §3): user-defined recurring
+ * work is a user Agent now (`agents` + `recurring_schedules`, visible on
+ * `/agents` with metrics and execution history). What remains here serves two
+ * callers:
+ *
+ *   1. `core/agents/custom-routine-migration.ts` — the one-time boot converter
+ *      that turns each valid `policies/routines/custom/<slug>.md` into a user
+ *      Agent definition.
+ *   2. `core/context-validation/` — writes under the legacy path are still
+ *      validated against this format so existing files stay well-formed
+ *      (they are inert post-migration; the prompt-injection branch in
+ *      `policy-files.ts` remains for one release).
+ */
+export interface CustomRoutineSpec {
+    slug: string;
+    cron: string;
+    enabled: boolean;
+    /**
+     * Canonical model tier. Normalized from frontmatter — both legacy
+     * `light`/`heavy` and current `lite`/`medium`/`high` strings are
+     * accepted at parse time (`light → medium`, `heavy → high`).
+     */
+    backendTier: "lite" | "medium" | "high";
+    maxBudgetUsd: number;
+    processKey: string;
+}
+export type CustomRoutineParseError = {
+    kind: "missing_field";
+    field: string;
+} | {
+    kind: "invalid_cron";
+    value: string;
+} | {
+    kind: "invalid_slug";
+    value: string;
+} | {
+    kind: "invalid_type";
+    value: string;
+} | {
+    kind: "invalid_process_key";
+    value: string;
+} | {
+    kind: "invalid_enabled";
+    value: string;
+} | {
+    kind: "invalid_tier";
+    value: string;
+} | {
+    kind: "invalid_budget";
+    value: string;
+} | {
+    kind: "missing_checks_section";
+} | {
+    kind: "no_frontmatter";
+};
+export interface CustomRoutineEnumerationResult {
+    specs: CustomRoutineSpec[];
+    errors: {
+        slug: string;
+        error: CustomRoutineParseError;
+    }[];
+}
+/**
+ * Parse a `policies/routines/custom/<slug>.md` file body into a validated spec.
+ * Pure function — safe to unit-test exhaustively. Returns a discriminated
+ * result so callers can log structured errors without throwing.
+ */
+export declare function parseCustomRoutineSpec(slug: string, body: string): {
+    ok: true;
+    spec: CustomRoutineSpec;
+} | {
+    ok: false;
+    error: CustomRoutineParseError;
+};
+/**
+ * Enumerate every `policies/routines/custom/*.md` file under `contextDir` and
+ * parse each into a spec. Errors are returned alongside the successful
+ * specs so callers can log them without aborting.
+ *
+ * The readers are injectable for tests — by default they read from disk; a
+ * missing directory yields empty results.
+ */
+export declare function enumerateCustomRoutines(contextDir: string, options?: {
+    readDir?: (dir: string) => string[];
+    readFile?: (path: string) => string;
+}): CustomRoutineEnumerationResult;
+/**
+ * Convenience: extract the slug from a `policies/routines/custom/<slug>.md` path.
+ * Returns null if the path is outside the custom-routine directory.
+ */
+export declare function slugFromCustomRoutinePath(relativePath: string): string | null;
+export { customRoutineSlugFromKey };

package/dist/core/custom-routines.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import cron from "node-cron";
+import { customRoutineKey, customRoutineSlugFromKey } from "@aitne/shared";
+import { CONTEXT_RELATIVE_PATHS } from "./context-paths.js";
+/**
+ * Extract the frontmatter body between the opening and closing `---`
+ * delimiters. Returns null when the file has no YAML frontmatter.
+ */
+function extractFrontmatter(content) {
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+        return null;
+    }
+    const afterOpen = content.startsWith("---\r\n") ? 5 : 4;
+    const endIdx = content.indexOf("\n---", afterOpen - 1);
+    if (endIdx < 0)
+        return null;
+    return content.slice(afterOpen, endIdx);
+}
+function readScalar(frontmatter, field) {
+    const re = new RegExp(`^${field}\\s*:\\s*(.+?)\\s*$`, "m");
+    const m = frontmatter.match(re);
+    if (!m)
+        return null;
+    let v = m[1].trim();
+    // Strip surrounding quotes (single or double).
+    if ((v.startsWith('"') && v.endsWith('"')) ||
+        (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+    }
+    return v;
+}
+function hasChecksSection(content) {
+    return /^##\s+Checks\s*$/m.test(content);
+}
+/**
+ * Parse a `policies/routines/custom/<slug>.md` file body into a validated spec.
+ * Pure function — safe to unit-test exhaustively. Returns a discriminated
+ * result so callers can log structured errors without throwing.
+ */
+export function parseCustomRoutineSpec(slug, body) {
+    if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(slug) || slug.length > 64) {
+        return { ok: false, error: { kind: "invalid_slug", value: slug } };
+    }
+    const fm = extractFrontmatter(body);
+    if (fm === null) {
+        return { ok: false, error: { kind: "no_frontmatter" } };
+    }
+    const typeRaw = readScalar(fm, "type");
+    if (!typeRaw) {
+        return { ok: false, error: { kind: "missing_field", field: "type" } };
+    }
+    if (typeRaw !== "rule") {
+        return { ok: false, error: { kind: "invalid_type", value: typeRaw } };
+    }
+    const slugRaw = readScalar(fm, "slug");
+    if (!slugRaw) {
+        return { ok: false, error: { kind: "missing_field", field: "slug" } };
+    }
+    if (slugRaw !== slug) {
+        return { ok: false, error: { kind: "invalid_slug", value: slugRaw } };
+    }
+    const processKeyRaw = readScalar(fm, "process_key");
+    if (!processKeyRaw) {
+        return { ok: false, error: { kind: "missing_field", field: "process_key" } };
+    }
+    if (processKeyRaw !== customRoutineKey(slug)) {
+        return { ok: false, error: { kind: "invalid_process_key", value: processKeyRaw } };
+    }
+    const cronExpr = readScalar(fm, "cron");
+    if (!cronExpr) {
+        return { ok: false, error: { kind: "missing_field", field: "cron" } };
+    }
+    if (!cron.validate(cronExpr)) {
+        return { ok: false, error: { kind: "invalid_cron", value: cronExpr } };
+    }
+    const tierRaw = readScalar(fm, "backend_tier");
+    if (!tierRaw) {
+        return { ok: false, error: { kind: "missing_field", field: "backend_tier" } };
+    }
+    // Accept the legacy two-tier names ("light" / "heavy") and the canonical
+    // three-tier names ("lite" / "medium" / "high"). Legacy "light" maps to
+    // Sonnet (medium) and "heavy" to Opus (high), preserving behavior of
+    // user-authored routine files written before the rename.
+    const tierAliasMap = {
+        "lite": "lite",
+        "medium": "medium",
+        "high": "high",
+        "light": "medium",
+        "heavy": "high",
+    };
+    const normalizedTier = tierAliasMap[tierRaw];
+    if (!normalizedTier) {
+        return { ok: false, error: { kind: "invalid_tier", value: tierRaw } };
+    }
+    const budgetRaw = readScalar(fm, "max_budget_usd");
+    if (!budgetRaw) {
+        return { ok: false, error: { kind: "missing_field", field: "max_budget_usd" } };
+    }
+    const budget = Number(budgetRaw);
+    if (!Number.isFinite(budget) || budget <= 0) {
+        return { ok: false, error: { kind: "invalid_budget", value: budgetRaw } };
+    }
+    const enabledRaw = readScalar(fm, "enabled");
+    if (!enabledRaw) {
+        return { ok: false, error: { kind: "missing_field", field: "enabled" } };
+    }
+    if (enabledRaw !== "true" && enabledRaw !== "false") {
+        return { ok: false, error: { kind: "invalid_enabled", value: enabledRaw } };
+    }
+    const enabled = enabledRaw === "true";
+    if (!hasChecksSection(body)) {
+        return { ok: false, error: { kind: "missing_checks_section" } };
+    }
+    return {
+        ok: true,
+        spec: {
+            slug,
+            cron: cronExpr,
+            enabled,
+            backendTier: normalizedTier,
+            maxBudgetUsd: budget,
+            processKey: customRoutineKey(slug),
+        },
+    };
+}
+/**
+ * Enumerate every `policies/routines/custom/*.md` file under `contextDir` and
+ * parse each into a spec. Errors are returned alongside the successful
+ * specs so callers can log them without aborting.
+ *
+ * The readers are injectable for tests — by default they read from disk; a
+ * missing directory yields empty results.
+ */
+export function enumerateCustomRoutines(contextDir, options) {
+    const dir = join(contextDir, CONTEXT_RELATIVE_PATHS.routines.customDir);
+    const readDir = options?.readDir ?? defaultReadDir;
+    const readFile = options?.readFile ?? defaultReadFile;
+    const files = readDir(dir);
+    const specs = [];
+    const errors = [];
+    for (const fileName of files) {
+        if (!fileName.endsWith(".md"))
+            continue;
+        const slug = fileName.slice(0, -3);
+        let body;
+        try {
+            body = readFile(join(dir, fileName));
+        }
+        catch {
+            continue;
+        }
+        const result = parseCustomRoutineSpec(slug, body);
+        if (result.ok) {
+            specs.push(result.spec);
+        }
+        else {
+            errors.push({ slug, error: result.error });
+        }
+    }
+    return { specs, errors };
+}
+function defaultReadDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir);
+}
+function defaultReadFile(path) {
+    return readFileSync(path, "utf-8");
+}
+/**
+ * Convenience: extract the slug from a `policies/routines/custom/<slug>.md` path.
+ * Returns null if the path is outside the custom-routine directory.
+ */
+export function slugFromCustomRoutinePath(relativePath) {
+    const prefix = `${CONTEXT_RELATIVE_PATHS.routines.customDir}/`;
+    if (!relativePath.startsWith(prefix))
+        return null;
+    const rest = relativePath.slice(prefix.length);
+    if (!rest.endsWith(".md"))
+        return null;
+    const slug = rest.slice(0, -3);
+    if (slug.includes("/"))
+        return null;
+    return slug;
+}
+export { customRoutineSlugFromKey };

package/dist/core/daemon-api-cli.js

@@ -1,5 +1,6 @@
 import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
+import { BACKEND_IDS, getManagedApiKeyEnvVars, } from "@aitne/shared";
 export const SESSION_DAEMON_API_BIN_DIR = join(".pa", "bin");
 export const SESSION_DAEMON_API_CLI_REL_PATH = join(SESSION_DAEMON_API_BIN_DIR, "pa-api");
 export const SESSION_DAEMON_CURL_SHIM_REL_PATH = join(SESSION_DAEMON_API_BIN_DIR, "curl");
@@ -708,6 +709,50 @@ export function ensureDaemonApiCli(sessionDir) {
     /* c8 ignore stop */
     return cliPath;
 }
+/**
+ * Daemon-internal secrets that must NEVER be inherited by an agent
+ * subprocess. Agents run with bypassPermissions and have Bash; `env` /
+ * `printenv` / `process.env` cannot be blocked at the tool layer, so a
+ * prompt-injected session could exfiltrate anything in its environment.
+ * `PA_MASTER_PASSWORD` decrypts the *entire* file-fallback secret store and
+ * has no legitimate use in a child process.
+ */
+const ALWAYS_STRIP_FROM_CHILD_ENV = ["PA_MASTER_PASSWORD"];
+function isBackendId(value) {
+    return BACKEND_IDS.includes(value);
+}
+/**
+ * Strip credentials a child agent must not see from a copied env:
+ *  - daemon-internal secrets (master password) — always.
+ *  - inactive backends' provider API keys — when the active backend is
+ *    known. The keychain mirror exports every configured backend's provider
+ *    key into the daemon's `process.env` globally, so without this a Claude
+ *    session's env also carries the user's OpenAI / Gemini / OpenCode
+ *    credentials. Scoping the keys to the backend that actually uses them
+ *    keeps a prompt-injected child from exfiltrating credentials it never
+ *    needs. Only applied when `sessionBackend` is a recognised backend id;
+ *    an absent/unknown value leaves the env untouched (no behaviour change
+ *    for non-agent spawns).
+ */
+function scrubSensitiveChildEnv(env, sessionBackend) {
+    for (const name of ALWAYS_STRIP_FROM_CHILD_ENV) {
+        delete env[name];
+    }
+    if (!sessionBackend || !isBackendId(sessionBackend))
+        return;
+    const activeVars = new Set(getManagedApiKeyEnvVars(sessionBackend));
+    for (const backendId of BACKEND_IDS) {
+        if (backendId === sessionBackend)
+            continue;
+        for (const name of getManagedApiKeyEnvVars(backendId)) {
+            // Keep any var the active backend also relies on (shared across
+            // providers, e.g. a common cloud credential).
+            if (activeVars.has(name))
+                continue;
+            delete env[name];
+        }
+    }
+}
 export function buildDaemonApiCliEnv(sessionDir, apiPort, optionsOrReadToken) {
     const options = typeof optionsOrReadToken === "string"
         ? { readToken: optionsOrReadToken }
@@ -721,6 +766,10 @@ export function buildDaemonApiCliEnv(sessionDir, apiPort, optionsOrReadToken) {
         PATH: pathParts.join(delimiter),
         [DAEMON_API_BASE_URL_ENV]: `http://127.0.0.1:${apiPort}`,
     };
+    // Remove daemon-internal secrets and inactive-backend provider keys before
+    // the child ever sees them. Must run after the process.env copy and before
+    // the PA_* identity vars below (which the child legitimately needs).
+    scrubSensitiveChildEnv(env, options.sessionBackend);
     if (options.readToken) {
         env[DAEMON_API_READ_TOKEN_ENV] = options.readToken;
     }

package/dist/core/day-boundary.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Day-boundary task runner with a per-agent-day idempotence marker —
+ * RESEARCH_CLUSTER_COST_FIX_PLAN.md F2 (defense in depth on top of the
+ * F1 per-cluster enqueue stamp).
+ *
+ * The scheduler invokes its day-boundary callback from THREE sites: the
+ * 04:00 cron, wake catch-up (which fires on every detected sleep gap
+ * >= 5 min — every macOS maintenance DarkWake), and the morning
+ * self-heal missed-fire path. Before this marker existed, each replay
+ * re-ran the full callback body; on 2026-06-11 that re-enqueued the
+ * same research cluster ~25x in one morning. Wrapping the body HERE —
+ * the single composition point — protects every future day-boundary
+ * addition, not just the research fan-out.
+ *
+ * Marker semantics: `runtime_state.day_boundary_last_agent_day` is
+ * written AFTER the body completes, not before. A sleep-interrupted or
+ * failed body therefore retries on the next scheduler fire (all three
+ * scheduler sites catch + log callback rejections), while replay safety
+ * of the individual steps comes from the steps themselves — the F1
+ * stamp for the fan-out, summarizeDmSessions' own incremental gating.
+ */
+import type Database from "better-sqlite3";
+export declare const DAY_BOUNDARY_LAST_AGENT_DAY_KEY = "day_boundary_last_agent_day";
+export interface DayBoundaryTasksDeps {
+    db: Database.Database;
+    /** Local agent-day label ('YYYY-MM-DD') the caller computes via
+     *  `getAgentDayDateStr(config.timezone, config.dayBoundaryHour)`. */
+    todayAgentDay: string;
+    summarizeDmSessions: () => Promise<void>;
+    fanoutResearchClusterUpdates: () => Promise<{
+        enqueuedSlugs: string[];
+    }>;
+}
+export type DayBoundaryTasksResult = {
+    ran: false;
+} | {
+    ran: true;
+    enqueuedSlugs: string[];
+};
+/**
+ * Run the day-boundary body at most once per agent-day. Returns
+ * `{ ran: false }` when the marker shows the body already completed for
+ * `todayAgentDay`. Errors propagate to the caller WITHOUT writing the
+ * marker, so the next scheduler fire retries the whole body.
+ */
+export declare function runDayBoundaryTasks(deps: DayBoundaryTasksDeps): Promise<DayBoundaryTasksResult>;

package/dist/core/day-boundary.js

@@ -0,0 +1,40 @@
+/**
+ * Day-boundary task runner with a per-agent-day idempotence marker —
+ * RESEARCH_CLUSTER_COST_FIX_PLAN.md F2 (defense in depth on top of the
+ * F1 per-cluster enqueue stamp).
+ *
+ * The scheduler invokes its day-boundary callback from THREE sites: the
+ * 04:00 cron, wake catch-up (which fires on every detected sleep gap
+ * >= 5 min — every macOS maintenance DarkWake), and the morning
+ * self-heal missed-fire path. Before this marker existed, each replay
+ * re-ran the full callback body; on 2026-06-11 that re-enqueued the
+ * same research cluster ~25x in one morning. Wrapping the body HERE —
+ * the single composition point — protects every future day-boundary
+ * addition, not just the research fan-out.
+ *
+ * Marker semantics: `runtime_state.day_boundary_last_agent_day` is
+ * written AFTER the body completes, not before. A sleep-interrupted or
+ * failed body therefore retries on the next scheduler fire (all three
+ * scheduler sites catch + log callback rejections), while replay safety
+ * of the individual steps comes from the steps themselves — the F1
+ * stamp for the fan-out, summarizeDmSessions' own incremental gating.
+ */
+import { readRuntimeState, writeRuntimeState } from "../db/runtime-state.js";
+export const DAY_BOUNDARY_LAST_AGENT_DAY_KEY = "day_boundary_last_agent_day";
+/**
+ * Run the day-boundary body at most once per agent-day. Returns
+ * `{ ran: false }` when the marker shows the body already completed for
+ * `todayAgentDay`. Errors propagate to the caller WITHOUT writing the
+ * marker, so the next scheduler fire retries the whole body.
+ */
+export async function runDayBoundaryTasks(deps) {
+    const { db, todayAgentDay } = deps;
+    const lastRunAgentDay = readRuntimeState(db, DAY_BOUNDARY_LAST_AGENT_DAY_KEY);
+    if (lastRunAgentDay === todayAgentDay) {
+        return { ran: false };
+    }
+    await deps.summarizeDmSessions();
+    const fanout = await deps.fanoutResearchClusterUpdates();
+    writeRuntimeState(db, DAY_BOUNDARY_LAST_AGENT_DAY_KEY, todayAgentDay);
+    return { ran: true, enqueuedSlugs: fanout.enqueuedSlugs };
+}

package/dist/core/dispatcher-activity-scan.d.ts

@@ -0,0 +1,221 @@
+/**
+ * `ActivityScanCoordinator` — owns the dispatcher's
+ * `triggerActivityScan` entry point and the cost-reduction-structural §B
+ * three-stage gate that fronts it. The coordinator decides whether a
+ * given hourly tick:
+ *   - skips (autonomous gate / morning routine active / already running
+ *     / below threshold);
+ *   - silently consumes observations + records an Agent Log line
+ *     (Stage 0 deterministic gate or Stage 2 lite-tier `log_only`);
+ *   - escalates to the existing Stage 3 enqueue (Stage 2 `escalate`
+ *     verdict or `failed` cautious-escalate path).
+ *
+ * Extracted from `core/dispatcher.ts` as part of phase D-2 of
+ * `docs/design/appendices/file-split-plan.md`. Pattern B (stateful
+ * coordinator): the coordinator owns the gate logic but borrows live
+ * accessors for state the dispatcher continues to own — the
+ * `activityScanInProgress` flag (atomic check-and-set inside the
+ * trigger), the `morningRoutineInProgress` flag (read-only), and the
+ * lazily-injected delegated-sync refresh callback.
+ *
+ * Dispatcher entry points served:
+ *   - `EventDispatcher.triggerActivityScan(source, options)` is now a
+ *     thin one-liner that delegates to `trigger(source, options)`.
+ *
+ * Invariants preserved bit-for-bit from
+ * `docs/design/02-event-pipeline.md` §2:
+ *   - skip-if-morning-routine-in-progress;
+ *   - skip-if-hourly-already-running (atomic flag flip BEFORE any
+ *     await boundary — the C1 race fix from before the split);
+ *   - skip-if-pending-observations-below-threshold (legacy
+ *     min-observations floor honoured only when the gate would have
+ *     proceeded to Stage 3 anyway);
+ *   - skip-if-setup-incomplete / vault-degraded / user-paused via
+ *     `isAutonomousAllowed`.
+ *
+ * Shared-state references held:
+ *   - `setActivityScanInProgress` / `isActivityScanInProgress` —
+ *     getter/setter pair around the dispatcher's flag. The flag is
+ *     left `true` when an enqueue actually happens (the EventBus
+ *     consumer's `dispatchSafe` finally clears it on routine
+ *     completion); it is reset inline when the coordinator owns the
+ *     turn (silent gate paths) or when the trigger is skipping.
+ *   - `isMorningRoutineActive` — read-only mirror of the dispatcher
+ *     method so the gate stays single-sourced.
+ *   - `isAutonomousAllowed` — same; returns the
+ *     `TriggerActivityScanSkipReason` the gate should surface.
+ *   - `getDelegatedSyncRefresh` — accessor; null when no delegated
+ *     integration is wired, in which case the gate proceeds without
+ *     a refresh, matching pre-injection behaviour.
+ */
+import type Database from "better-sqlite3";
+import type { IntegrationKey } from "@aitne/shared";
+import type { AgentConfig } from "../config.js";
+import type { EventBus } from "./event-bus.js";
+import type { TodayWriteLockManager } from "./today-write-lock.js";
+import type { IAgentRouter } from "./backends/backend-router.js";
+import type { IAuditLogger, IContextBuilder, TriggerActivityScanOptions, TriggerActivityScanResult, TriggerActivityScanSkipReason } from "./dispatcher-types.js";
+import type { PromptAssembler } from "./dispatcher-prompt.js";
+import type { RoutineFetchWindowRunner } from "./routine-fetch-window-runner.js";
+export interface ActivityScanCoordinatorDeps {
+    db: Database.Database;
+    config: AgentConfig;
+    eventBus: EventBus;
+    contextBuilder: IContextBuilder;
+    agentRouter: IAgentRouter;
+    audit: IAuditLogger;
+    todayWriteLock: TodayWriteLockManager | undefined;
+    prompt: PromptAssembler;
+    /**
+     * docs/design/appendices/routine-data-acquisition.md Phase 4 / D3 — pre-pass runner
+     * spawned between Stage 2 (lite-tier triage) and Stage 3 (medium-tier
+     * main session) on `escalate` / `failed` verdicts. The rendered
+     * `<fetch_report>` block rides on the Stage 3 RoutineEvent's
+     * `event.data.fetchReportBlock` so ContextBuilder folds it into the
+     * Stage 3 prompt.
+     */
+    fetchWindowRunner: RoutineFetchWindowRunner;
+    /** Accessor for the lazily-injected delegated-sync refresh callback. */
+    getDelegatedSyncRefresh: () => (() => Promise<void>) | null;
+    /** Setter for the dispatcher's `activityScanInProgress` flag. */
+    setActivityScanInProgress: (value: boolean) => void;
+    /** Getter for the dispatcher's `activityScanInProgress` flag. */
+    isActivityScanInProgress: () => boolean;
+    /** Mirrors `EventDispatcher.isMorningRoutineActive`. */
+    isMorningRoutineActive: () => boolean;
+    /**
+     * Mirrors `EventDispatcher.isAutonomousAllowed`. Returns the
+     * skip-reason when the gate must abort early (setup incomplete,
+     * vault degraded, user paused) or `null` when autonomous work is
+     * permitted to proceed.
+     */
+    isAutonomousAllowed: () => TriggerActivityScanSkipReason | null;
+    /**
+     * Accessor for the scheduler's `queueMorningRoutineWake`. Returns the
+     * bound function once wiring has completed, or `null` early in startup
+     * before the scheduler is constructed. The pre-routine gate calls this
+     * when it detects the current agent-day's morning_routine has not run
+     * yet (typical cause: Mac slept through the 04:00 cron tick). The
+     * wake row carries the dedup guarantee — multiple back-to-back hourly
+     * ticks all see the same in-flight row instead of stacking up.
+     */
+    getQueueMorningRoutineWake: () => QueueMorningRoutineWake | null;
+}
+/** Signature of `AgentScheduler.queueMorningRoutineWake`, narrowed to the
+ *  surface the dispatcher gate consumes. Kept structural so we don't pull
+ *  the scheduler class into this module just for a type reference. */
+export type QueueMorningRoutineWake = (source: string, options?: {
+    postCatchupRoutines?: string[];
+    postCatchupActivityScan?: boolean;
+}) => {
+    inserted: boolean;
+    existingId?: number;
+};
+/**
+ * HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.3 + §7.2 — outcome of the
+ * Layer-1 pre-pass harvest that runs at the top of `trigger()` for
+ * delegated/native integrations. Surfaced both in the audit row (per-
+ * tick observability) and on the Stage 3 event (the rendered
+ * `<fetch_report>` block).
+ */
+export interface HarvestResult {
+    /** True when at least one integration was eligible and the runner ran. */
+    ran: boolean;
+    /** Integrations whose sub-session completed successfully or partially. */
+    integrations: IntegrationKey[];
+    /** Eligible integrations suppressed by the freshness window. */
+    skippedIntegrations: IntegrationKey[];
+    /** Eligible integrations whose sub-session ended in `failed`. */
+    failedIntegrations: IntegrationKey[];
+    /** Wall-clock time spent on the harvest (ms). */
+    durationMs: number;
+    /**
+     * True when any eligible integration failed. Triggers §3.5 cautious-
+     * escalate: gate decision is forced to `stage3` regardless of the
+     * signal verdict so a fetch outage doesn't manifest as silent
+     * stage0.
+     */
+    failed: boolean;
+    /**
+     * Rendered `<fetch_report>` block from the runner, ready to plumb
+     * onto `stage3Event.data.fetchReportBlock`. `null` when the runner
+     * was not spawned (no eligible integrations) — in that case the
+     * Stage 3 prompt simply omits the block.
+     */
+    fetchReportBlock: string | null;
+}
+export declare class ActivityScanCoordinator {
+    private readonly db;
+    private readonly config;
+    private readonly eventBus;
+    private readonly contextBuilder;
+    private readonly agentRouter;
+    private readonly audit;
+    private readonly todayWriteLock;
+    private readonly prompt;
+    private readonly fetchWindowRunner;
+    private readonly getDelegatedSyncRefresh;
+    private readonly setActivityScanInProgress;
+    private readonly isActivityScanInProgress;
+    private readonly isMorningRoutineActive;
+    private readonly isAutonomousAllowed;
+    private readonly getQueueMorningRoutineWake;
+    constructor(deps: ActivityScanCoordinatorDeps);
+    trigger(source: string, options?: TriggerActivityScanOptions): Promise<TriggerActivityScanResult>;
+    /**
+     * HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.3 Layer 1 — pre-pass harvest
+     * for active non-direct integrations. Reads the per-integration
+     * `pre_pass_last_run:<key>` freshness key; integrations whose last
+     * successful run is within `activityScanPrePassFreshnessMinutes` are
+     * skipped this tick. Forced runs (`/api/agent/run-now`) bypass the
+     * freshness gate.
+     *
+     * Returns a `HarvestResult` so the caller can:
+     *   - emit telemetry (which integrations fetched, which skipped on
+     *     freshness, which failed),
+     *   - cautious-escalate when any non-direct integration failed
+     *     (§3.5 — prevents silent stage0 from masking a fetch outage),
+     *   - plumb the rendered `<fetch_report>` block onto the Stage 3
+     *     event so ContextBuilder folds it into the prompt.
+     */
+    private harvestForGate;
+    /**
+     * cost-reduction-structural §B — pull a fresh signal snapshot and run
+     * the deterministic gate. Helper so the dispatcher's call site stays
+     * compact and tests can spy on the boundary.
+     */
+    private computeActivityScanGateDecision;
+    private readTodayMdSafe;
+    /**
+     * cost-reduction-structural §B — daemon-direct silent path. Used by
+     * Stage 0 and Stage 2 log-only verdicts. Consumes pending user
+     * observations + appends a single Agent Log line + records the gate
+     * verdict to `agent_actions`. The flag is reset before return.
+     */
+    private runSilentActivityScanPath;
+    private enqueueStage3ActivityScan;
+    private logGateAuditRow;
+    /**
+     * cost-reduction-structural §B Stage 2 — synchronous lite-tier triage.
+     * Builds a `routine.activity_scan.triage` RoutineEvent and runs it
+     * inline through the agent router (NOT the EventBus, so the result
+     * is available before we decide whether to silence or escalate).
+     *
+     * The agent contract is JSON-only output (`{ "action": "log_only" |
+     * "escalate", "reason": "..." }`); on parse failure we return
+     * `'failed'` and the caller treats that as cautious escalate.
+     *
+     * Tool/turn clamp (defense-in-depth):
+     *   - `allowedToolsOverride: []` removes every tool from the SDK's
+     *     allowlist for the spawn. Stage 2 has nothing to do but emit a
+     *     JSON line; the design's "no write tools" rule is enforced here
+     *     instead of relying on the prompt alone.
+     *   - `maxTurns: 1` caps the spawn at a single assistant turn. Even
+     *     if a future prompt change accidentally invites tool use, the
+     *     spawn cannot loop. Codex/Gemini have no per-spawn `allowedTools`
+     *     surface today (acknowledged gap in `agent-core.ts`); the
+     *     `maxTurns` cap and process_backend_config envelope are the
+     *     remaining safety floor on those backends.
+     */
+    private runStage2Triage;
+}