@aitne/daemon 0.1.10 → 0.1.11

package/dist/scheduler/activity-scan-gate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Stage-1 deterministic gate for the three-stage activity_scan funnel
+ * (cost-reduction-structural §B). Pure function over a `ActivityScanSignals`
+ * snapshot — no DB handle, no clock, no I/O. The dispatcher computes the
+ * snapshot via `computeActivityScanSignals`, then asks this module which
+ * stage to enter.
+ *
+ * The four possible decisions:
+ *   - `stage0_silent`: consume observations, append a single Agent Log
+ *     line via the daemon-direct writer, return. No LLM call.
+ *   - `stage2`: lite-tier triage (only when `stage2Enabled`). Strict
+ *     JSON-only output decides log_only vs escalate.
+ *   - `stage3`: existing full activity_scan session.
+ *
+ * HOURLY_CHECK_GATE_REDESIGN_PLAN.md Phase 4 collapsed the gateMode
+ * enum (`off`/`shadow`/`live`) into a single execution path. The gate's
+ * verdict is always honoured.
+ */
+import type { ActivityScanSignals } from "../db/activity-scan-signals.js";
+export type ActivityScanGateStage = "stage0_silent" | "stage2" | "stage3";
+export interface ActivityScanGateConfig {
+    /**
+     * Hours since the last Stage 3 run after which the gate force-runs at
+     * least Stage 2 (or Stage 3 if novelty is high). Bounds the worst case
+     * where Stage 0/1 keeps short-circuiting on a quiet day.
+     */
+    heartbeatHours: number;
+    /**
+     * When `false`, low-signal cases bypass Stage 2 entirely and route to
+     * Stage 3. The cautious default — Stage 2 only takes effect after
+     * shadow telemetry validates the decision boundary.
+     */
+    stage2Enabled: boolean;
+    /**
+     * Below this threshold, `pendingObsCount` alone does not imply
+     * Stage 3. Default 0 — any pending observation hits the low-signal
+     * branch which routes to Stage 2 or Stage 3 depending on the flag.
+     */
+    pendingObsLowSignalCeiling?: number;
+}
+export interface ActivityScanGateDecision {
+    stage: ActivityScanGateStage;
+    /** Short, telemetry-friendly explanation. */
+    reason: string;
+    /** Snapshot at decision time (echoed for the audit row). */
+    signals: ActivityScanSignals;
+}
+export declare function decideStage(signals: ActivityScanSignals, config: ActivityScanGateConfig): ActivityScanGateDecision;
+/**
+ * The dispatcher logs every cron tick to `agent_actions` regardless of
+ * which stage runs. Helper that builds the JSON payload from a decision
+ * so the schema stays consistent across stages and call-sites.
+ */
+export declare function buildGateAuditDetail(decision: ActivityScanGateDecision, extra: {
+    appliedDecision: ActivityScanGateStage;
+    /** Stage-2 LLM verdict, when Stage 2 ran. */
+    stage2Verdict?: "log_only" | "escalate" | "failed";
+    /** Forced-run flag from `/api/agent/run-now` etc. */
+    forced?: boolean;
+    /**
+     * HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.5 — true when pre-pass for
+     * any non-direct integration failed in `harvestForGate` and the
+     * gate force-escalated to `stage3` regardless of the signal
+     * verdict. Surfaced in the audit row so dashboards can flag the
+     * cautious-escalate path.
+     */
+    cautiousEscalate?: boolean;
+    /**
+     * Original gate verdict captured BEFORE cautious-escalate
+     * overwrote it. Persisted as `pre_escalate_gate_*` so dashboards
+     * can answer "what would the gate have said if pre-pass had
+     * succeeded?" — distinguishes a tick that was structurally
+     * stage3 anyway from one that was forced up from stage0_silent
+     * by a transient fetch outage.
+     */
+    preEscalateGateStage?: ActivityScanGateStage;
+    preEscalateGateReason?: string;
+}): Record<string, unknown>;
+/**
+ * Build the `<gate_decision>` block injected into Stage 3's prompt so
+ * the routine knows *why* it was escalated and can prioritize.
+ */
+export declare function renderGateDecisionBlock(decision: ActivityScanGateDecision, extra: {
+    forced?: boolean;
+    cautiousEscalate?: boolean;
+}): string;

package/dist/scheduler/activity-scan-gate.js

