@openparachute/agent 0.1.0

package/src/db/migrations/024-collapse-approvals.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Coverage for migration 024 (paraclaw#11). Both source tables happen to be
+ * empty in Aaron's install, so backfill correctness can only be verified with
+ * fixtures: insert representative rows into `pending_questions` and
+ * `pending_approvals`, then run 024 and assert the resulting `approvals`
+ * shape.
+ *
+ * Strategy: pre-record `collapse-approvals` in `schema_version` so
+ * `runMigrations()` skips it, build the pre-024 DB, seed fixtures, then call
+ * `migration024.up(db)` directly. This is the cheapest way to exercise the
+ * backfill without exporting the private migrations list.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { closeDb, getDb, initTestDb, runMigrations } from '../index.js';
+import { migration024 } from './024-collapse-approvals.js';
+
+function applyAllExcept024(): void {
+  const db = initTestDb();
+  // Mark 024 as already-applied so runMigrations skips it.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY,
+      name    TEXT NOT NULL,
+      applied TEXT NOT NULL
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_schema_version_name ON schema_version(name);
+    INSERT INTO schema_version (version, name, applied) VALUES (9999, 'collapse-approvals', '2026-01-01');
+  `);
+  runMigrations(db);
+}
+
+function seedAgentGroupAndSession(id: string, agentGroupId: string, sessionId: string): void {
+  const db = getDb();
+  db.prepare(
+    `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+     VALUES (?, ?, ?, NULL, 'selective', datetime('now'))`,
+  ).run(agentGroupId, agentGroupId, agentGroupId);
+  db.prepare(
+    `INSERT INTO sessions (id, agent_group_id, messaging_group_id, thread_id, agent_provider, status, container_status, last_active, created_at)
+     VALUES (?, ?, NULL, NULL, NULL, 'active', 'stopped', NULL, datetime('now'))`,
+  ).run(sessionId, agentGroupId);
+}
+
+interface ApprovalRow {
+  id: string;
+  kind: string;
+  agent_group_id: string;
+  session_id: string | null;
+  body: string;
+  status: string;
+  created_at: string;
+  expires_at: string | null;
+}
+
+beforeEach(() => {
+  applyAllExcept024();
+});
+
+afterEach(() => {
+  closeDb();
+});
+
+describe('migration 024 — backfill', () => {
+  it('questions-only fixture maps to kind="question" with derived agent_group_id', () => {
+    seedAgentGroupAndSession('seed-q', 'ag-q', 'sess-q');
+    const db = getDb();
+    db.prepare(
+      `INSERT INTO pending_questions
+         (question_id, session_id, message_out_id, platform_id, channel_type, thread_id, title, options_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'q-1',
+      'sess-q',
+      'msg-out-1',
+      'discord:111',
+      'discord',
+      'thread-1',
+      'Pick one',
+      JSON.stringify([{ label: 'Yes', selectedLabel: 'Yes', value: 'yes' }]),
+      '2026-04-01T00:00:00Z',
+    );
+
+    migration024.up(db);
+
+    const rows = db.prepare(`SELECT * FROM approvals ORDER BY id`).all() as ApprovalRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe('q-1');
+    expect(rows[0].kind).toBe('question');
+    expect(rows[0].agent_group_id).toBe('ag-q'); // derived from session
+    expect(rows[0].session_id).toBe('sess-q');
+    expect(rows[0].status).toBe('pending');
+    const body = JSON.parse(rows[0].body) as Record<string, unknown>;
+    expect(body.title).toBe('Pick one');
+    expect(body.message_out_id).toBe('msg-out-1');
+    expect(body.platform_id).toBe('discord:111');
+    expect(body.channel_type).toBe('discord');
+    expect(body.thread_id).toBe('thread-1');
+    expect(Array.isArray(body.options)).toBe(true);
+  });
+
+  it('approval-per-action fixtures map to kind=action with payload + routing in body', () => {
+    seedAgentGroupAndSession('seed-a', 'ag-a', 'sess-a');
+    const db = getDb();
+    const insertApproval = db.prepare(
+      `INSERT INTO pending_approvals
+         (approval_id, session_id, request_id, action, payload, created_at,
+          agent_group_id, channel_type, platform_id, platform_message_id, expires_at, status, title, options_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const fixtures: Array<[string, string, Record<string, unknown>]> = [
+      ['a-install', 'install_packages', { packages: ['curl'] }],
+      ['a-mcp', 'add_mcp_server', { name: 'tavily', url: 'https://x' }],
+      ['a-cred', 'credential', { provider: 'github' }],
+    ];
+    for (const [id, action, payload] of fixtures) {
+      insertApproval.run(
+        id,
+        'sess-a',
+        id,
+        action,
+        JSON.stringify(payload),
+        '2026-04-02T00:00:00Z',
+        'ag-a',
+        'slack',
+        'C0001',
+        'msg-1',
+        null,
+        'pending',
+        `Approve ${action}?`,
+        JSON.stringify([{ label: 'Approve', selectedLabel: '✅', value: 'approve' }]),
+      );
+    }
+
+    migration024.up(db);
+
+    const rows = db.prepare(`SELECT * FROM approvals ORDER BY id`).all() as ApprovalRow[];
+    // SQLite ORDER BY id is a lexicographic sort over the row-id strings,
+    // not insertion order. Fixture ids `a-cred` < `a-install` < `a-mcp`,
+    // so the kinds line up as credential → install_packages → add_mcp_server.
+    // Renaming a fixture id will reshuffle this list — re-derive, don't
+    // chase by re-sorting.
+    expect(rows.map((r) => r.kind)).toEqual(['credential', 'install_packages', 'add_mcp_server']);
+    for (const r of rows) {
+      expect(r.agent_group_id).toBe('ag-a');
+      expect(r.session_id).toBe('sess-a');
+      expect(r.status).toBe('pending');
+      const body = JSON.parse(r.body) as Record<string, unknown>;
+      expect(body.title).toContain('Approve');
+      expect(body.platform_id).toBe('C0001');
+      expect(body.channel_type).toBe('slack');
+      expect(body.platform_message_id).toBe('msg-1');
+      expect(typeof body.payload).toBe('object');
+    }
+    const installRow = rows.find((r) => r.kind === 'install_packages')!;
+    const installBody = JSON.parse(installRow.body) as { payload: { packages: string[] } };
+    expect(installBody.payload.packages).toEqual(['curl']);
+  });
+
+  it('mixed fixture — questions and approvals both copy over', () => {
+    seedAgentGroupAndSession('seed-m', 'ag-m', 'sess-m');
+    const db = getDb();
+    db.prepare(
+      `INSERT INTO pending_questions
+         (question_id, session_id, message_out_id, platform_id, channel_type, thread_id, title, options_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'q-mix',
+      'sess-m',
+      'mout-1',
+      null,
+      null,
+      null,
+      'Mixed Q',
+      JSON.stringify([{ label: 'Y', selectedLabel: 'Y', value: 'y' }]),
+      '2026-04-03T00:00:00Z',
+    );
+    db.prepare(
+      `INSERT INTO pending_approvals
+         (approval_id, session_id, request_id, action, payload, created_at,
+          agent_group_id, channel_type, platform_id, platform_message_id, expires_at, status, title, options_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'a-mix',
+      'sess-m',
+      'a-mix',
+      'install_packages',
+      JSON.stringify({ packages: ['jq'] }),
+      '2026-04-03T00:00:00Z',
+      'ag-m',
+      null,
+      null,
+      null,
+      null,
+      'pending',
+      'Install jq?',
+      JSON.stringify([{ label: 'Approve', selectedLabel: '✅', value: 'approve' }]),
+    );
+
+    migration024.up(db);
+
+    const rows = db.prepare(`SELECT id, kind FROM approvals ORDER BY id`).all() as ApprovalRow[];
+    expect(rows).toEqual([
+      expect.objectContaining({ id: 'a-mix', kind: 'install_packages' }),
+      expect.objectContaining({ id: 'q-mix', kind: 'question' }),
+    ]);
+  });
+
+  it('drops orphan question whose session vanished', () => {
+    const db = getDb();
+    // Insert a pending_question with a session_id pointing nowhere — backfill
+    // can't derive agent_group_id, so the row should be dropped (not crash).
+    // Bypass FK by disabling temporarily — pending_questions FKs sessions(id).
+    db.exec('PRAGMA foreign_keys = OFF');
+    db.prepare(
+      `INSERT INTO pending_questions
+         (question_id, session_id, message_out_id, platform_id, channel_type, thread_id, title, options_json, created_at)
+       VALUES (?, ?, ?, NULL, NULL, NULL, ?, ?, ?)`,
+    ).run(
+      'q-orphan',
+      'sess-gone',
+      'mout-x',
+      'Orphan',
+      JSON.stringify([{ label: 'Y', selectedLabel: 'Y', value: 'y' }]),
+      '2026-04-04T00:00:00Z',
+    );
+    db.exec('PRAGMA foreign_keys = ON');
+
+    migration024.up(db);
+
+    const rows = db.prepare(`SELECT id FROM approvals`).all() as { id: string }[];
+    expect(rows).toEqual([]);
+  });
+
+  it('drops legacy source tables after backfill', () => {
+    const db = getDb();
+    migration024.up(db);
+    const tables = db
+      .prepare(
+        `SELECT name FROM sqlite_master WHERE type='table' AND name IN ('pending_questions','pending_approvals')`,
+      )
+      .all() as { name: string }[];
+    expect(tables).toEqual([]);
+    const approvals = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name = 'approvals'`).all() as {
+      name: string;
+    }[];
+    expect(approvals.map((t) => t.name)).toEqual(['approvals']);
+  });
+});

