@aitne/daemon 0.1.8 → 0.1.9

package/dist/api/routes/agents/views.js

@@ -0,0 +1,514 @@
+import { AGENT_TIERS, OVERRIDE_EDIT_PATHS, agentDefinitionSchema, recurrenceRuleSchema } from "@aitne/shared";
+import { recurrenceRuleToCron } from "../../../core/agents/recurrence-convert.js";
+import { renderAgentMarkdown } from "../../../core/agents/agent-frontmatter.js";
+/**
+ * Pure response shapers + mutation planners for the `/api/agents` routes
+ * (AGENT_DEFINITIONS_DESIGN.md §9). The Hono handlers in `index.ts` stay thin —
+ * fetch rows, call these, `c.json(...)`. Keeping the JSON-shape + validation
+ * logic here (no DB / fs / Hono) puts it in the 100%-coverage set; the route
+ * file is the I/O-shaped glue (auto-excluded as an `index.ts`).
+ */
+// ── Timestamp serialization ─────────────────────────────────────────────────
+/** epoch-ms → ISO-8601, null-safe (execution timestamps are epoch-ms, §5.2). */
+export function epochToIso(ms) {
+    return ms === null ? null : new Date(ms).toISOString();
+}
+// ── Execution serialization ─────────────────────────────────────────────────
+/** Full execution row for the detail / executions endpoints (§9.2 / §9.3). */
+export function serializeExecution(e) {
+    return {
+        id: e.id,
+        agent_id: e.agentId,
+        schedule_row_id: e.scheduleRowId,
+        trigger: e.trigger,
+        started_at: epochToIso(e.startedAt),
+        ended_at: epochToIso(e.endedAt),
+        result: e.result,
+        error_kind: e.errorKind,
+        error_message: e.errorMessage,
+        cost_usd: e.costUsd,
+        tokens_input: e.tokensInput,
+        tokens_output: e.tokensOutput,
+        turns: e.turns,
+        success_criteria: e.successCriteria,
+        output_summary: e.outputSummary,
+    };
+}
+/** Slim last-execution summary for the list view (§9.1). */
+export function serializeLastExecution(e) {
+    if (e === null)
+        return null;
+    return {
+        id: e.id,
+        started_at: epochToIso(e.startedAt),
+        ended_at: epochToIso(e.endedAt),
+        result: e.result,
+        cost_usd: e.costUsd,
+        output_summary: e.outputSummary,
+    };
+}
+// ── Metrics serialization ───────────────────────────────────────────────────
+/** Full metric window incl. p95 for the detail view (§9.2). */
+export function serializeMetricsWindow(w) {
+    return {
+        executions: w.executions,
+        error_rate: w.errorRate,
+        avg_cost_usd: w.avgCostUsd,
+        p95_duration_seconds: w.p95DurationSeconds,
+        criteria_hit_rate: w.criteriaHitRate,
+    };
+}
+/** Compact metric window (no p95) for the list view (§9.1). */
+export function serializeListMetrics(w) {
+    return {
+        executions: w.executions,
+        error_rate: w.errorRate,
+        avg_cost_usd: w.avgCostUsd,
+        criteria_hit_rate: w.criteriaHitRate,
+    };
+}
+/** One row of `GET /api/agents` (§9.1). `kind` mirrors the stored `source`. */
+export function buildListItem(dto, inputs) {
+    // Read the parse-error into a camelCase local + emit it via the object-literal
+    // (colon) form. The redaction static guard (check-redaction-coverage.mjs)
+    // flags the auth-health JSON key name whenever it is immediately followed by
+    // an equals sign — which also catches a strict-equality comparison — so we
+    // never write that key adjacent to `=`. This value is an Agent-definition
+    // parse error (§6.6), never a secret. Mirrors the agents-store.ts /
+    // loader.ts dodge. Surfaced only for invalid rows.
+    const parseError = dto.metadata.last_error;
+    const surfaceError = dto.invalid && typeof parseError === "string";
+    return {
+        slug: dto.slug,
+        name: dto.name,
+        // Coalesce to "" so the daemon honours the dashboard's non-null
+        // `description` contract. An invalid row may carry a null description; its
+        // real failure is surfaced separately via `last_error` below, so an empty
+        // string here loses no information (a valid/fallback row always has one).
+        description: dto.description ?? "",
+        kind: dto.source,
+        enabled: dto.enabled,
+        tags: dto.tags,
+        schedule: {
+            kind: dto.scheduleKind,
+            expression: dto.scheduleExpression,
+            timezone: dto.scheduleTimezone,
+            interval: inputs.intervalCadence ?? null,
+        },
+        process_key: dto.processKey,
+        last_execution: serializeLastExecution(inputs.lastExecution),
+        metrics_7d: serializeListMetrics(inputs.metrics7d),
+        stop_warning: dto.stopWarning,
+        invalid: dto.invalid,
+        ...(surfaceError ? { last_error: parseError } : {}),
+    };
+}
+// ── Detail row + envelope (§9.2) ────────────────────────────────────────────
+/**
+ * snake_case projection of the stored DB columns for the detail `row` block.
+ * `intervalCadence` (resolved by the route from live config) is surfaced as
+ * `schedule_interval` so the detail view renders the real runtime-window
+ * cadence; `null` for fixed-cron / one-shot / event Agents (§5.5.1).
+ */
+export function buildRow(dto, intervalCadence = null) {
+    return {
+        slug: dto.slug,
+        name: dto.name,
+        // Coalesce to "" so the detail `row` block matches the dashboard's non-null
+        // `description` type (mirrors buildListItem); invalid rows surface their
+        // failure via the envelope's separate error field, not this column.
+        description: dto.description ?? "",
+        source: dto.source,
+        definition_path: dto.definitionPath,
+        definition_hash: dto.definitionHash,
+        enabled: dto.enabled,
+        enabled_overridden_at: dto.enabledOverriddenAt,
+        process_key: dto.processKey,
+        schedule_kind: dto.scheduleKind,
+        schedule_expression: dto.scheduleExpression,
+        schedule_timezone: dto.scheduleTimezone,
+        schedule_interval: intervalCadence,
+        tags: dto.tags,
+        stop_warning: dto.stopWarning,
+        recurring_schedule_id: dto.recurringScheduleId,
+        last_execution_id: dto.lastExecutionId,
+        version_counter: typeof dto.metadata.version_counter === "number"
+            ? dto.metadata.version_counter
+            : null,
+        override_snapshot: dto.metadata.override_snapshot ?? null,
+        invalid: dto.invalid,
+        created_at: dto.createdAt,
+        updated_at: dto.updatedAt,
+    };
+}
+/** Full `GET /api/agents/:slug` envelope (§9.2). */
+export function buildDetail(inputs) {
+    return {
+        agent: inputs.definition,
+        row: buildRow(inputs.dto, inputs.intervalCadence ?? null),
+        recent_executions: inputs.recentExecutions.map(serializeExecution),
+        metrics: {
+            "7d": serializeMetricsWindow(inputs.metrics7d),
+            "30d": serializeMetricsWindow(inputs.metrics30d),
+            by_error_kind_7d: inputs.byErrorKind7d,
+        },
+        definition_yaml: inputs.definitionYaml,
+        definition_path: inputs.dto.definitionPath,
+    };
+}
+/**
+ * Plan a manual run (§9.4): produce the `agent_schedule` insert payload. The
+ * owning Agent is stamped into `task_context.agent_id` (resolver step 1, §8.1)
+ * so the execution is attributed regardless of which dispatch flow runs;
+ * built-in routine Agents additionally carry `task_context.routine` (+ phase
+ * for the two sweeps) so the dispatcher's routine special-cases fire the real
+ * flow where it supports them.
+ *
+ * Rejects (409) the no-LLM in-process passes (`process_key: null`) — they fire
+ * via the scheduler's in-process callback, not the `agent_schedule` queue — and
+ * any row currently flagged invalid.
+ */
+export function planRunNow(dto, opts = {}) {
+    if (dto.invalid) {
+        return {
+            ok: false,
+            status: 409,
+            error: "agent_invalid",
+            hint: "This Agent's definition failed to load — fix the agent.md before running it.",
+        };
+    }
+    if (dto.processKey === null) {
+        return {
+            ok: false,
+            status: 409,
+            error: "agent_not_runnable",
+            hint: "This built-in is a no-LLM in-process pass with no routing key; it is fired by the scheduler, not run-now.",
+        };
+    }
+    const taskContext = {
+        agent_id: dto.slug,
+        trigger: "manual",
+        processKey: dto.processKey,
+        importance: "normal",
+    };
+    if (dto.source === "builtin" && dto.processKey.startsWith("routine.")) {
+        taskContext.routine = dto.processKey.slice("routine.".length);
+        const phase = sweepPhaseFromSlug(dto.slug);
+        if (phase !== null)
+            taskContext.phase = phase;
+    }
+    // §9.4 optional `trigger_note`: stamp it into the schedule row's context so
+    // the operator's reason rides along with the run and is auditable. Only
+    // present when supplied (the dashboard's no-note call leaves it absent).
+    if (opts.triggerNote !== undefined) {
+        taskContext.trigger_note = opts.triggerNote;
+    }
+    return {
+        ok: true,
+        taskType: dto.processKey,
+        taskDescription: dto.name,
+        // Built-ins drive their prompt from the routine/process key; user Agents
+        // carry the recurring row's prompt so the manual run does the real task.
+        taskPrompt: dto.source === "user" ? opts.taskPrompt ?? null : null,
+        taskContext,
+        // Routing pins ride along ONLY for user Agents — mirrors the cron path
+        // (`generateNextScheduleRow` copies the recurring row's backend_id / model /
+        // tier_override). Built-ins resolve their backend from the process key, so a
+        // pin must never leak onto a built-in's manual run.
+        backendId: dto.source === "user" ? opts.backendId ?? null : null,
+        model: dto.source === "user" ? opts.model ?? null : null,
+        tier: dto.source === "user" ? opts.tier ?? null : null,
+        emitDm: dto.source === "builtin",
+    };
+}
+/** `user-profile-sweep-{morning,evening}` → its phase; null for every other slug. */
+function sweepPhaseFromSlug(slug) {
+    if (slug.endsWith("-evening"))
+        return "evening";
+    if (slug.endsWith("-morning"))
+        return "morning";
+    return null;
+}
+function asString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function asRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+/**
+ * Plan a `POST /api/agents` create from a structured JSON body — the
+ * programmatic counterpart to the dashboard's "+ New Agent" form (which writes
+ * the same `agent.md` via the context-vault PUT). Pure: assembles the
+ * frontmatter, validates it through `agentDefinitionSchema`, enforces the
+ * recurring-only contract, checks slug uniqueness, and renders the `agent.md`
+ * the route then writes. No DB / fs / Hono — fully unit-testable to 100%.
+ *
+ * `/agents` is recurring-only. The caller picks ONE of two schedule input forms:
+ *   - `{ kind: "cron", expression }` — a 5-field cron (incl. hourly `M * * * *`
+ *     / `M *​/N * * *`, now that the loader pairs those).
+ *   - `{ kind: "recurring", recurrence: <recurrenceRule> }` — the structured
+ *     frequency form (`hourly`/`daily`/`weekly`/`monthly` + its fields), the
+ *     clear path the dashboard + agent-create skill use. It is rendered to the
+ *     canonical cron here so the stored `agent.md` stays cron-based and
+ *     round-trips through the loader's recurring pairing.
+ * Any other `schedule.kind` (one_shot/event) is rejected with a pointer at the
+ * `/schedule` queue. `backend.process_key` defaults to `agent.task` (user
+ * recurring Agents always run an LLM turn) so the caller need not know the key.
+ */
+export function planCreate(body, existingSlugs) {
+    const slug = asString(body.slug);
+    if (slug === undefined || slug.length === 0) {
+        return { ok: false, status: 400, error: "slug_required", field: "slug" };
+    }
+    const name = asString(body.name);
+    if (name === undefined || name.length === 0) {
+        return { ok: false, status: 400, error: "name_required", field: "name" };
+    }
+    const schedule = asRecord(body.schedule);
+    if (schedule === undefined) {
+        return { ok: false, status: 400, error: "schedule_required", field: "schedule" };
+    }
+    // Resolve either input form into the canonical cron schedule the frontmatter
+    // stores. A structured `recurrence` is validated + rendered to cron; a raw
+    // cron passes through; anything else is rejected before schema parsing so the
+    // caller gets the actionable pointer regardless of the wrong-kind fields.
+    const scheduleKind = asString(schedule.kind);
+    let scheduleFrontmatter;
+    if (scheduleKind === "recurring") {
+        const parsedRule = recurrenceRuleSchema.safeParse(schedule.recurrence);
+        if (!parsedRule.success) {
+            const issues = parsedRule.error.issues.map((i) => ({
+                field: `schedule.recurrence.${i.path.join(".")}`,
+                message: i.message,
+            }));
+            return {
+                ok: false,
+                status: 400,
+                error: "invalid_recurrence",
+                hint: "schedule.recurrence must be a valid recurrence rule: frequency hourly/daily/weekly/monthly plus its fields (hourly→intervalHours/minuteOfHour, daily/weekly/monthly→time, weekly→daysOfWeek, monthly→daysOfMonth).",
+                issues,
+            };
+        }
+        const timezone = asString(schedule.timezone) ?? parsedRule.data.timezone;
+        scheduleFrontmatter = {
+            kind: "cron",
+            expression: recurrenceRuleToCron(parsedRule.data),
+            ...(timezone !== undefined ? { timezone } : {}),
+        };
+    }
+    else if (scheduleKind === "cron") {
+        scheduleFrontmatter = schedule;
+    }
+    else {
+        return {
+            ok: false,
+            status: 400,
+            error: "one_shot_not_supported",
+            field: "schedule.kind",
+            hint: "/agents is recurring-only. Use schedule.kind \"cron\" or \"recurring\"; for one-time tasks use POST /api/schedule.",
+        };
+    }
+    // Slug uniqueness (covers built-in slugs too — they're rows in `agents`).
+    if (existingSlugs.has(slug)) {
+        return { ok: false, status: 409, error: "slug_collision", slug };
+    }
+    // Assemble the agent.md frontmatter from the input. `kind` is forced to
+    // "user"; `backend.process_key` defaults to the user-recurring routing key;
+    // `limits` is always present (the schema has no object-level default).
+    const inputBackend = asRecord(body.backend) ?? {};
+    const backend = { ...inputBackend };
+    if (backend.process_key === undefined)
+        backend.process_key = "agent.task";
+    const frontmatter = {
+        slug,
+        name,
+        ...(body.description !== undefined ? { description: body.description } : {}),
+        kind: "user",
+        ...(body.enabled !== undefined ? { enabled: body.enabled } : {}),
+        schedule: scheduleFrontmatter,
+        backend,
+        limits: asRecord(body.limits) ?? {},
+        ...(body.tools !== undefined ? { tools: body.tools } : {}),
+        ...(body.on_error !== undefined ? { on_error: body.on_error } : {}),
+        ...(body.tags !== undefined ? { tags: body.tags } : {}),
+        ...(body.outputs !== undefined ? { outputs: body.outputs } : {}),
+        ...(body.success_criteria !== undefined
+            ? { success_criteria: body.success_criteria }
+            : {}),
+    };
+    const parsed = agentDefinitionSchema.safeParse(frontmatter);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => ({
+            // `agentDefinitionSchema`'s field + superRefine issues always carry a
+            // path (backend.process_key, stop_warning, success_criteria[i].id, …);
+            // an empty path joins to "" which the caller surfaces verbatim.
+            field: i.path.join("."),
+            message: i.message,
+        }));
+        return {
+            ok: false,
+            status: 400,
+            error: "invalid_definition",
+            hint: "The assembled agent.md failed schema validation; fix the reported fields.",
+            issues,
+        };
+    }
+    const prompt = asString(body.prompt) ?? "";
+    return { ok: true, slug, markdown: renderAgentMarkdown(frontmatter, prompt) };
+}
+// ── PATCH plan (§9.5) ────────────────────────────────────────────────────────
+// The built-in override allow-list is the shared `OVERRIDE_EDIT_PATHS` single
+// source of truth (== `MERGEABLE_OVERRIDE_PATHS` minus the two `enabled*` keys;
+// `enabled` is the `agents.enabled` column's authority, §6.4, toggled
+// separately and never an override-snapshot value). Re-exported so existing
+// `views.OVERRIDE_EDIT_PATHS` importers keep working.
+export { OVERRIDE_EDIT_PATHS };
+/**
+ * Parent block → its editable leaf keys (everything else under it is read-only).
+ * Derived structurally from the shared `OVERRIDE_EDIT_PATHS` so this PATCH edit
+ * gate — the fourth consumer of the allow-list — can never omit a path a future
+ * 7th entry adds. Same `{backend:{tier,model}, limits:{…}, on_error:{…}}` shape
+ * as before; pinned by a drift-guard test against `OVERRIDE_EDIT_PATHS`.
+ */
+export const EDITABLE_NESTED = (() => {
+    const acc = {};
+    for (const path of OVERRIDE_EDIT_PATHS) {
+        const dot = path.indexOf(".");
+        const parent = path.slice(0, dot);
+        const leaf = path.slice(dot + 1);
+        (acc[parent] ??= new Set()).add(leaf);
+    }
+    return acc;
+})();
+const CONTROL_KEYS = new Set(["enabled", "ack_warning", "reset"]);
+function isAgentTier(v) {
+    return typeof v === "string" && AGENT_TIERS.includes(v);
+}
+function isPositiveInt(v) {
+    return typeof v === "number" && Number.isInteger(v) && v > 0;
+}
+function isNonNegativeFinite(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0;
+}
+/** Validate an override-edit value against the same contract the schema enforces. */
+function isValidOverrideValue(path, value) {
+    switch (path) {
+        case "backend.tier":
+            return value === null || isAgentTier(value);
+        case "backend.model":
+            return value === null || (typeof value === "string" && value.length > 0);
+        case "limits.max_turns":
+        case "limits.timeout_minutes":
+            return isPositiveInt(value);
+        case "limits.max_budget_usd":
+            return isNonNegativeFinite(value);
+        case "on_error.notify_owner":
+            return typeof value === "boolean";
+    }
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Plan a `PATCH /api/agents/:slug` (§9.5). Splits the body into:
+ *   - an `enabled` toggle (column authority; built-in disable needs `ack_warning`);
+ *   - built-in override-snapshot field edits (validated against the schema);
+ *   - override `reset` of those same fields;
+ * and reports every read-only / unknown key it ignored under `stripped`.
+ *
+ * User Agents may only toggle `enabled` here — field edits go through the
+ * `agent.md` file (the dashboard editor → context-vault PATCH path, §9.5), so a
+ * field-edit / reset on a user Agent is rejected with a pointer.
+ */
+export function planPatch(dto, body) {
+    // ── enabled toggle ──
+    let setEnabled;
+    if ("enabled" in body) {
+        if (typeof body.enabled !== "boolean") {
+            return { ok: false, status: 400, error: "invalid_enabled", field: "enabled" };
+        }
+        // Only a real ON↔OFF transition is a change (design §12.2 gates on
+        // `body.enabled !== agent.enabled`). Re-disabling an already-stopped
+        // built-in must NOT demand a fresh stop-warning ack (the spurious 409
+        // below), and a same-state toggle must not re-stamp `enabled_overridden_at`
+        // / re-emit SSE / re-audit. A no-op `enabled` leaves `setEnabled` undefined
+        // so the rest of the plan (override edits) still applies.
+        if (body.enabled !== dto.enabled) {
+            setEnabled = body.enabled;
+        }
+    }
+    const ackWarning = body.ack_warning === true;
+    if (setEnabled === false && dto.source === "builtin" && !ackWarning) {
+        return { ok: false, status: 409, error: "stop_warning_required", warning: dto.stopWarning };
+    }
+    // ── collect override edits + stripped read-only keys ──
+    const edits = [];
+    const stripped = [];
+    for (const [key, value] of Object.entries(body)) {
+        if (CONTROL_KEYS.has(key))
+            continue;
+        const editable = EDITABLE_NESTED[key];
+        if (editable) {
+            if (!isPlainObject(value)) {
+                stripped.push(key);
+                continue;
+            }
+            for (const [subKey, subValue] of Object.entries(value)) {
+                const path = `${key}.${subKey}`;
+                if (editable.has(subKey)) {
+                    edits.push({ path: path, value: subValue });
+                }
+                else {
+                    stripped.push(path);
+                }
+            }
+        }
+        else {
+            // Top-level read-only field (slug / kind / process_key / schedule / …).
+            stripped.push(key);
+        }
+    }
+    // ── reset list ──
+    let reset = [];
+    if ("reset" in body) {
+        if (!Array.isArray(body.reset) || body.reset.some((p) => typeof p !== "string")) {
+            return { ok: false, status: 400, error: "invalid_reset", field: "reset" };
+        }
+        reset = body.reset;
+        for (const path of reset) {
+            if (!OVERRIDE_EDIT_PATHS.includes(path)) {
+                return { ok: false, status: 400, error: "invalid_reset_path", field: path };
+            }
+        }
+    }
+    // ── user Agents: only enabled is editable via this endpoint ──
+    if (dto.source === "user" && (edits.length > 0 || reset.length > 0)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "user_agent_edit_via_file",
+            hint: `Edit user Agent fields via PATCH /api/context/policies/agents/${dto.slug}/agent.md, not this endpoint.`,
+        };
+    }
+    // ── validate built-in override edits ──
+    const overrideSet = {};
+    for (const { path, value } of edits) {
+        if (!isValidOverrideValue(path, value)) {
+            return { ok: false, status: 400, error: "invalid_field_value", field: path };
+        }
+        overrideSet[path] = value;
+    }
+    const plan = {
+        ok: true,
+        overrideSet,
+        overrideReset: reset,
+        stripped,
+        ...(setEnabled !== undefined ? { setEnabled } : {}),
+    };
+    if (dto.source === "user" && setEnabled !== undefined && dto.recurringScheduleId !== null) {
+        plan.mirrorRecurringEnabled = setEnabled;
+    }
+    return plan;
+}