@@ -0,0 +1,132 @@
+/**
+ * Stage-1 deterministic gate for the three-stage activity_scan funnel
+ * (cost-reduction-structural §B). Pure function over a `ActivityScanSignals`
+ * snapshot — no DB handle, no clock, no I/O. The dispatcher computes the
+ * snapshot via `computeActivityScanSignals`, then asks this module which
+ * stage to enter.
+ *
+ * The four possible decisions:
+ *   - `stage0_silent`: consume observations, append a single Agent Log
+ *     line via the daemon-direct writer, return. No LLM call.
+ *   - `stage2`: lite-tier triage (only when `stage2Enabled`). Strict
+ *     JSON-only output decides log_only vs escalate.
+ *   - `stage3`: existing full activity_scan session.
+ *
+ * HOURLY_CHECK_GATE_REDESIGN_PLAN.md Phase 4 collapsed the gateMode
+ * enum (`off`/`shadow`/`live`) into a single execution path. The gate's
+ * verdict is always honoured.
+ */
+const HIGH_NOVELTY_FLOOR = 3;
+const ESCALATE_NOVELTY_FLOOR = 2;
+export function decideStage(signals, config) {
+    // Heartbeat: even on quiet days, exercise Stage 2/3 every N hours so
+    // the gate's signal compute is exercised end-to-end. We pick Stage 3
+    // when there is *some* novelty pending, Stage 2 otherwise — Stage 2
+    // is the cheaper lite-tier shape and Stage 3 wastes context if there
+    // is nothing to act on. If Stage 2 is disabled, the cautious fallback
+    // is Stage 3.
+    if (signals.hoursSinceLastStage3Run >= config.heartbeatHours) {
+        if (numericNovelty(signals.maxNoveltyScore) >= ESCALATE_NOVELTY_FLOOR) {
+            return decision("stage3", "heartbeat_due_with_novelty", signals);
+        }
+        return decision(config.stage2Enabled ? "stage2" : "stage3", "heartbeat_due", signals);
+    }
+    // Hard escalate: any high-priority signal goes straight to Stage 3.
+    if (numericNovelty(signals.maxNoveltyScore) >= HIGH_NOVELTY_FLOOR) {
+        return decision("stage3", "high_novelty", signals);
+    }
+    if (signals.calendarHasConflict) {
+        return decision("stage3", "calendar_conflict", signals);
+    }
+    if (signals.vipMailUnreadCount > 0) {
+        return decision("stage3", "vip_mail_unread", signals);
+    }
+    if (signals.agentPlanOverdueCount > 0) {
+        return decision("stage3", "agent_plan_overdue", signals);
+    }
+    if (signals.scheduleApproachingCount > 0) {
+        return decision("stage3", "schedule_approaching", signals);
+    }
+    // No signals at all → Stage 0 silent.
+    if (signals.pendingObsCount === 0 && !signals.calendarHas24hChange) {
+        return decision("stage0_silent", "no_signals", signals);
+    }
+    // Low signals only → Stage 2 if enabled, else Stage 3 (cautious default).
+    // The pendingObsLowSignalCeiling lets an operator widen the silent-skip
+    // band ("at most N noise observations is still nothing to act on"); the
+    // default 0 leaves the design's conservative posture intact.
+    const ceiling = Math.max(0, config.pendingObsLowSignalCeiling ?? 0);
+    if (signals.pendingObsCount <= ceiling
+        && !signals.calendarHas24hChange) {
+        return decision("stage0_silent", "low_signal_under_ceiling", signals);
+    }
+    return decision(config.stage2Enabled ? "stage2" : "stage3", "low_signal_default", signals);
+}
+/**
+ * The dispatcher logs every cron tick to `agent_actions` regardless of
+ * which stage runs. Helper that builds the JSON payload from a decision
+ * so the schema stays consistent across stages and call-sites.
+ */
+export function buildGateAuditDetail(decision, extra) {
+    return {
+        stage_reached: extra.appliedDecision,
+        gate_stage: decision.stage,
+        gate_reason: decision.reason,
+        forced: extra.forced ?? false,
+        ...(extra.stage2Verdict ? { stage2_verdict: extra.stage2Verdict } : {}),
+        ...(extra.cautiousEscalate ? { cautious_escalate: true } : {}),
+        ...(extra.preEscalateGateStage
+            ? { pre_escalate_gate_stage: extra.preEscalateGateStage }
+            : {}),
+        ...(extra.preEscalateGateReason
+            ? { pre_escalate_gate_reason: extra.preEscalateGateReason }
+            : {}),
+        signal_snapshot: {
+            pendingObsCount: decision.signals.pendingObsCount,
+            maxNoveltyScore: decision.signals.maxNoveltyScore,
+            noveltyDistribution: decision.signals.noveltyDistribution,
+            vipMailUnreadCount: decision.signals.vipMailUnreadCount,
+            calendarHas24hChange: decision.signals.calendarHas24hChange,
+            calendarHasConflict: decision.signals.calendarHasConflict,
+            agentPlanOverdueCount: decision.signals.agentPlanOverdueCount,
+            scheduleApproachingCount: decision.signals.scheduleApproachingCount,
+            hoursSinceLastStage3Run: serializeHours(decision.signals.hoursSinceLastStage3Run),
+        },
+    };
+}
+/**
+ * Build the `<gate_decision>` block injected into Stage 3's prompt so
+ * the routine knows *why* it was escalated and can prioritize.
+ */
+export function renderGateDecisionBlock(decision, extra) {
+    return [
+        "<gate_decision>",
+        `  triggered_by: ${decision.stage === "stage3" ? "stage1" : "stage2_escalation"}`,
+        `  reason: ${decision.reason}`,
+        `  forced: ${extra.forced ? "true" : "false"}`,
+        ...(extra.cautiousEscalate ? ["  cautious_escalate: true"] : []),
+        `  signals_snapshot: ${JSON.stringify({
+            maxNovelty: decision.signals.maxNoveltyScore,
+            pendingObs: decision.signals.pendingObsCount,
+            vipMail: decision.signals.vipMailUnreadCount,
+            calConflict: decision.signals.calendarHasConflict,
+            agentPlanOverdue: decision.signals.agentPlanOverdueCount,
+            scheduleApproaching: decision.signals.scheduleApproachingCount,
+        })}`,
+        "</gate_decision>",
+    ].join("\n");
+}
+function numericNovelty(score) {
+    // Cautious default — null (no summary done yet) is treated as 2 so a
+    // backlog of unsummarized observations does NOT silently skip the
+    // routine. The design doc calls this out explicitly under "edge cases".
+    return score ?? ESCALATE_NOVELTY_FLOOR;
+}
+function decision(stage, reason, signals) {
+    return { stage, reason, signals };
+}
+function serializeHours(value) {
+    if (!Number.isFinite(value))
+        return null;
+    return Number(value.toFixed(2));
+}