package/src/db/migrations/024-collapse-approvals.ts

@@ -0,0 +1,182 @@
+/**
+ * Collapse `pending_questions` and `pending_approvals` into a single
+ * `approvals` table with a `kind` discriminator (paraclaw#11).
+ *
+ * Both tables persisted "agent needs human consent" — questions are inline
+ * UX prompts (kind='question'), approvals are admin-gating for self-mod
+ * actions (kind='install_packages' | 'add_mcp_server' | 'credential' | …).
+ * Same primitive, two storage shapes was vestigial drag.
+ *
+ * The new shape lifts the always-needed fields (id, kind, agent_group_id,
+ * session_id, status, timestamps) into columns and stuffs everything
+ * kind-specific (title, options, routing, request payload) into a single
+ * JSON `body` column. Readers parse on the way out.
+ *
+ * Backfill rules
+ * ──────────────
+ * Questions → kind='question'. agent_group_id is derived from the row's
+ * session (questions never carry it directly; sessions always do). A
+ * question row whose session has vanished (legacy orphan) is dropped —
+ * the response handler couldn't have routed it anyway.
+ *
+ * Approvals → kind=`pending_approvals.action`. agent_group_id comes from
+ * the row's column when set, falling back to the session's. A row with
+ * neither (truly orphaned legacy) is dropped — same reasoning.
+ *
+ * Indexes match the queries the app runs: list-pending-by-group filters
+ * on (status, agent_group_id); session-scoped lookups join on session_id.
+ */
+import { log } from '../../log.js';
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+interface QuestionRow {
+  question_id: string;
+  session_id: string;
+  message_out_id: string;
+  platform_id: string | null;
+  channel_type: string | null;
+  thread_id: string | null;
+  title: string;
+  options_json: string;
+  created_at: string;
+  agent_group_id: string | null;
+}
+
+interface ApprovalRow {
+  approval_id: string;
+  session_id: string | null;
+  request_id: string;
+  action: string;
+  payload: string;
+  created_at: string;
+  agent_group_id: string | null;
+  channel_type: string | null;
+  platform_id: string | null;
+  platform_message_id: string | null;
+  expires_at: string | null;
+  status: string;
+  title: string;
+  options_json: string;
+  session_group_id: string | null;
+}
+
+export const migration024: Migration = {
+  version: 24,
+  name: 'collapse-approvals',
+  up(db: Database) {
+    db.exec(`
+      CREATE TABLE approvals (
+        id               TEXT PRIMARY KEY,
+        kind             TEXT NOT NULL,
+        agent_group_id   TEXT NOT NULL REFERENCES agent_groups(id),
+        session_id       TEXT REFERENCES sessions(id),
+        body             TEXT NOT NULL,
+        status           TEXT NOT NULL DEFAULT 'pending',
+        approver_user_id TEXT,
+        decided_at       TEXT,
+        created_at       TEXT NOT NULL,
+        expires_at       TEXT
+      );
+      CREATE INDEX idx_approvals_status ON approvals(status, agent_group_id);
+      CREATE INDEX idx_approvals_session ON approvals(session_id) WHERE session_id IS NOT NULL;
+    `);
+
+    const insert = db.prepare(
+      `INSERT INTO approvals
+         (id, kind, agent_group_id, session_id, body, status, created_at, expires_at)
+       VALUES
+         (@id, @kind, @agent_group_id, @session_id, @body, @status, @created_at, @expires_at)`,
+    );
+
+    let questionsCopied = 0;
+    let questionsDropped = 0;
+    const questionRows = db
+      .prepare<QuestionRow>(
+        `SELECT pq.*, s.agent_group_id AS agent_group_id
+           FROM pending_questions pq
+           LEFT JOIN sessions s ON s.id = pq.session_id`,
+      )
+      .all();
+    for (const r of questionRows) {
+      if (!r.agent_group_id) {
+        log.warn('Dropping orphan pending_question (session vanished)', { question_id: r.question_id });
+        questionsDropped++;
+        continue;
+      }
+      insert.run({
+        id: r.question_id,
+        kind: 'question',
+        agent_group_id: r.agent_group_id,
+        session_id: r.session_id,
+        body: JSON.stringify({
+          title: r.title,
+          options: JSON.parse(r.options_json),
+          message_out_id: r.message_out_id,
+          platform_id: r.platform_id,
+          channel_type: r.channel_type,
+          thread_id: r.thread_id,
+        }),
+        status: 'pending',
+        created_at: r.created_at,
+        expires_at: null,
+      });
+      questionsCopied++;
+    }
+
+    let approvalsCopied = 0;
+    let approvalsDropped = 0;
+    const approvalRows = db
+      .prepare<ApprovalRow>(
+        `SELECT pa.*, s.agent_group_id AS session_group_id
+           FROM pending_approvals pa
+           LEFT JOIN sessions s ON s.id = pa.session_id`,
+      )
+      .all();
+    for (const r of approvalRows) {
+      const groupId = r.agent_group_id ?? r.session_group_id;
+      if (!groupId) {
+        log.warn('Dropping orphan pending_approval (no agent_group_id and no session)', {
+          approval_id: r.approval_id,
+          action: r.action,
+        });
+        approvalsDropped++;
+        continue;
+      }
+      insert.run({
+        id: r.approval_id,
+        kind: r.action,
+        agent_group_id: groupId,
+        session_id: r.session_id,
+        body: JSON.stringify({
+          title: r.title,
+          options: JSON.parse(r.options_json),
+          request_id: r.request_id,
+          payload: JSON.parse(r.payload),
+          platform_id: r.platform_id,
+          channel_type: r.channel_type,
+          thread_id: null,
+          platform_message_id: r.platform_message_id,
+        }),
+        status: r.status,
+        created_at: r.created_at,
+        expires_at: r.expires_at,
+      });
+      approvalsCopied++;
+    }
+
+    db.exec(`
+      DROP TABLE pending_questions;
+      DROP TABLE pending_approvals;
+    `);
+
+    if (questionsCopied + questionsDropped + approvalsCopied + approvalsDropped > 0) {
+      log.info('approvals collapse complete', {
+        questionsCopied,
+        questionsDropped,
+        approvalsCopied,
+        approvalsDropped,
+      });
+    }
+  },
+};