package/dist/api/routes/apple-calendar.d.ts

@@ -22,10 +22,9 @@ export interface AppleCalendarRouteDependencies {
  * DELETE /apple-calendar/credentials         — disconnect
  * POST   /apple-calendar/default-calendar    — pick which calendar is primary
  *
- * The skill body routes the agent here when `rules/management.md` Source
+ * The skill body routes the agent here when `policies/management.md` Source
  * of Truth declares Apple Calendar as the schedule provider. The agent
  * MUST NOT cross-call `/api/calendar/*`; that would query Google and
  * silently return wrong data, which is worse than an error.
  */
 export declare function createAppleCalendarRoutes(deps: AppleCalendarRouteDependencies): Hono;
-//# sourceMappingURL=apple-calendar.d.ts.map

package/dist/api/routes/apple-calendar.js

@@ -67,7 +67,7 @@ const appleUpdateEventSchema = z
  * DELETE /apple-calendar/credentials         — disconnect
  * POST   /apple-calendar/default-calendar    — pick which calendar is primary
  *
- * The skill body routes the agent here when `rules/management.md` Source
+ * The skill body routes the agent here when `policies/management.md` Source
  * of Truth declares Apple Calendar as the schedule provider. The agent
  * MUST NOT cross-call `/api/calendar/*`; that would query Google and
  * silently return wrong data, which is worse than an error.
@@ -389,4 +389,3 @@ export function createAppleCalendarRoutes(deps) {
     });
     return app;
 }