package/dist/services/background-task/background-task-budget.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Background-task budget envelope — BACKGROUND_TASK_RUNNER_DESIGN.md §6 / §10.1.
+ *
+ * Pure resolution of the `(modelId, maxTurns, maxBudgetUsd,
+ * executeTimeoutMinutes)` envelope for a background-task worker from
+ * three inputs:
+ *
+ *   1. The per-task `tier` (`lite` | `medium` | `high`) — selects the
+ *      base turn/budget/timeout envelope.
+ *   2. The optional per-task `maxBudgetUsd` override (POST body).
+ *   3. The operator-editable `process_backend_config` row for
+ *      `process_key='background_task'` (model + caps) — same chokepoint
+ *      as browser-task's `loadBrowserTaskBackendBinding`.
+ *
+ * The worker is Claude-only (it drives the Claude Agent SDK `query()`
+ * loop directly, like browser_task). A `process_backend_config` row that
+ * pins a non-Claude backend is refused with `backend_misconfigured` so a
+ * mis-set `/settings/models` row fails fast rather than silently doing
+ * nothing.
+ *
+ * 100% coverage gate — the I/O (DB read) lives in
+ * `loadBackgroundTaskBinding`; this module is the pure arithmetic.
+ */
+import type { BackgroundTaskTier } from "../../db/background-task-store.js";
+/** Fallback model when the `process_backend_config` row is missing or
+ *  carries an empty `main_model`. Mirrors the seed default. */
+export declare const BACKGROUND_TASK_FALLBACK_CLAUDE_MODEL = "claude-sonnet-4-6";
+export declare const BACKGROUND_TASK_DEFAULT_TIER: BackgroundTaskTier;
+/** Hard upper bounds. The seed sits well below; the caps give the
+ *  operator room to relax via `/settings/models` while pinning a ceiling
+ *  no per-task override can blow past. Background tasks are the
+ *  long-running surface, so the turn / timeout ceilings are far higher
+ *  than browser-task's (60 turns / 5 min) — a deep research or
+ *  multi-repo audit legitimately runs for many turns over many minutes. */
+export declare const BACKGROUND_TASK_MAX_TURNS_CAP = 120;
+export declare const BACKGROUND_TASK_MAX_BUDGET_USD_CAP = 15;
+export declare const BACKGROUND_TASK_MAX_EXECUTE_TIMEOUT_MINUTES = 120;
+export interface BackgroundTaskEnvelope {
+    modelId: string;
+    maxTurns: number;
+    maxBudgetUsd: number;
+    executeTimeoutMinutes: number;
+}
+interface TierEnvelope {
+    maxTurns: number;
+    maxBudgetUsd: number;
+    executeTimeoutMinutes: number;
+}
+export declare function tierEnvelope(tier: BackgroundTaskTier): TierEnvelope;
+/** Shape of the operator-editable `process_backend_config` row, already
+ *  read from the DB (or null when absent). */
+export interface BackgroundTaskProcessConfig {
+    mainBackend: string;
+    mainModel: string | null;
+    maxTurns: number | null;
+    maxBudgetUsd: number | null;
+}
+export interface ResolveEnvelopeInput {
+    tier: BackgroundTaskTier | null;
+    /** Per-task budget override (POST body). Clamped to the hard cap. */
+    maxBudgetUsd: number | null;
+    processConfig: BackgroundTaskProcessConfig | null;
+}
+export type ResolveEnvelopeResult = {
+    ok: true;
+    envelope: BackgroundTaskEnvelope;
+} | {
+    ok: false;
+    reason: "backend_misconfigured";
+    detail: string;
+};
+/**
+ * Pure envelope resolution. Branches:
+ *   - processConfig present + `mainBackend !== 'claude'` → REFUSE.
+ *   - otherwise: model from the config (or fallback); turns from the
+ *     config (or tier base), clamped; budget = per-task override ?? config
+ *     budget ?? tier base, clamped; timeout from the tier base, clamped.
+ */
+export declare function resolveBackgroundTaskEnvelope(input: ResolveEnvelopeInput): ResolveEnvelopeResult;
+export {};

