@aitne/daemon 0.1.9 → 0.1.11

package/dist/safety/risk-classifier.js

@@ -285,6 +285,30 @@ const API_RISK = {
     "GET /api/browser-task/{*}/screenshots/{*}": RiskTier.ReadSensitive,
     "POST /api/browser-task/{*}/clarify": RiskTier.Autonomous,
     "POST /api/browser-task/{*}/cancel": RiskTier.Autonomous,
+    // ── Background Task (BACKGROUND_TASK_RUNNER_DESIGN.md §7) ──
+    // Generic detached long-task surface, cloned from browser-task and
+    // classified to the same posture. The only production callers are the
+    // DM-agent `background-task` / `background-task-reply` skills and the
+    // morning-briefing session, whose curl shim carries `x-read-token`
+    // (sufficient for ReadSensitive, never enough for Approve). The same
+    // loopback / sec-fetch / channel-attestation defenses as browser-task
+    // apply, and every dispatched task surfaces to the user via DM — no
+    // covert dispatch path.
+    //   - POST (spawn) + clarify + cancel are Autonomous, matching the
+    //     sibling agent-driven write paths (design §7: "same posture as
+    //     /api/browser-task").
+    //   - The list + detail reads stay ReadSensitive (NOT Autonomous):
+    //     the artifact (`report` / `brief` / `draft` / `significance`)
+    //     carries personal research / audit content, exactly the reason
+    //     browser-task's reads are ReadSensitive. Reachable from the agent
+    //     sessions that need them because their curl carries the read
+    //     token (cf. GET /api/observations, also ReadSensitive, which the
+    //     briefing already calls).
+    "POST /api/background-task": RiskTier.Autonomous,
+    "GET /api/background-task": RiskTier.ReadSensitive,
+    "GET /api/background-task/{*}": RiskTier.ReadSensitive,
+    "POST /api/background-task/{*}/clarify": RiskTier.Autonomous,
+    "POST /api/background-task/{*}/cancel": RiskTier.Autonomous,
     "/api/setup": RiskTier.Approve,
     "POST /api/setup/redetect-browsers": RiskTier.Approve,
     // Management Mode Phase 2 — migration endpoint. Redundant with the
@@ -451,6 +475,22 @@ const API_RISK = {
     "PUT /api/observations/{*}/consume": RiskTier.Autonomous,
     "PATCH /api/observations/{*}/consume": RiskTier.Autonomous,
     "DELETE /api/observations/{*}/consume": RiskTier.Autonomous,
+    "POST /api/feedback": RiskTier.Autonomous,
+    "POST /api/feedback/consume": RiskTier.Autonomous,
+    // Read-only lesson-store overview for the dashboard Lessons settings page
+    // (FEEDBACK_LEARNING_LOOP_DESIGN.md §9 Phase 5). Summarises cap utilisation
+    // only — lesson prose was redaction-scrubbed at capture — so Autonomous.
+    "GET /api/feedback/lessons": RiskTier.Autonomous,
+    // Self-tuning verdict endpoint (SELF_TUNING_REVIEW_CYCLE_DESIGN.md §3.4).
+    // Autonomous + (Phase 3) mandatory owner DM on apply — the exact pattern
+    // that replaced the abolished Notify tier; requiring the Approve bearer
+    // would put a human back in every loop iteration and defeat the design.
+    // Safety is carried by code, not tier: verdicts may only reference
+    // daemon-generated single-use recommendation ids from the current cycle,
+    // the handler is idempotent per id, and Phase 2 never actuates (shadow).
+    "POST /api/tuning/verdicts": RiskTier.Autonomous,
+    // Pending-cycle read — knob names + telemetry counts only, no user prose.
+    "GET /api/tuning/pending": RiskTier.Autonomous,
     // ── Notification ──
     "/api/notify": RiskTier.Autonomous,
     // ── External Service Proxy ──
@@ -662,7 +702,7 @@ const API_RISK = {
     "PATCH /api/delegated-sync/active-hours": RiskTier.Approve,
     "POST /api/delegated-sync/cadences/": RiskTier.Approve,
     // INTEGRATION-DRIFT-DETECTION-PLAN.md §6.0 — drift-detection chokepoint.
-    // Autonomous: the agent's hourly_check delegated variant POSTs the
+    // Autonomous: the agent's activity_scan delegated variant POSTs the
     // result of its connector fetch to compute a structural diff. Defense
     // layers (window-key allowlist + per-call audit row) live inside the
     // handler. Daemon-internal callers (CalendarPoller, DelegatedSyncWorker)
@@ -797,13 +837,22 @@ const API_RISK = {
     "GET /api/skill-curation/signals": RiskTier.Autonomous,
     "GET /api/skill-curation/knowledge-map": RiskTier.Autonomous,
     "GET /api/skill-curation/proposals/": RiskTier.Autonomous,
-    // Mutation endpoints are Autonomous — the optimizer agent's runToken
-    // (HMAC, one-time, scoped to a single run) is the auth surface, enforced
-    // inside the route. Per design §2.1 the chokepoint applies every passing
-    // proposal atomically; there are no per-proposal approve/reject/revert
-    // routes. The only roll-back path is the system-driven auto-revert
-    // (`auto-revert.ts`), which never crosses the HTTP boundary.
-    "POST /api/skill-curation/runs": RiskTier.Autonomous,
+    // Run minting (`POST /runs`, exact) is Approve. In production this surface
+    // is unused — the dispatcher's `materializeOptimizerWorkdir` mints the
+    // runId/runToken directly and never crosses the HTTP boundary (see the
+    // route handler comment). Leaving it Autonomous let any Bearer-less local
+    // caller (incl. a prompt-injected DM agent) mint a valid optimizer token
+    // once curation is opted in, then drive `/proposals` to self-author skill
+    // overlays — a least-privilege violation. Approve confines minting to the
+    // dashboard/operator; the legitimate optimizer reads its token from the
+    // workdir preamble, not this route.
+    "POST /api/skill-curation/runs": RiskTier.Approve,
+    // The proposal chokepoint and the per-run finalize stay Autonomous — both
+    // are gated by the optimizer's runToken (HMAC, scoped to a single run)
+    // enforced inside the route, and the legitimate optimizer agent reaches
+    // them via curl from its session workdir (no Bearer). Per design §2.1 the
+    // chokepoint applies every passing proposal atomically; the only roll-back
+    // path is the system-driven auto-revert (`auto-revert.ts`).
     "POST /api/skill-curation/proposals": RiskTier.Autonomous,
     "POST /api/skill-curation/runs/": RiskTier.Autonomous,
     // P22 §6.1 — settings + listing surfaces consumed by the dashboard.
@@ -878,9 +927,14 @@ export function findExplicitRiskClassification(method, path) {
         /* c8 ignore stop */
         if (keyMethod && keyMethod !== method)
             return false;
-        return path.startsWith(keyPath);
+        return pathPrefixMatches(keyPath, path);
     })
-        .sort((a, b) => b[0].length - a[0].length);
+        // Rank by matched path-prefix length so the most-specific prefix wins.
+        // Must compare the path segment, NOT the raw key: the `"METHOD "` token
+        // would otherwise lift a shorter, less-specific method-keyed prefix
+        // (e.g. `DELETE /api/git`) above a longer path-only one (`/api/github`),
+        // silently downgrading the tier. Mirrors the step-3 pattern tiebreaker.
+        .sort((a, b) => keyPathOf(b[0]).length - keyPathOf(a[0]).length);
     if (candidates.length > 0)
         return candidates[0][1];
     return null;
@@ -960,16 +1014,41 @@ function matchesPattern(keyPath, actualPath) {
     }
     return true;
 }
-/** Count characters before the first `{*}` (or whole length if none) —
- *  used to rank pattern candidates by specificity. Defensive against future
- *  overlapping `{*}` keys: today no two `{*}` entries in `API_RISK` match
- *  the same `(method, path)` pair, so the sort comparator never invokes
- *  this helper. The function exists so the first overlapping pair added
- *  picks the more specific entry instead of relying on iteration order. */
+/** Extract the path portion of an `API_RISK` key: `"METHOD /path"` → `/path`,
+ *  or a bare `"/path"` path-only key unchanged. Ranking must compare the path
+ *  segment alone — the leading `"METHOD "` token (3–6 chars) would otherwise
+ *  inflate a shorter, less-specific method-keyed prefix above a longer
+ *  path-only one. */
+export function keyPathOf(key) {
+    return key.includes(" ") ? key.split(" ")[1] : key;
+}
+/** Segment-aware prefix test for step-4 (non-`{*}`) keys. A raw
+ *  `path.startsWith(keyPath)` matches a *string* prefix, so `/api/git`
+ *  would spuriously match the unrelated sibling `/api/git-accounts` (and,
+ *  worse, an unclassified future `/api/git-webhook` — silently inheriting
+ *  the sibling's tier instead of failing closed to Approve). A key that
+ *  ends in `/` is an explicit subtree catch-all, so a raw `startsWith` is
+ *  already the boundary; otherwise the match must be a strict
+ *  `/`-delimited descendant. Exact `path === keyPath` is pre-empted by the
+ *  step-1/step-2 exact lookups, so step 4 only ever matches descendants.
+ *  Mirrors the segment discipline of `matchesPattern` (step 3). */
+function pathPrefixMatches(keyPath, path) {
+    if (keyPath.endsWith("/"))
+        return path.startsWith(keyPath);
+    return path.startsWith(keyPath + "/");
+}
+/** Count characters of the path prefix before the first `{*}` (or the whole
+ *  path length if none) — used to rank pattern candidates by specificity.
+ *  Defensive against future overlapping `{*}` keys: today no two `{*}` entries
+ *  in `API_RISK` match the same `(method, path)` pair, so the sort comparator
+ *  never invokes this helper. The function exists so the first overlapping
+ *  pair added picks the more specific entry instead of relying on iteration
+ *  order. */
 /* c8 ignore start */
 function literalPrefixLength(key) {
-    const idx = key.indexOf("{*}");
-    return idx < 0 ? key.length : idx;
+    const keyPath = keyPathOf(key);
+    const idx = keyPath.indexOf("{*}");
+    return idx < 0 ? keyPath.length : idx;
 }
 /* c8 ignore stop */
 /** Strip a trailing `{*}` placeholder from `path` so callers can

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