package/src/db/migrations/025-secret-mode-check.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Migration 025 (paraclaw#28): CHECK constraint on agent_groups.secret_mode.
+ * Verify it (a) preserves existing rows across the table recreate-and-rename
+ * and (b) rejects out-of-range writes that previously would have been
+ * silently accepted.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { closeDb, initTestDb, runMigrations } from '../index.js';
+import { migration025 } from './025-secret-mode-check.js';
+import { applyMigrationsExcept } from './_test-helpers.js';
+
+afterEach(() => {
+  closeDb();
+});
+
+describe('migration 025 — secret_mode CHECK constraint', () => {
+  it('preserves rows already in agent_groups across the table recreate', () => {
+    // Apply everything up through 024, leaving 025 unrun. Insert a row
+    // with the pre-025 shape (no CHECK constraint). Then run 025 the
+    // way the runner runs it (FKs off connection-scope, then a tx
+    // around `up`) and confirm the row survives the DROP-and-RENAME.
+    const db = applyMigrationsExcept([migration025]);
+    db.prepare(
+      `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+       VALUES (?, ?, ?, NULL, 'all', datetime('now'))`,
+    ).run('keepme', 'keepme', 'keepme');
+
+    db.exec('PRAGMA foreign_keys = OFF');
+    try {
+      db.transaction(() => migration025.up(db))();
+    } finally {
+      db.exec('PRAGMA foreign_keys = ON');
+    }
+
+    const row = db.prepare(`SELECT * FROM agent_groups WHERE id = ?`).get('keepme') as {
+      secret_mode: string;
+    };
+    expect(row.secret_mode).toBe('all');
+  });
+
+  it('survives an orphan FK row in a referencing table (paraclaw#54)', () => {
+    // Production-flavored regression: real installs carry pre-FK-era
+    // orphan rows (e.g. a `sessions.agent_group_id` whose parent was
+    // never inserted or got dropped). Migration 025's first cut used
+    // `defer_foreign_keys = TRUE`, which delays the FK check to commit
+    // and then trips it on the orphan, taking the whole boot down with
+    // a `FOREIGN KEY constraint failed` Startup error. Plant the
+    // production-shaped triple — real parent, valid child pointing at
+    // it, AND orphan child pointing at a never-existed parent — and
+    // run 025 the way the runner runs it. Empirically, the deferred
+    // check only fires when the renamed parent has live referencing
+    // children, so the orphan-only fixture isn't enough; a bare orphan
+    // slips past `defer_foreign_keys=TRUE`.
+    const db = applyMigrationsExcept([migration025]);
+
+    // Real parent + valid child (the natural way, FKs ON).
+    db.prepare(
+      `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+       VALUES (?, ?, ?, NULL, 'all', datetime('now'))`,
+    ).run('g-real', 'g-real', 'g-real');
+    db.prepare(
+      `INSERT INTO sessions (id, agent_group_id, messaging_group_id, thread_id, status, created_at)
+       VALUES (?, ?, NULL, NULL, 'active', datetime('now'))`,
+    ).run('valid-session', 'g-real');
+
+    // Orphan child: foreign_keys is ON by default in test DBs
+    // (initTestDb), so flip it off to plant one. This mirrors how the
+    // orphan appeared on Aaron's DB — early-era operations under
+    // foreign_keys = OFF, never reconciled.
+    db.exec('PRAGMA foreign_keys = OFF');
+    db.prepare(
+      `INSERT INTO sessions (id, agent_group_id, messaging_group_id, thread_id, status, created_at)
+       VALUES (?, ?, NULL, NULL, 'active', datetime('now'))`,
+    ).run('orphan-session', 'never-existed-agent-group');
+    db.exec('PRAGMA foreign_keys = ON');
+
+    // Verify the FK violation is real *before* running the migration —
+    // i.e. the fixture would actually trip a deferred check.
+    const violationsBefore = db.prepare(`PRAGMA foreign_key_check`).all() as {
+      table: string;
+      rowid: number;
+      parent: string;
+      fkid: number;
+    }[];
+    expect(violationsBefore.some((v) => v.table === 'sessions' && v.parent === 'agent_groups')).toBe(true);
+
+    // Run 025 via the real runner so the disableForeignKeys flag is
+    // exercised end-to-end. Drop the fake-applied marker first so the
+    // runner picks it up.
+    db.prepare('DELETE FROM schema_version WHERE name = ?').run('secret-mode-check');
+    expect(() => runMigrations(db)).not.toThrow();
+
+    // Both children are still there, the parent survived the recreate,
+    // the migration recorded itself, and the CHECK constraint is in
+    // place.
+    const orphan = db.prepare(`SELECT id, agent_group_id FROM sessions WHERE id = ?`).get('orphan-session') as {
+      id: string;
+      agent_group_id: string;
+    };
+    expect(orphan).toEqual({ id: 'orphan-session', agent_group_id: 'never-existed-agent-group' });
+    const valid = db.prepare(`SELECT id, agent_group_id FROM sessions WHERE id = ?`).get('valid-session') as {
+      id: string;
+      agent_group_id: string;
+    };
+    expect(valid).toEqual({ id: 'valid-session', agent_group_id: 'g-real' });
+    const parent = db.prepare(`SELECT id FROM agent_groups WHERE id = ?`).get('g-real') as { id: string };
+    expect(parent?.id).toBe('g-real');
+    const applied = db.prepare(`SELECT name FROM schema_version WHERE name = ?`).get('secret-mode-check') as {
+      name: string;
+    };
+    expect(applied?.name).toBe('secret-mode-check');
+    expect(() =>
+      db
+        .prepare(
+          `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+           VALUES (?, ?, ?, NULL, 'bogus', datetime('now'))`,
+        )
+        .run('badmode-after-fix', 'badmode-after-fix', 'badmode-after-fix'),
+    ).toThrow(/CHECK constraint/i);
+  });
+
+  it('rejects out-of-range writes', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    expect(() =>
+      db
+        .prepare(
+          `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+           VALUES (?, ?, ?, NULL, 'bogus', datetime('now'))`,
+        )
+        .run('badmode', 'badmode', 'badmode'),
+    ).toThrow(/CHECK constraint/i);
+  });
+
+  it('still accepts both valid modes', () => {
+    const db = initTestDb();
+    runMigrations(db);
+    db.prepare(
+      `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+       VALUES (?, ?, ?, NULL, 'all', datetime('now'))`,
+    ).run('g-all', 'g-all', 'g-all');
+    db.prepare(
+      `INSERT INTO agent_groups (id, name, folder, agent_provider, secret_mode, created_at)
+       VALUES (?, ?, ?, NULL, 'selective', datetime('now'))`,
+    ).run('g-sel', 'g-sel', 'g-sel');
+    const rows = db
+      .prepare(`SELECT id, secret_mode FROM agent_groups WHERE id IN ('g-all', 'g-sel') ORDER BY id`)
+      .all() as { id: string; secret_mode: string }[];
+    expect(rows).toEqual([
+      { id: 'g-all', secret_mode: 'all' },
+      { id: 'g-sel', secret_mode: 'selective' },
+    ]);
+  });
+});