package/dist/services/background-task/background-task-budget.js

@@ -0,0 +1,91 @@
+/**
+ * Background-task budget envelope — BACKGROUND_TASK_RUNNER_DESIGN.md §6 / §10.1.
+ *
+ * Pure resolution of the `(modelId, maxTurns, maxBudgetUsd,
+ * executeTimeoutMinutes)` envelope for a background-task worker from
+ * three inputs:
+ *
+ *   1. The per-task `tier` (`lite` | `medium` | `high`) — selects the
+ *      base turn/budget/timeout envelope.
+ *   2. The optional per-task `maxBudgetUsd` override (POST body).
+ *   3. The operator-editable `process_backend_config` row for
+ *      `process_key='background_task'` (model + caps) — same chokepoint
+ *      as browser-task's `loadBrowserTaskBackendBinding`.
+ *
+ * The worker is Claude-only (it drives the Claude Agent SDK `query()`
+ * loop directly, like browser_task). A `process_backend_config` row that
+ * pins a non-Claude backend is refused with `backend_misconfigured` so a
+ * mis-set `/settings/models` row fails fast rather than silently doing
+ * nothing.
+ *
+ * 100% coverage gate — the I/O (DB read) lives in
+ * `loadBackgroundTaskBinding`; this module is the pure arithmetic.
+ */
+/** Fallback model when the `process_backend_config` row is missing or
+ *  carries an empty `main_model`. Mirrors the seed default. */
+export const BACKGROUND_TASK_FALLBACK_CLAUDE_MODEL = "claude-sonnet-4-6";
+export const BACKGROUND_TASK_DEFAULT_TIER = "medium";
+/** Hard upper bounds. The seed sits well below; the caps give the
+ *  operator room to relax via `/settings/models` while pinning a ceiling
+ *  no per-task override can blow past. Background tasks are the
+ *  long-running surface, so the turn / timeout ceilings are far higher
+ *  than browser-task's (60 turns / 5 min) — a deep research or
+ *  multi-repo audit legitimately runs for many turns over many minutes. */
+export const BACKGROUND_TASK_MAX_TURNS_CAP = 120;
+export const BACKGROUND_TASK_MAX_BUDGET_USD_CAP = 15.0;
+export const BACKGROUND_TASK_MAX_EXECUTE_TIMEOUT_MINUTES = 120;
+/** Per-tier base envelope. `process_backend_config` overrides
+ *  model/turns/budget; the tier is the source of the execute-timeout
+ *  (which has no `process_backend_config` column) and the fallback when
+ *  the config row is absent. */
+const TIER_ENVELOPES = {
+    lite: { maxTurns: 15, maxBudgetUsd: 0.5, executeTimeoutMinutes: 10 },
+    medium: { maxTurns: 40, maxBudgetUsd: 2.0, executeTimeoutMinutes: 30 },
+    high: { maxTurns: 80, maxBudgetUsd: 8.0, executeTimeoutMinutes: 60 },
+};
+export function tierEnvelope(tier) {
+    return TIER_ENVELOPES[tier];
+}
+function clampPositive(value, cap, fallback) {
+    if (!Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.min(value, cap);
+}
+/**
+ * Pure envelope resolution. Branches:
+ *   - processConfig present + `mainBackend !== 'claude'` → REFUSE.
+ *   - otherwise: model from the config (or fallback); turns from the
+ *     config (or tier base), clamped; budget = per-task override ?? config
+ *     budget ?? tier base, clamped; timeout from the tier base, clamped.
+ */
+export function resolveBackgroundTaskEnvelope(input) {
+    const tier = input.tier ?? BACKGROUND_TASK_DEFAULT_TIER;
+    const base = TIER_ENVELOPES[tier];
+    const cfg = input.processConfig;
+    if (cfg && cfg.mainBackend !== "claude") {
+        return {
+            ok: false,
+            reason: "backend_misconfigured",
+            detail: `process_backend_config.main_backend='${cfg.mainBackend}' — background_task drives the Claude Agent SDK directly; refusing to dispatch. Set background_task back to claude in /settings/models.`,
+        };
+    }
+    const modelId = cfg && typeof cfg.mainModel === "string" && cfg.mainModel.length > 0
+        ? cfg.mainModel
+        : BACKGROUND_TASK_FALLBACK_CLAUDE_MODEL;
+    const rawTurns = cfg && typeof cfg.maxTurns === "number" && Number.isFinite(cfg.maxTurns)
+        ? Math.max(1, Math.floor(cfg.maxTurns))
+        : base.maxTurns;
+    const maxTurns = Math.min(rawTurns, BACKGROUND_TASK_MAX_TURNS_CAP);
+    // Per-task override wins, then the operator config, then the tier base.
+    const budgetSource = input.maxBudgetUsd != null
+        ? input.maxBudgetUsd
+        : cfg && cfg.maxBudgetUsd != null
+            ? cfg.maxBudgetUsd
+            : base.maxBudgetUsd;
+    const maxBudgetUsd = clampPositive(budgetSource, BACKGROUND_TASK_MAX_BUDGET_USD_CAP, base.maxBudgetUsd);
+    const executeTimeoutMinutes = Math.min(base.executeTimeoutMinutes, BACKGROUND_TASK_MAX_EXECUTE_TIMEOUT_MINUTES);
+    return {
+        ok: true,
+        envelope: { modelId, maxTurns, maxBudgetUsd, executeTimeoutMinutes },
+    };
+}

package/dist/services/background-task/background-task-driver.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Background-task driver — generic Claude Agent SDK glue for the
+ * per-task worker loop. BACKGROUND_TASK_RUNNER_DESIGN.md §4.1.
+ *
+ * The browser-task driver's analogue, with the entire Playwright /
+ * managed-Chromium / allowlist / final-confirm plane removed. A worker
+ * is a plain `query()` session seeded with a SELF-CONTAINED brief and a
+ * three-tool MCP envelope (`read_memory`, `ask_user`, `finish`) plus the
+ * SDK's `WebSearch` / `WebFetch` for research-type work. It opts out of
+ * the `<user>` / `<management_rules>` injection (`settingSources:
+ * ["project"]`, as browser-task does) — the brief carries the context,
+ * the output-language directive, persona hints for the `draft`, and the
+ * notification policy / criteria.
+ *
+ * Responsibilities:
+ *   1. Resolve the `(model, maxTurns, maxBudgetUsd, executeTimeout)`
+ *      envelope from `process_backend_config` + the row's tier/budget
+ *      (`background-task-budget.ts`), pinned for the task's lifetime.
+ *   2. Render a per-task workdir (empty dir + CLAUDE.md agent profile).
+ *   3. Drive `query()` until terminal, honouring the AbortController
+ *      (cancel + timeout) — no Playwright resources to release.
+ *   4. Hand back a `DriverRunResult` the runner maps to terminal state /
+ *      park. On the death paths the artifact is NULL — the runner
+ *      synthesizes the fail-loud artifact (§4.3).
+ *
+ * Excluded from the 100% coverage gate — SDK stream consumer. The pure
+ * sub-pieces (budget envelope) live in the covered set.
+ */
+import type Database from "better-sqlite3";
+import { type BackgroundTaskRow } from "../../db/background-task-store.js";
+import { type BackgroundTaskEnvelope, type BackgroundTaskProcessConfig } from "./background-task-budget.js";
+import { type BackgroundTaskRuntime } from "./background-task-tools.js";
+import { type BackgroundTaskTransitionEmitter } from "./background-task-transition-events.js";
+/** Read the operator-editable envelope row for `background_task`. */
+export declare function loadBackgroundTaskProcessConfig(db: Database.Database): BackgroundTaskProcessConfig | null;
+export interface DriverDeps {
+    db: Database.Database;
+    paDataDir: string;
+    /** Workspace dir root — resolves the agent-profile MD. */
+    workspaceDir: string;
+    transitionEmitter?: BackgroundTaskTransitionEmitter;
+    /** Vault root for the worker's `read_memory` tool. */
+    contextDir: string;
+    /** Clarification TTL in ms (`backgroundTaskClarificationTtlMinutes`). */
+    clarificationTtlMs: number;
+    /** Override for tests; production wires `() => Date.now()`. */
+    nowFn?: () => number;
+}
+export interface DriverHandle {
+    abortController: AbortController;
+    cwd: string;
+    runtime: BackgroundTaskRuntime;
+    sdkSessionId: string | null;
+    binding: BackgroundTaskEnvelope;
+}
+export interface DriverRunResult {
+    outcome: "completed" | "yielded_for_clarification" | "no_finish" | "max_turns_exceeded" | "budget_exceeded" | "timeout" | "cancelled" | "sdk_error" | "resume_unavailable" | "backend_misconfigured";
+    sdkSessionId: string | null;
+    detail?: string | null;
+    costUsd: number;
+    numTurns: number;
+    durationMs: number;
+}
+/**
+ * Acquire a fresh workdir + runtime + binding for `row`. The runner
+ * calls this BEFORE `runDriver` so it can stash the handle in its parked
+ * map before any turn fires (an ask_user on the first turn must find the
+ * handle already there).
+ */
+export declare function prepareDriverHandle(input: {
+    deps: DriverDeps;
+    row: BackgroundTaskRow;
+}): Promise<{
+    ok: true;
+    handle: DriverHandle;
+} | {
+    ok: false;
+    reason: DriverRunResult["outcome"];
+    detail?: string;
+}>;
+/** Drive the initial turn — the worker reads the brief and works. */
+export declare function runDriver(deps: DriverDeps, row: BackgroundTaskRow, handle: DriverHandle): Promise<DriverRunResult>;
+/** Resume a parked task after `/clarify` lands the owner's answer. Uses
+ *  the persisted SDK session id so the prompt cache stays warm. Works both
+ *  in-process (warm parked handle) and across a daemon restart (the runner
+ *  reconstructs the handle from the persisted `backend_session_id`); in the
+ *  cross-restart case a session the SDK can no longer load surfaces as
+ *  `resume_unavailable`. */
+export declare function resumeDriver(deps: DriverDeps, row: BackgroundTaskRow, handle: DriverHandle, userAnswer: string): Promise<DriverRunResult>;
+/**
+ * BACKGROUND_TASK_RUNNER_DESIGN.md §10.2 / Phase 4 — resume a task that was
+ * mid-execution when the daemon restarted, using the persisted SDK session
+ * id (`backend_session_id`) so the warm transcript + prompt cache survive
+ * the restart instead of re-running the brief from scratch. The runner
+ * reconstructs the handle (`prepareDriverHandle` recreates the per-task
+ * workdir + sets `sdkSessionId` from the row). When the SDK can no longer
+ * load the session, this returns `resume_unavailable` and the runner falls
+ * back to re-dispatch-from-brief — so resume is a pure optimization with no
+ * regression.
+ */
+export declare function resumeFromBootDriver(deps: DriverDeps, row: BackgroundTaskRow, handle: DriverHandle): Promise<DriverRunResult>;
+/** Remove the per-task workdir. Idempotent. Parked tasks (awaiting_user)
+ *  do NOT call this — the runner keeps the handle in its parked map so
+ *  /clarify can resume the warm SDK session. */
+export declare function releaseDriverHandle(deps: DriverDeps, handle: DriverHandle): Promise<void>;