-//# sourceMappingURL=apple-calendar.js.map

package/dist/api/routes/attachments.d.ts

@@ -33,4 +33,3 @@ export declare const ATTACHMENT_LIMITS: {
 };
 /** Test-only: reset the in-flight counter. */
 export declare function resetInFlightCounter(): void;
-//# sourceMappingURL=attachments.d.ts.map

package/dist/api/routes/attachments.js

@@ -394,4 +394,3 @@ export const ATTACHMENT_LIMITS = {
 export function resetInFlightCounter() {
     inFlightPerKey.clear();
 }
-//# sourceMappingURL=attachments.js.map

package/dist/api/routes/backends.d.ts

@@ -1,4 +1,3 @@
 import { Hono } from "hono";
 import type { ApiDependencies } from "../server.js";
 export declare function createBackendRoutes(deps: ApiDependencies): Hono;
-//# sourceMappingURL=backends.d.ts.map

package/dist/api/routes/backends.js

@@ -885,11 +885,50 @@ export function createBackendRoutes(deps) {
             return c.json(backendNotRuntimeSupportedResponse(backendId), 400);
         }
         const previousMain = readDefaults().default_backend;
-        setMainBackend(db, backendId);
-        const result = applyDefaultPresets(db, {
-            defaultBackend: backendId,
-            force: force ?? false,
-        });
+        // All persistent DB mutations for a main-backend switch must succeed
+        // atomically — `default_backend`, the `process_backend_config` re-seed,
+        // the native cascade, and the native_unbound audit rows are mutually
+        // load-bearing. Better-sqlite3 turns nested `db.transaction()` calls
+        // into SAVEPOINTs, so wrapping these composes safely with the inner
+        // transactions inside setMainBackend / applyDefaultPresets. The fs
+        // (`writeManagementMd`) and notification side-effects intentionally
+        // stay outside this tx — they cannot be rolled back.
+        const txOutcome = db.transaction(() => {
+            setMainBackend(db, backendId);
+            const presetResult = applyDefaultPresets(db, {
+                defaultBackend: backendId,
+                force: force ?? false,
+            });
+            let cascade = [];
+            if (backendId !== previousMain) {
+                const integrationsBefore = readIntegrations(db);
+                cascade = cascadeNativeBindingsOnMainSwitch(db, backendId);
+                for (const entry of cascade) {
+                    try {
+                        db.prepare(`INSERT INTO agent_actions
+                 (event_id, action_type, trigger, result, detail, started_at, completed_at)
+               VALUES (?, 'integration.native_unbound', 'reactive', 'success', ?, datetime('now'), datetime('now'))`).run(`integration:${entry.key}:native_unbound:${Date.now()}`, JSON.stringify({
+                            key: entry.key,
+                            priorMode: "native",
+                            priorNativeBackend: entry.priorNativeBackend,
+                            newMainBackend: entry.newMainBackend,
+                            // Carry the deniedTools snapshot so a future re-flip-to-
+                            // native restore can be reconstructed without re-querying
+                            // the now-cleared row.
+                            priorDeniedTools: integrationsBefore[entry.key].deniedTools ?? [],
+                        }));
+                        /* c8 ignore start -- in-memory DB always succeeds; catch is defensive */
+                    }
+                    catch (err) {
+                        logger.warn({ err, key: entry.key }, "failed to write integration.native_unbound audit row");
+                    }
+                    /* c8 ignore stop */
+                }
+            }
+            return { presetResult, cascade };
+        })();
+        const result = txOutcome.presetResult;
+        const nativeCascade = txOutcome.cascade;
         const warnings = getAuthWarnings(backendId);
         logger.info({
             backendId,
@@ -897,37 +936,7 @@ export function createBackendRoutes(deps) {
             processRowsUpdated: result.processRowsUpdated,
             processRowsSkipped: result.processRowsSkipped,
         }, "Main backend switched");
-        // INTEGRATION_NATIVE_MODE_DESIGN.md §11.4 — main-backend change
-        // cascade. Capture the pre-cascade snapshot of each native row so we
-        // can write `integration.native_unbound` audit rows for any row that
-        // gets flipped to `disabled`. Runs BEFORE the `onMainBackendChange`
-        // notification so the workdir re-materialise step sees the post-
-        // cascade state and the skill bundle reflects the new mode.
-        let nativeCascade = [];
         if (backendId !== previousMain) {
-            const integrationsBefore = readIntegrations(db);
-            nativeCascade = cascadeNativeBindingsOnMainSwitch(db, backendId);
-            for (const entry of nativeCascade) {
-                try {
-                    db.prepare(`INSERT INTO agent_actions
-               (event_id, action_type, trigger, result, detail, started_at, completed_at)
-             VALUES (?, 'integration.native_unbound', 'reactive', 'success', ?, datetime('now'), datetime('now'))`).run(`integration:${entry.key}:native_unbound:${Date.now()}`, JSON.stringify({
-                        key: entry.key,
-                        priorMode: "native",
-                        priorNativeBackend: entry.priorNativeBackend,
-                        newMainBackend: entry.newMainBackend,
-                        // Carry the deniedTools snapshot so a future re-flip-to-
-                        // native restore can be reconstructed without re-querying
-                        // the now-cleared row.
-                        priorDeniedTools: integrationsBefore[entry.key].deniedTools ?? [],
-                    }));
-                    /* c8 ignore start -- in-memory DB always succeeds; catch is defensive */
-                }
-                catch (err) {
-                    logger.warn({ err, key: entry.key }, "failed to write integration.native_unbound audit row");
-                }
-                /* c8 ignore stop */
-            }
             // INTEGRATION_NATIVE_MODE_DESIGN.md §11.4 — cascade flipped native
             // rows to `disabled` directly in the DB. Mirror that into the
             // on-disk `integrations.md` so the human-readable file does not
@@ -1320,4 +1329,3 @@ export function createBackendRoutes(deps) {
     });
     return app;
 }
-//# sourceMappingURL=backends.js.map

package/dist/api/routes/books.d.ts

@@ -60,4 +60,3 @@ export interface ImportNotebookResult {
 }
 export declare function importKindleNotebook(db: ApiDependencies["db"], parsed: KindleNotebookExport): ImportNotebookResult;
 export declare function createBookRoutes(deps: ApiDependencies): Hono;
-//# sourceMappingURL=books.d.ts.map