package/src/db/migrations/025-secret-mode-check.ts

@@ -0,0 +1,49 @@
+/**
+ * Add a `CHECK (secret_mode IN ('all', 'selective'))` constraint to
+ * `agent_groups`. The TS layer narrows `SecretMode = 'all' | 'selective'`
+ * already, but a stray raw SQL writer (a future migration, an ad-hoc
+ * fix-up script) could land an out-of-range value the readers would then
+ * silently treat as `selective`. Belt-and-suspenders.
+ *
+ * SQLite doesn't allow `ALTER TABLE … ADD CHECK`. The only path is the
+ * recreate-and-rename dance: build the new table with the CHECK inline,
+ * copy the rows, drop the old, rename in place.
+ *
+ * paraclaw#54: the first cut used `PRAGMA defer_foreign_keys = TRUE`,
+ * which only postpones the FK check to commit-time. On a real install
+ * with a pre-FK-enforcement orphan row in a referencing table (a
+ * `sessions.agent_group_id` whose parent was dropped before FKs were
+ * enforced), the deferred check at COMMIT scans the renamed table and
+ * trips on the orphan, taking boot down. The structural fix is
+ * `PRAGMA foreign_keys = OFF` connection-scope, which SQLite forbids
+ * changing mid-txn — so the toggle has to live in the runner, not here.
+ * `disableForeignKeys: true` opts this migration into that wrapper.
+ */
+import type { Database } from '../connection.js';
+import type { Migration } from './index.js';
+
+export const migration025: Migration = {
+  version: 25,
+  name: 'secret-mode-check',
+  disableForeignKeys: true,
+  up(db: Database) {
+    db.exec(`
+      CREATE TABLE agent_groups_new (
+        id               TEXT PRIMARY KEY,
+        name             TEXT NOT NULL,
+        folder           TEXT NOT NULL UNIQUE,
+        agent_provider   TEXT,
+        secret_mode      TEXT NOT NULL DEFAULT 'selective'
+                           CHECK (secret_mode IN ('all', 'selective')),
+        created_at       TEXT NOT NULL
+      );
+
+      INSERT INTO agent_groups_new (id, name, folder, agent_provider, secret_mode, created_at)
+        SELECT id, name, folder, agent_provider, secret_mode, created_at
+          FROM agent_groups;
+
+      DROP TABLE agent_groups;
+      ALTER TABLE agent_groups_new RENAME TO agent_groups;
+    `);
+  },
+};