@yemi33/minions 0.1.2108 → 0.1.2109

package/dashboard/js/qa.js

@@ -344,19 +344,81 @@ function _qaRenderRunRow(run) {
   } else if (agentId) {
     liveLink = '<a href="#" class="qa-run-link" onclick="event.preventDefault();qaOpenRunAgent(\'\',this.dataset.agent);" data-agent="' + escHtml(agentId) + '">' + escHtml(linkLabel) + '</a>';
   }
+  // W-mpxp90xs000i5732 — per-row Delete button, terminal-only. The engine
+  // also enforces terminal-only with a 409 (defense in depth); rendering
+  // the button conditionally just keeps the UI honest about what's safe
+  // to click.
+  let deleteBtn = '';
+  if (_qaIsTerminalStatus(status)) {
+    deleteBtn = '<button class="qa-btn-ghost qa-run-delete-btn" ' +
+      'data-run-id="' + escHtml(id) + '" ' +
+      'onclick="qaDeleteRun(this.dataset.runId)">Delete</button>';
+  }
+  const actionsHtml = (liveLink || deleteBtn)
+    ? '<span class="qa-run-actions">' + liveLink + deleteBtn + '</span>'
+    : '';
   const artifactsHtml = _qaRenderArtifactPreviews(id, run.artifacts || []);
-  return '<div class="qa-run-row">' +
+  return '<div class="qa-run-row" data-run-id="' + escHtml(id) + '">' +
     '<div class="qa-run-head">' +
       '<span class="qa-run-status ' + escHtml(statusClass) + '">' + escHtml(status) + '</span>' +
       '<span class="qa-run-name">' + escHtml(runbook) + '</span>' +
       (target ? '<span class="qa-run-target">→ <code>' + escHtml(target) + '</code></span>' : '') +
       (ts ? '<span class="qa-run-ts">' + escHtml(String(ts).slice(0, 19).replace('T', ' ')) + '</span>' : '') +
-      (liveLink ? '<span class="qa-run-actions">' + liveLink + '</span>' : '') +
+      actionsHtml +
     '</div>' +
     (artifactsHtml ? '<div class="qa-run-artifacts">' + artifactsHtml + '</div>' : '') +
     '</div>';
 }
 
+// W-mpxp90xs000i5732 — terminal status set kept in sync with
+// engine/qa-runs.js#TERMINAL_STATUSES. The Delete button only renders for
+// runs in one of these states; the engine's deleteQaRun returns 409 for
+// anything else (defense in depth).
+function _qaIsTerminalStatus(status) {
+  if (!status || typeof status !== 'string') return false;
+  const s = status.toLowerCase();
+  return s === 'passed' || s === 'failed' || s === 'errored';
+}
+
+// W-mpxp90xs000i5732 — per-row Delete handler. Confirms with the user,
+// fires DELETE /api/qa/runs/<id>, optimistic-removes the row on 200, and
+// surfaces errors via showToast(). Does NOT use alert() post-API per the
+// WI's UX contract.
+async function qaDeleteRun(id) {
+  if (!id) return;
+  if (!confirm('Delete QA run ' + id + ' and its artifacts? This cannot be undone.')) return;
+  let res, json;
+  try {
+    res = await fetch('/api/qa/runs/' + encodeURIComponent(id), {
+      method: 'DELETE',
+    });
+  } catch (e) {
+    if (typeof showToast === 'function') {
+      showToast('cmd-toast', 'Delete QA run failed: ' + (e && e.message || String(e)), false);
+    }
+    return;
+  }
+  try { json = await res.json(); } catch { json = {}; }
+  if (res.ok && json && json.ok) {
+    const sel = (window.CSS && CSS.escape ? CSS.escape(id) : id.replace(/"/g, '\\"'));
+    const row = document.querySelector('.qa-run-row[data-run-id="' + sel + '"]');
+    if (row && row.parentNode) row.parentNode.removeChild(row);
+    if (typeof loadQaRuns === 'function') loadQaRuns();
+    if (typeof showToast === 'function') {
+      const msg = json.artifactsRemoved
+        ? 'QA run deleted (artifacts removed).'
+        : 'QA run deleted.';
+      showToast('cmd-toast', msg, true);
+    }
+    return;
+  }
+  const errMsg = (json && (json.error + (json.currentStatus ? ' (status=' + json.currentStatus + ')' : '')))
+    || ('HTTP ' + (res ? res.status : '?'));
+  if (typeof showToast === 'function') {
+    showToast('cmd-toast', 'Delete QA run failed: ' + errMsg, false);
+  }
+}
+
 function _qaRenderArtifactPreviews(runId, artifacts) {
   if (!runId || !Array.isArray(artifacts) || !artifacts.length) return '';
   const parts = [];

package/dashboard/js/settings.js

@@ -404,6 +404,7 @@ async function openSettings() {
     '<div class="settings-stack">' +
       settingsToggle('Allow Temp Agents', 'set-allowTempAgents', !!e.allowTempAgents, 'Spawn ephemeral agents when all permanent agents are busy') +
       settingsToggle('Disable model discovery', 'set-disableModelDiscovery', !!e.disableModelDiscovery, 'Skip /api/runtimes/<name>/models REST calls fleet-wide. Settings UI falls back to free-text.') +
+      settingsToggle('QA: dual-write JSON sidecars', 'set-qaDualWriteJson', e.qaDualWriteJson !== false, 'Keep mirroring qa-runs.json and qa-sessions.json on every mutation alongside the SQLite source of truth. Default ON. Disable only once external tooling has been migrated off the JSON files — disabling drops the rollback path back to the JSON store.') +
     '</div>';
 
   // Section registry — order is intentional (Runtime + Auto-fix surface first
@@ -880,6 +881,7 @@ async function saveSettings() {
       copilotReasoningSummaries: !!document.getElementById('set-copilotReasoningSummaries')?.checked,
       maxBudgetUsd: (document.getElementById('set-maxBudgetUsd')?.value ?? '').trim(),
       disableModelDiscovery: !!document.getElementById('set-disableModelDiscovery')?.checked,
+      qaDualWriteJson: !!document.getElementById('set-qaDualWriteJson')?.checked,
       // W-mpmwxkrw000872ec — global font-size scale. Allowlist validation
       // (and clamp messaging) lives server-side in handleSettingsUpdate.
       fontSize: document.getElementById('set-fontSize')?.value || 'small',

package/dashboard.js

@@ -10345,6 +10345,46 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }
   }
 
+  // W-mpxp90xs000i5732 — DELETE /api/qa/runs/<id>. Hard-delete: removes the
+  // run from engine/qa-runs.json AND best-effort wipes the on-disk artifact
+  // directory under engine/qa-artifacts/<runId>/. Terminal-only — refuses
+  // pending/running runs with 409. Caller must cancel/complete the run via
+  // the lifecycle helpers before deletion. CSRF/Origin gate is applied by
+  // the server dispatcher for all mutating methods (see MUTATING_METHODS).
+  function handleQaRunsDelete(req, res, match) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const id = decodeURIComponent(match[1] || '');
+      if (!_qaIsSafeSegment(id)) {
+        return jsonReply(res, 400, { error: 'invalid run id' }, req);
+      }
+      const result = qa.deleteQaRun(id);
+      if (result && result.ok) {
+        return jsonReply(res, 200, {
+          ok: true,
+          id,
+          artifactsRemoved: !!result.artifactsRemoved,
+        }, req);
+      }
+      const err = result && result.error;
+      if (err === 'not_found') {
+        return jsonReply(res, 404, { error: 'not_found' }, req);
+      }
+      if (err === 'not_terminal') {
+        return jsonReply(res, 409, {
+          error: 'not_terminal',
+          currentStatus: result.currentStatus,
+        }, req);
+      }
+      if (err === 'invalid_id') {
+        return jsonReply(res, 400, { error: 'invalid run id' }, req);
+      }
+      return jsonReply(res, 500, { error: 'qa-runs delete returned unknown result' }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   function handleQaArtifact(req, res, match) {
     try {
       const qa = require('./engine/qa-runs');
@@ -11052,6 +11092,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // traversal attempts return 403, missing files return 404.
     { method: 'GET', path: '/api/qa/runs', desc: 'List QA validation runs (newest first). Optional ?limit=N and ?status=pending|running|passed|failed|errored filters.', handler: handleQaRunsList },
     { method: 'GET', path: /^\/api\/qa\/runs\/([^/?]+)$/, template: '/api/qa/runs/<id>', desc: 'Fetch a single QA run record by id.', handler: handleQaRunsById },
+    { method: 'DELETE', path: /^\/api\/qa\/runs\/([^/?]+)$/, template: '/api/qa/runs/<id>', desc: 'Delete a QA run by id (terminal runs only). Best-effort removes artifacts under engine/qa-artifacts/<runId>/.', destructive: true, handler: handleQaRunsDelete },
     { method: 'GET', path: /^\/api\/qa\/artifacts\/([^/?]+)\/([^?]+)$/, template: '/api/qa/artifacts/<runId>/<file>', desc: 'Serve a QA artifact file (image/video/log). Sandboxed to engine/qa-artifacts/; rejects path traversal with 403.', handler: handleQaArtifact },
     // QA Runbooks (W-mpeiwz6k0005bf34-a) — per-project test plans stored at
     // <MINIONS_DIR>/projects/<name>/runbooks/<id>.json. Pure persistence —

package/docs/deprecated.json

@@ -1,4 +1,12 @@
 [
+  {
+    "id": "qa-json-sidecars",
+    "location": "engine/small-state-store.js _mirrorQaRunsJson + _mirrorQaSessionsJson; engine/shared.js _qaMutator (mirror call); dashboard/js/settings.js set-qaDualWriteJson toggle",
+    "reason": "Phase 8 migration (migrate-qa-state-to-sqlite, shipped 2026-06) moved qa_runs + qa_sessions into SQLite (engine/state.db, tables qa_runs + qa_sessions) as the source of truth. The legacy JSON sidecars engine/qa-runs.json and engine/qa-sessions.json are dual-written on every mutation while operators migrate external tooling and dashboards off the JSON files. Gated by engine.qaDualWriteJson (default true).",
+    "deprecated": "2026-06-03",
+    "targetRemovalDate": "2026-09-03",
+    "notes": "Safe to remove on or after 2026-09-03 (90 days post-ship, ~3 release windows) once: (1) operator telemetry / dashboard Settings shows engine.qaDualWriteJson flipped false on the main fleet; (2) no external readers (CI scripts, dashboards, ops runbooks) reference the JSON sidecars directly. Removal scope: delete _mirrorQaRunsJson + _mirrorQaSessionsJson + their exports in engine/small-state-store.js; drop the _qaDualWriteEnabled() + mirror call in engine/shared.js#_qaMutator; remove qaDualWriteJson from ENGINE_DEFAULTS and from the Settings toggle in dashboard/js/settings.js; remove the divergence-rehydrate branch in _resyncQaRunsIfDiverged / _resyncQaSessionsIfDiverged (the JSON files no longer exist to diverge against)."
+  },
   {
     "id": "config-poll-key-migration",
     "location": "engine/queries.js:126-163",

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Accepted — implementation in progress**
 
-> **Implementation status (as of 2026-05):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–7 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool — see `CHANGELOG.md`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
+> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–8 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, and qa_runs + qa_sessions — see `CHANGELOG.md`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true) — when ops trust SQL as the source of truth for QA state, flip it false to halve write I/O on hot loops. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
 
 ## Executive Summary
 

package/docs/qa-runbook-lifecycle.md

@@ -27,6 +27,41 @@ and clears the interval on page navigation via the `switchPage` wrapper in
 `dashboard/js/qa.js` (matches `_stopPlanPoll`/`_stopMeetingPoll` pattern in
 `dashboard/js/state.js`).
 
+### Persistence (Phase 8: SQLite source of truth)
+
+Since the Phase 8 migration (`migrate-qa-state-to-sqlite`), both
+`qa-runs.json` and `qa-sessions.json` are dual-written sidecars and SQLite
+(`engine/state.db`, tables `qa_runs` + `qa_sessions`) is the source of
+truth. Every mutation goes through `shared.mutateQaRuns` /
+`shared.mutateQaSessions`, which apply inside a SQLite transaction
+(`BEGIN IMMEDIATE`) then best-effort mirror to JSON under a `withFileLock`
+on the sidecar path so cross-process writers serialize. Reads go through
+`small-state-store.readQaRuns` / `readQaSessions`, which compare the SQL
+content-hash to the JSON sidecar and rehydrate SQL from JSON when an
+external editor (operator hand-edit, manual rollback) has diverged.
+
+The JSON mirror is gated by `engine.qaDualWriteJson` (default true). Once
+operators trust SQL as the source of truth and have migrated external
+tooling off the JSON files, flip it false via Dashboard → Settings →
+Advanced → "QA: dual-write JSON sidecars" to halve write I/O. With the
+toggle off, `qa-runs.json` / `qa-sessions.json` stop receiving updates
+(stale snapshot at the moment of the flip), so don't disable until any
+external readers have moved to the SQL tables or the dashboard `/api/qa/*`
+endpoints. The qa-runs cap (`QA_RUNS_MAX_RECORDS=2000`) and qa-sessions
+cap (`QA_SESSIONS_MAX_RECORDS=500`) still apply, enforced in-memory at
+createRun/createSession time.
+
+### Deleting runs
+
+`DELETE /api/qa/runs/<id>` hard-deletes a single terminal-status run
+(`passed`/`failed`/`errored`) and best-effort removes its artifact
+directory under `engine/qa-artifacts/<runId>/`. Non-terminal runs return
+`409 not_terminal` — operators must cancel/complete the run via the
+lifecycle helpers first. Invalid ids return `400 invalid_id`. The /qa
+dashboard page renders a per-row Delete button conditionally (terminal
+only), confirms with the user, and surfaces success/error via
+`showToast()` rather than `alert()`.
+
 ## Artifact contract
 
 `engine/qa-artifacts/<runId>/<file>`, served via
@@ -198,6 +233,7 @@ Documented in `dashboard.js`; routes are visible at `GET /api/routes`.
 | POST   | `/api/qa/sessions/<id>/dismiss`            | Non-terminal → `done`. Accept the draft as final; leaves spawn alive. Optional `{ summary }`.                              |
 | GET    | `/api/qa/runners`                          | List registered runner adapters (built-ins + `qa-runners.d/` plugins). Metadata only — hooks (functions) are stripped.    |
 | POST   | `/api/qa/runners/reload`                   | Clear in-process registry, re-register built-ins, re-scan `qa-runners.d/` for plugin edits. Returns the fresh runner list. |
+| DELETE | `/api/qa/runs/<id>`                        | Hard-delete a single QA run record (terminal-status runs only) and best-effort wipe its artifact directory under `engine/qa-artifacts/<runId>/`. Returns `{ ok: true, id, artifactsRemoved }` on success, `409 not_terminal` for in-flight runs, `404 not_found` for unknown ids. |
 
 The single-session POSTs share `_qaSessionAction` in `dashboard.js`; module
 errors are mapped to HTTP via `_qaSessionsErrorToStatus`:

package/engine/db/migrations/009-qa.js

@@ -0,0 +1,140 @@
+// engine/db/migrations/009-qa.js
+//
+// Phase 8: move the two QA state files into SQL.
+//
+//   engine/qa-runs.json      -> qa_runs       (top-level array → row per id)
+//   engine/qa-sessions.json  -> qa_sessions   (top-level array → row per id)
+//
+// Mirrors the dual-write / content-hash divergence pattern established by
+// the watches and Phase 7 small-state stores. JSON sidecars stay in place as
+// dual-write mirrors for one release cycle (gated by `engine.qaDualWriteJson`).
+
+const path = require('path');
+const fs = require('fs');
+
+function _resolveMinionsDir() {
+  const envHome = process.env.MINIONS_HOME || process.env.MINIONS_TEST_DIR;
+  if (envHome) return envHome;
+  try { return require('../../shared').MINIONS_DIR; } catch { return null; }
+}
+
+function _toMs(v) {
+  if (v == null) return null;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  const parsed = Date.parse(v);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function _readJsonOr(filePath, fallback) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch { return fallback; }
+}
+
+module.exports = {
+  version: 9,
+  description: 'qa_runs + qa_sessions',
+  up(db) {
+    db.exec(`
+      CREATE TABLE qa_runs (
+        id            TEXT PRIMARY KEY,
+        runbook_id    TEXT NOT NULL,
+        target_name   TEXT NOT NULL,
+        project       TEXT,
+        work_item_id  TEXT,
+        status        TEXT NOT NULL,
+        started_at    INTEGER,
+        completed_at  INTEGER,
+        created_at    INTEGER NOT NULL,
+        data          TEXT NOT NULL
+      );
+      CREATE INDEX idx_qa_runs_status        ON qa_runs(status);
+      CREATE INDEX idx_qa_runs_created_at    ON qa_runs(created_at DESC);
+      CREATE INDEX idx_qa_runs_runbook       ON qa_runs(runbook_id);
+      CREATE INDEX idx_qa_runs_target        ON qa_runs(target_name);
+      CREATE INDEX idx_qa_runs_work_item     ON qa_runs(work_item_id) WHERE work_item_id IS NOT NULL;
+
+      CREATE TABLE qa_sessions (
+        id                TEXT PRIMARY KEY,
+        state             TEXT NOT NULL,
+        primary_project   TEXT,
+        qa_run_id         TEXT,
+        created_at        INTEGER NOT NULL,
+        updated_at        INTEGER NOT NULL,
+        completed_at      INTEGER,
+        data              TEXT NOT NULL
+      );
+      CREATE INDEX idx_qa_sessions_state         ON qa_sessions(state);
+      CREATE INDEX idx_qa_sessions_created_at    ON qa_sessions(created_at DESC);
+      CREATE INDEX idx_qa_sessions_project       ON qa_sessions(primary_project);
+      CREATE INDEX idx_qa_sessions_qa_run        ON qa_sessions(qa_run_id) WHERE qa_run_id IS NOT NULL;
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const now = Date.now();
+    let inserted = 0;
+
+    // ── qa_runs ────────────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'qa-runs.json'), null);
+      if (Array.isArray(raw)) {
+        const ins = db.prepare(`
+          INSERT INTO qa_runs (id, runbook_id, target_name, project, work_item_id, status, started_at, completed_at, created_at, data)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO NOTHING
+        `);
+        for (const run of raw) {
+          if (!run || !run.id) continue;
+          try {
+            ins.run(
+              String(run.id),
+              String(run.runbookId || ''),
+              String(run.targetName || ''),
+              run.project || null,
+              run.workItemId || null,
+              String(run.status || 'pending'),
+              _toMs(run.startedAt),
+              _toMs(run.completedAt),
+              _toMs(run.createdAt) || now,
+              JSON.stringify(run),
+            );
+            inserted += 1;
+          } catch { /* duplicate / corrupt — skip */ }
+        }
+      }
+    }
+
+    // ── qa_sessions ────────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'qa-sessions.json'), null);
+      if (Array.isArray(raw)) {
+        const ins = db.prepare(`
+          INSERT INTO qa_sessions (id, state, primary_project, qa_run_id, created_at, updated_at, completed_at, data)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO NOTHING
+        `);
+        for (const session of raw) {
+          if (!session || !session.id) continue;
+          try {
+            ins.run(
+              String(session.id),
+              String(session.state || 'pending'),
+              session.primaryProject || (session.spec && session.spec.project) || null,
+              session.qaRunId || null,
+              _toMs(session.createdAt) || now,
+              _toMs(session.updatedAt) || _toMs(session.createdAt) || now,
+              _toMs(session.completedAt),
+              JSON.stringify(session),
+            );
+            inserted += 1;
+          } catch { /* duplicate / corrupt — skip */ }
+        }
+      }
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v9: backfilled ${inserted} QA rows; JSON files kept as dual-write mirrors`);
+  },
+};

package/engine/qa-runs.js

@@ -5,13 +5,19 @@
  * a managed target. Records carry status, timing, work-item linkage, and an
  * artifacts array (screenshots, logs, videos captured during the run).
  *
- * State file: engine/qa-runs.json (single file, all runs across all projects).
- * Artifacts live on disk under engine/qa-artifacts/<runId>/ — the run record
- * stores relative paths (`type`, `path`, `label`, `capturedAt`), and the
- * dashboard exposes them through GET /api/qa/artifacts/<runId>/<file>.
+ * Persistence: SQLite (engine/state.db, `qa_runs` table) as source of truth
+ * since Phase 8 (PRD: migrate-qa-state-to-sqlite). The legacy JSON sidecar
+ * at engine/qa-runs.json is dual-written on every mutation when
+ * `engine.qaDualWriteJson` is true (default) so external tooling and the
+ * rollback path keep working. Artifacts live on disk under
+ * engine/qa-artifacts/<runId>/ — the run record stores relative paths
+ * (`type`, `path`, `label`, `capturedAt`), and the dashboard exposes them
+ * through GET /api/qa/artifacts/<runId>/<file>.
  *
- * Concurrency: every mutation goes through mutateJsonFileLocked per
- * CLAUDE.md best-practice; callbacks are synchronous and never await.
+ * Concurrency: every mutation goes through shared.mutateQaRuns, which routes
+ * to small-state-store.applyQaRunsMutation inside a SQLite transaction
+ * (BEGIN IMMEDIATE) plus a content-hash divergence rehydrate on read.
+ * Callbacks are synchronous and never await.
  *
  * Status state machine:
  *
@@ -20,22 +26,20 @@
  *                       ╲──▶ errored
  *
  * Illegal transitions throw with a descriptive error. Terminal statuses
- * (passed / failed / errored) cannot transition further.
+ * (passed / failed / errored) cannot transition further. `deleteRun` is
+ * only allowed once a run is terminal.
  */
 
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { mutateJsonFileLocked, uid, ts, log } = shared;
+const { mutateQaRuns, uid, ts, log } = shared;
 
-// Cap qa-runs.json so the file doesn't grow unboundedly over months of nightly
-// QA dispatch. Without a cap, listRuns + summarizeRunsForStatus pay O(N) on
-// every read, and /api/status's fast-state slice runs the summary on every
-// rebuild — at 10k+ historical runs the JSON parse alone starts eating into
-// the W-mpehsyhv event-loop budget that CC SSE isolation depends on. Mirrors
-// the 2500-entry cap on engine/log.json. createRun trims oldest-by-createdAt
-// when crossing the threshold; terminal-status runs that have already shipped
-// completion notifications are safe to drop.
+// Cap qa-runs.json so the file (and qa_runs table) doesn't grow unboundedly
+// over months of nightly QA dispatch. Mirrors the 2500-entry cap on
+// engine/log.json. createRun trims oldest-by-createdAt when crossing the
+// threshold; terminal-status runs that have already shipped completion
+// notifications are safe to drop.
 const QA_RUNS_MAX_RECORDS = 2000;
 
 const QA_RUN_STATUS = Object.freeze({
@@ -80,7 +84,8 @@ const ALLOWED_TRANSITIONS = {
   [QA_RUN_STATUS.ERRORED]: new Set(),
 };
 
-// Dynamic paths — respect MINIONS_TEST_DIR for test isolation.
+// Dynamic paths — respect MINIONS_TEST_DIR for test isolation. Kept exported
+// for back-compat with tests that probe the JSON sidecar on disk.
 function qaRunsPath() {
   return path.join(shared.MINIONS_DIR, 'engine', 'qa-runs.json');
 }
@@ -148,7 +153,7 @@ function createRun({ runbookId, targetName, project, workItemId } = {}) {
     createdAt: ts(),
   };
 
-  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+  mutateQaRuns((runs) => {
     if (!Array.isArray(runs)) runs = [];
     runs.push(run);
     // Rotation: drop oldest-by-createdAt when over the cap. Cheap because
@@ -158,7 +163,7 @@ function createRun({ runbookId, targetName, project, workItemId } = {}) {
       runs = runs.slice(runs.length - QA_RUNS_MAX_RECORDS);
     }
     return runs;
-  }, { defaultValue: [] });
+  });
 
   // Pre-create the artifact directory outside the lock — directory creation
   // is idempotent and slow file I/O must never run while holding the lock.
@@ -178,7 +183,7 @@ function markRunning(id) {
   if (!id) throw new Error('qa-runs: id is required');
   let captured = null;
   let transitionError = null;
-  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+  mutateQaRuns((runs) => {
     if (!Array.isArray(runs)) runs = [];
     const run = runs.find(r => r && r.id === id);
     if (!run) { transitionError = new Error(`qa-runs: run not found: ${id}`); return runs; }
@@ -188,7 +193,7 @@ function markRunning(id) {
     run.startedAt = ts();
     captured = run;
     return runs;
-  }, { defaultValue: [] });
+  });
   if (transitionError) throw transitionError;
   return captured;
 }
@@ -215,7 +220,7 @@ function completeRun(id, { status, summary, artifacts } = {}) {
 
   let captured = null;
   let transitionError = null;
-  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+  mutateQaRuns((runs) => {
     if (!Array.isArray(runs)) runs = [];
     const run = runs.find(r => r && r.id === id);
     if (!run) { transitionError = new Error(`qa-runs: run not found: ${id}`); return runs; }
@@ -230,7 +235,7 @@ function completeRun(id, { status, summary, artifacts } = {}) {
     }
     captured = run;
     return runs;
-  }, { defaultValue: [] });
+  });
   if (transitionError) throw transitionError;
   return captured;
 }
@@ -242,11 +247,22 @@ function completeRun(id, { status, summary, artifacts } = {}) {
  */
 function getRun(id) {
   if (!id) return null;
-  const runs = shared.safeJsonArr(qaRunsPath());
+  const runs = _readRuns();
   const run = runs.find(r => r && r.id === id);
   return run || null;
 }
 
+// Internal helper — reads via the small-state store (SQL → JSON fallback)
+// when available, falling back to direct JSON read if SQLite is unavailable.
+function _readRuns() {
+  try {
+    const store = require('./small-state-store');
+    const arr = store.readQaRuns();
+    if (Array.isArray(arr)) return arr;
+  } catch { /* fall back */ }
+  return shared.safeJsonArr(qaRunsPath());
+}
+
 /**
  * List runs, newest first, optionally filtered by status, capped by limit.
  * @param {object} [opts]
@@ -255,7 +271,7 @@ function getRun(id) {
  * @returns {Array<object>}
  */
 function listRuns({ limit, status } = {}) {
-  let runs = shared.safeJsonArr(qaRunsPath());
+  let runs = _readRuns();
   if (!Array.isArray(runs)) return [];
   if (status) {
     if (!isValidStatus(status)) return [];
@@ -280,7 +296,7 @@ function listRuns({ limit, status } = {}) {
  */
 function getRunsForWorkItem(wi) {
   if (!wi) return [];
-  const runs = shared.safeJsonArr(qaRunsPath());
+  const runs = _readRuns();
   return runs
     .filter(r => r && r.workItemId === wi)
     .sort((a, b) => {
@@ -303,7 +319,7 @@ function getRunsForWorkItem(wi) {
 function setRunWorkItemId(id, workItemId) {
   if (!id) return null;
   let captured = null;
-  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+  mutateQaRuns((runs) => {
     if (!Array.isArray(runs)) runs = [];
     const run = runs.find(r => r && r.id === id);
     if (run) {
@@ -311,10 +327,80 @@ function setRunWorkItemId(id, workItemId) {
       captured = run;
     }
     return runs;
-  }, { defaultValue: [] });
+  });
   return captured;
 }
 
+// W-mpxp90xs000i5732 — sandbox check for run ids reaching deleteQaRun /
+// artifact path operations. Mirrors dashboard.js#_qaIsSafeSegment: rejects
+// empty / overlong / nulls / separators / .. / drive letters. Defense in
+// depth — createRun's uid-suffix is already safe, but operator-driven
+// DELETE endpoints take ids from URL paths, so every callsite re-validates.
+function _isSafeRunId(id) {
+  if (!id || typeof id !== 'string') return false;
+  if (id.length > 128) return false;
+  if (id.indexOf('\0') >= 0) return false;
+  if (id.indexOf('/') >= 0 || id.indexOf('\\') >= 0) return false;
+  if (id.indexOf('..') >= 0) return false;
+  if (/^[a-zA-Z]:/.test(id)) return false;
+  return true;
+}
+
+/**
+ * Hard-delete a terminal-status run record and best-effort remove its
+ * artifact directory. Result envelope (matches PR #3008 shape so the
+ * dashboard DELETE /api/qa/runs/<id> handler stays generic):
+ *
+ *   { ok: true,  id, artifactsRemoved: bool }
+ *   { ok: false, error: 'invalid_id' | 'not_found' | 'not_terminal',
+ *     currentStatus?: string }
+ *
+ * Caller must cancel/complete the run via the lifecycle helpers before
+ * deletion — running/pending runs are refused so an operator can't vacuum a
+ * live QA agent out from under itself. The artifact rmSync runs OUTSIDE
+ * the lock, with a path.resolve + startsWith() belt-and-braces sandbox.
+ *
+ * @param {string} id - run id (must pass _isSafeRunId)
+ * @returns {object} envelope (see above)
+ */
+function deleteQaRun(id) {
+  if (!_isSafeRunId(id)) return { ok: false, error: 'invalid_id' };
+  let captured = null;
+  let notFound = false;
+  let notTerminal = null;
+  mutateQaRuns((runs) => {
+    if (!Array.isArray(runs)) return runs;
+    const idx = runs.findIndex(r => r && r.id === id);
+    if (idx < 0) { notFound = true; return runs; }
+    const run = runs[idx];
+    if (!TERMINAL_STATUSES.has(run.status)) {
+      notTerminal = run.status;
+      return runs;
+    }
+    captured = run;
+    runs.splice(idx, 1);
+    return runs;
+  });
+  if (notFound) return { ok: false, error: 'not_found' };
+  if (notTerminal !== null) return { ok: false, error: 'not_terminal', currentStatus: notTerminal };
+  // Sandbox check + best-effort rm outside the lock.
+  let artifactsRemoved = false;
+  try {
+    const dir = qaArtifactsDirForRun(id);
+    const base = path.resolve(qaArtifactsDir());
+    const resolved = path.resolve(dir);
+    if (resolved.startsWith(base + path.sep) || resolved === base) {
+      if (fs.existsSync(resolved)) {
+        fs.rmSync(resolved, { recursive: true, force: true });
+        artifactsRemoved = true;
+      }
+    }
+  } catch (e) {
+    log('warn', `qa-runs: rm artifacts dir failed for ${id}: ${e.message}`);
+  }
+  return { ok: true, id, artifactsRemoved, run: captured };
+}
+
 /**
  * Cheap summary helper for the dashboard /api/status fast-state slice. Returns
  * `{ total, sig }` without sorting the run list — the sidebar activity-dot
@@ -322,14 +408,12 @@ function setRunWorkItemId(id, workItemId) {
  * (b) when any status flips. `sig` joins id:status across all current runs;
  * any change to either advances the string, which is enough signal for the
  * counter. We deliberately skip the sort that listRuns() does because this
- * runs on every fast-state rebuild (~every 10 s + every mtime-tracked write),
- * and an O(N log N) sort on a 2 k-entry file would eat into the event-loop
- * budget that CC SSE isolation (W-mpehsyhv) depends on.
+ * runs on every fast-state rebuild (~every 10 s + every mtime-tracked write).
  *
  * @returns {{ total: number, sig: string }}
  */
 function summarizeRunsForStatus() {
-  const runs = shared.safeJsonArr(qaRunsPath());
+  const runs = _readRuns();
   if (!Array.isArray(runs) || runs.length === 0) return { total: 0, sig: '' };
   let sig = '';
   for (const r of runs) {
@@ -350,6 +434,8 @@ module.exports = {
   markRunning,
   completeRun,
   setRunWorkItemId,
+  deleteQaRun,
+  _isSafeRunId,
   getRun,
   listRuns,
   getRunsForWorkItem,

package/engine/qa-sessions.js

@@ -28,8 +28,10 @@
  *
  *   (awaiting-approval ──▶ drafting on /edit; drafting ──▶ executing on auto mode.)
  *
- * Concurrency: every mutation goes through mutateJsonFileLocked per the repo
- * convention. Callbacks are synchronous and never await. Slow filesystem work
+ * Concurrency: every mutation goes through shared.mutateQaSessions, which
+ * routes to small-state-store.applyQaSessionsMutation inside a SQLite
+ * transaction (BEGIN IMMEDIATE) plus a content-hash divergence rehydrate on
+ * read. Callbacks are synchronous and never await. Slow filesystem work
  * (qa-tests/<id>/ scaffolding, dispatch enqueueing) runs OUTSIDE the lock.
  *
  * Path-traversal hardening: sessionId is generated by createSession() with a
@@ -38,14 +40,28 @@
  * a filesystem path or a session lookup. Mirrors engine/qa-runbooks.js
  * _isSafeId (PR #2694 review feedback).
  *
- * State file: engine/qa-sessions.json (single file, all sessions across all
- * projects), capped at QA_SESSIONS_MAX_RECORDS via createSession-time rotation.
+ * Persistence: SQLite (engine/state.db, `qa_sessions` table) as source of
+ * truth since Phase 8 (PRD: migrate-qa-state-to-sqlite). The legacy JSON
+ * sidecar at engine/qa-sessions.json is dual-written on every mutation when
+ * `engine.qaDualWriteJson` is true (default). Capped at
+ * QA_SESSIONS_MAX_RECORDS via createSession-time rotation.
  */
 
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { mutateJsonFileLocked, uid, ts, log } = shared;
+const { mutateQaSessions, uid, ts, log } = shared;
+
+// Internal helper — read sessions via the small-state store when available
+// (SQL → JSON fallback inside the store), else direct JSON read.
+function _readSessions() {
+  try {
+    const store = require('./small-state-store');
+    const arr = store.readQaSessions();
+    if (Array.isArray(arr)) return arr;
+  } catch { /* fall back */ }
+  return _readSessions();
+}
 
 // Cap engine/qa-sessions.json. Sessions cost more than runs (3 WIs, a
 // managed-spawn, artifacts) so the operational steady state is meaningfully
@@ -422,7 +438,7 @@ function createSession(spec) {
     completedAt: null,
   };
 
-  mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+  mutateQaSessions( (sessions) => {
     if (!Array.isArray(sessions)) sessions = [];
     sessions.push(session);
     // Rotation: drop oldest-by-createdAt when over cap. Cheap because it runs
@@ -448,7 +464,7 @@ function createSession(spec) {
  */
 function getSession(id) {
   if (!_isSafeSessionId(id)) return null;
-  const sessions = shared.safeJsonArr(qaSessionsPath());
+  const sessions = _readSessions();
   return sessions.find(s => s && s.id === id) || null;
 }
 
@@ -520,7 +536,7 @@ function getSessionTestFile(sessionId) {
  * List sessions, newest first, optionally filtered by state, capped by limit.
  */
 function listSessions({ limit, state } = {}) {
-  let sessions = shared.safeJsonArr(qaSessionsPath());
+  let sessions = _readSessions();
   if (!Array.isArray(sessions)) return [];
   if (state) {
     if (!isValidState(state)) return [];
@@ -547,7 +563,7 @@ function setSessionWorkItem(id, phase, workItemId) {
   if (!_isSafeSessionId(id)) return null;
   if (!Object.values(SESSION_PHASE).includes(phase)) return null;
   let captured = null;
-  mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+  mutateQaSessions( (sessions) => {
     if (!Array.isArray(sessions)) sessions = [];
     const session = sessions.find(s => s && s.id === id);
     if (session) {
@@ -571,7 +587,7 @@ function setSessionWorkItem(id, phase, workItemId) {
 function setSessionQaRunId(id, qaRunId) {
   if (!_isSafeSessionId(id)) return null;
   let captured = null;
-  mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+  mutateQaSessions( (sessions) => {
     if (!Array.isArray(sessions)) sessions = [];
     const session = sessions.find(s => s && s.id === id);
     if (session) {
@@ -607,7 +623,7 @@ function transitionSession(id, toState, patch = {}) {
 
   let captured = null;
   let transitionError = null;
-  mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+  mutateQaSessions( (sessions) => {
     if (!Array.isArray(sessions)) sessions = [];
     const session = sessions.find(s => s && s.id === id);
     if (!session) { transitionError = new Error(`qa-sessions: session not found: ${id}`); return sessions; }
@@ -961,7 +977,7 @@ function queueSetup(sessionId, opts = {}) {
     for (const [key, wiId] of Object.entries(builtWiIds)) {
       if (nextStatus[key]) nextStatus[key] = { ...nextStatus[key], wiId };
     }
-    mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+    mutateQaSessions( (sessions) => {
       if (!Array.isArray(sessions)) sessions = [];
       const s = sessions.find(x => x && x.id === sessionId);
       if (s) {
@@ -1031,7 +1047,7 @@ function handleSetupComplete(sessionId, opts = {}) {
   // Update this project's entry under lock. Capture the merged map so we
   // can decide on a transition without re-reading.
   let mergedStatus = null;
-  mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+  mutateQaSessions( (sessions) => {
     if (!Array.isArray(sessions)) sessions = [];
     const s = sessions.find(x => x && x.id === sessionId);
     if (!s || !s.setupStatus) return sessions;
@@ -1280,7 +1296,7 @@ function dismissSession(sessionId, { summary } = {}) {
  * @returns {{ total: number, sig: string }}
  */
 function summarizeSessionsForStatus() {
-  const sessions = shared.safeJsonArr(qaSessionsPath());
+  const sessions = _readSessions();
   if (!Array.isArray(sessions) || sessions.length === 0) return { total: 0, sig: '' };
   let sig = '';
   for (const s of sessions) {

package/engine/shared.js

@@ -2072,6 +2072,13 @@ const ENGINE_DEFAULTS = {
   ccUseWorkerPool: false,            // Sub-task C of W-mp2w003600196c51 (CC perf): when true AND CC runtime is copilot, _invokeCcStream routes through engine/cc-worker-pool.js (persistent `copilot --acp` per CC tab) instead of spawning a fresh CLI per turn. Off by default — opt-in feature flag. **Structurally copilot-only**: the pool spawns `copilot --acp` (Agent Client Protocol); Claude Code does not implement ACP, so resolveCcUseWorkerPool returns false on non-copilot CC runtimes even with explicit-true (W-mphlriic00095f69 — prevents silent runtime switch). Engine/agent dispatch path stays per-process regardless.
   maxBudgetUsd: undefined,       // fleet USD ceiling for --max-budget-usd (per-agent override: agents.<id>.maxBudgetUsd). Honors 0 via ?? so a literal cap of $0 works
   disableModelDiscovery: false,  // skip runtime.listModels() REST calls fleet-wide (settings UI falls back to free-text)
+  // Phase 8 (qa-runs.json + qa-sessions.json → SQL). When true, every QA
+  // mutation also writes the JSON sidecar at engine/qa-runs.json and
+  // engine/qa-sessions.json for back-compat with external tooling. SQL is
+  // always the source of truth — flip this OFF once operators trust the
+  // SQL store and want to drop the dual-write cost. Sunset tracked in
+  // docs/deprecated.json (qa-json-sidecars).
+  qaDualWriteJson: true,
   // W-mpmwxkrw000872ec — dashboard global font-size scale. Drives the
   // [data-font-size] attribute on <html> via the inline bootstrap script in
   // layout.html (localStorage fast path) and is reconciled from the server
@@ -2979,6 +2986,77 @@ const mutateWorktreePool = _smallStateMutator({
   defaultValue: () => ({ entries: [] }),
 });
 
+/**
+ * Phase 8 — QA state mutators. Both qa-runs and qa-sessions are top-level
+ * JSON arrays (mutator receives the array; mutates in place or returns a
+ * replacement). The store diffs by `id`. Falls back to mutateJsonFileLocked
+ * on SQLite failure so a node:sqlite-broken install keeps recording QA
+ * state. The JSON mirror is gated by `engine.qaDualWriteJson` (default true)
+ * — turn off once operators trust SQL as the source of truth.
+ */
+function _qaDualWriteEnabled() {
+  try {
+    const cfg = safeJson(path.join(MINIONS_DIR, 'config.json')) || {};
+    const flag = cfg && cfg.engine && cfg.engine.qaDualWriteJson;
+    if (flag === false) return false;
+    return true;
+  } catch { return true; }
+}
+
+function _qaMutator({ filePath, applyMutation, mirror, topic }) {
+  return (mutator) => {
+    // Cross-process serialization: SQLite's BEGIN IMMEDIATE already
+    // serializes the table write across processes, but the JSON sidecar
+    // mirror is best-effort and can race — two concurrent processes can
+    // each snapshot SQL and write the JSON, and an older snapshot can
+    // overwrite a newer one. Wrap SQL apply + mirror in a single file
+    // lock on the JSON path's .lock file so multi-process writers
+    // serialize through the mirror, matching the legacy fully-locked
+    // semantics that test/unit/qa-runs.test.js asserts.
+    return withFileLock(filePath + '.lock', () => {
+      try {
+        const store = require('./small-state-store');
+        const { wrote, result } = store[applyMutation]((arr) => {
+          if (!Array.isArray(arr)) arr = [];
+          return mutator(arr) || arr;
+        });
+        if (wrote) {
+          if (_qaDualWriteEnabled()) {
+            try { store[mirror](filePath); } catch { /* mirror best-effort */ }
+          }
+          try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+        }
+        return result;
+      } catch (e) {
+        if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) throw e;
+        return mutateJsonFileLocked(filePath, (data) => {
+          if (!Array.isArray(data)) data = [];
+          return mutator(data) || data;
+        }, {
+          defaultValue: [],
+          onWrote: () => {
+            try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+          },
+        });
+      }
+    }, { timeoutMs: 5000, retries: 3 });
+  };
+}
+
+const mutateQaRuns = _qaMutator({
+  filePath: path.join(MINIONS_DIR, 'engine', 'qa-runs.json'),
+  applyMutation: 'applyQaRunsMutation',
+  mirror: '_mirrorQaRunsJson',
+  topic: 'qa_runs',
+});
+
+const mutateQaSessions = _qaMutator({
+  filePath: path.join(MINIONS_DIR, 'engine', 'qa-sessions.json'),
+  applyMutation: 'applyQaSessionsMutation',
+  mirror: '_mirrorQaSessionsJson',
+  topic: 'qa_sessions',
+});
+
 /**
  * Route a watches mutation through the SQL store. Same shape as
  * mutateWorkItems / mutatePullRequests: mutator receives the watches
@@ -5769,7 +5847,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,

package/engine/small-state-store.js

@@ -521,6 +521,314 @@ function _mirrorWorktreePoolJson(filePath) {
   } catch { /* mirror best-effort */ }
 }
 
+// ─── qa_runs ───────────────────────────────────────────────────────────────
+// Shape: [ {id, runbookId, targetName, project, workItemId, status, startedAt,
+//           completedAt, createdAt, artifacts, summary, ...}, ... ]
+// SQL:   row per id, extracted query columns + JSON blob `data`.
+// Pattern: mirrors watches-store (top-level array, id-keyed diff).
+
+let _qaRunsHash = null;
+
+function _hydrateQaRuns(db) {
+  const fp = _resolveFilePath('qa-runs.json');
+  const raw = _readJson(fp) || [];
+  if (!Array.isArray(raw)) return;
+  db.prepare('DELETE FROM qa_runs').run();
+  const now = Date.now();
+  const ins = db.prepare(`
+    INSERT INTO qa_runs (id, runbook_id, target_name, project, work_item_id, status, started_at, completed_at, created_at, data)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO NOTHING
+  `);
+  for (const run of raw) {
+    if (!run || !run.id) continue;
+    ins.run(
+      String(run.id),
+      String(run.runbookId || ''),
+      String(run.targetName || ''),
+      run.project || null,
+      run.workItemId || null,
+      String(run.status || 'pending'),
+      _toMs(run.startedAt),
+      _toMs(run.completedAt),
+      _toMs(run.createdAt) || now,
+      JSON.stringify(run),
+    );
+  }
+}
+
+function _resyncQaRunsIfDiverged(db) {
+  const fp = _resolveFilePath('qa-runs.json');
+  const currentHash = _fileContentHash(fp);
+  if (currentHash == null) return;
+  if (_qaRunsHash != null && currentHash === _qaRunsHash) return;
+  if (_qaRunsHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM qa_runs LIMIT 1').get();
+    if (sqlHas) { _qaRunsHash = currentHash; return; }
+  }
+  _hydrateQaRuns(db);
+  _qaRunsHash = currentHash;
+}
+
+function _readQaRunsFromSqlOnly(db) {
+  const rows = db.prepare('SELECT data FROM qa_runs ORDER BY created_at, rowid').all();
+  const out = [];
+  for (const row of rows) {
+    try { out.push(JSON.parse(row.data)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+function readQaRuns() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJson(_resolveFilePath('qa-runs.json')) || []; }
+  _resyncQaRunsIfDiverged(db);
+  const out = _readQaRunsFromSqlOnly(db);
+  if (out.length === 0) {
+    const fallback = _readJson(_resolveFilePath('qa-runs.json'));
+    if (Array.isArray(fallback) && fallback.length > 0) return fallback;
+    return [];
+  }
+  return out;
+}
+
+function applyQaRunsMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`small-state-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    _resyncQaRunsIfDiverged(db);
+    const before = _readQaRunsFromSqlOnly(db);
+    const beforeSnap = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null)
+      ? before
+      : (Array.isArray(next) ? next : before);
+
+    const indexById = (arr) => {
+      const out = new Map();
+      for (const r of arr) {
+        if (r && r.id) out.set(String(r.id), r);
+      }
+      return out;
+    };
+    const beforeMap = indexById(beforeSnap);
+    const afterMap = indexById(after);
+
+    const now = Date.now();
+    const upsert = db.prepare(`
+      INSERT INTO qa_runs (id, runbook_id, target_name, project, work_item_id, status, started_at, completed_at, created_at, data)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        runbook_id   = excluded.runbook_id,
+        target_name  = excluded.target_name,
+        project      = excluded.project,
+        work_item_id = excluded.work_item_id,
+        status       = excluded.status,
+        started_at   = excluded.started_at,
+        completed_at = excluded.completed_at,
+        created_at   = excluded.created_at,
+        data         = excluded.data
+    `);
+    const del = db.prepare('DELETE FROM qa_runs WHERE id = ?');
+    let wrote = false;
+    for (const [id, run] of afterMap) {
+      const prev = beforeMap.get(id);
+      if (!prev || JSON.stringify(prev) !== JSON.stringify(run)) {
+        upsert.run(
+          id,
+          String(run.runbookId || ''),
+          String(run.targetName || ''),
+          run.project || null,
+          run.workItemId || null,
+          String(run.status || 'pending'),
+          _toMs(run.startedAt),
+          _toMs(run.completedAt),
+          _toMs(run.createdAt) || now,
+          JSON.stringify(run),
+        );
+        wrote = true;
+      }
+    }
+    for (const [id] of beforeMap) {
+      if (!afterMap.has(id)) { del.run(id); wrote = true; }
+    }
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorQaRunsJson(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    const arr = _readQaRunsFromSqlOnly(getDb());
+    const target = filePath || _resolveFilePath('qa-runs.json');
+    shared.safeWrite(target, arr);
+    const h = _fileContentHash(target);
+    if (h != null) _qaRunsHash = h;
+  } catch { /* mirror best-effort */ }
+}
+
+// ─── qa_sessions ───────────────────────────────────────────────────────────
+// Shape: [ {id, state, spec:{...}, primaryProject, coServices, setupStatus,
+//           workItems, managedSpawnName, qaRunId, testFile, summary,
+//           failureClass, error, createdAt, updatedAt, completedAt, ...}, ... ]
+// SQL:   row per id, extracted query columns + JSON blob.
+
+let _qaSessionsHash = null;
+
+function _qaSessionPrimaryProject(session) {
+  if (!session || typeof session !== 'object') return null;
+  if (session.primaryProject) return String(session.primaryProject);
+  if (session.spec && session.spec.project) return String(session.spec.project);
+  if (session.spec && Array.isArray(session.spec.projects) && session.spec.projects[0]) {
+    return String(session.spec.projects[0]);
+  }
+  return null;
+}
+
+function _hydrateQaSessions(db) {
+  const fp = _resolveFilePath('qa-sessions.json');
+  const raw = _readJson(fp) || [];
+  if (!Array.isArray(raw)) return;
+  db.prepare('DELETE FROM qa_sessions').run();
+  const now = Date.now();
+  const ins = db.prepare(`
+    INSERT INTO qa_sessions (id, state, primary_project, qa_run_id, created_at, updated_at, completed_at, data)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO NOTHING
+  `);
+  for (const session of raw) {
+    if (!session || !session.id) continue;
+    ins.run(
+      String(session.id),
+      String(session.state || 'pending'),
+      _qaSessionPrimaryProject(session),
+      session.qaRunId || null,
+      _toMs(session.createdAt) || now,
+      _toMs(session.updatedAt) || _toMs(session.createdAt) || now,
+      _toMs(session.completedAt),
+      JSON.stringify(session),
+    );
+  }
+}
+
+function _resyncQaSessionsIfDiverged(db) {
+  const fp = _resolveFilePath('qa-sessions.json');
+  const currentHash = _fileContentHash(fp);
+  if (currentHash == null) return;
+  if (_qaSessionsHash != null && currentHash === _qaSessionsHash) return;
+  if (_qaSessionsHash == null) {
+    const sqlHas = db.prepare('SELECT 1 FROM qa_sessions LIMIT 1').get();
+    if (sqlHas) { _qaSessionsHash = currentHash; return; }
+  }
+  _hydrateQaSessions(db);
+  _qaSessionsHash = currentHash;
+}
+
+function _readQaSessionsFromSqlOnly(db) {
+  const rows = db.prepare('SELECT data FROM qa_sessions ORDER BY created_at, rowid').all();
+  const out = [];
+  for (const row of rows) {
+    try { out.push(JSON.parse(row.data)); } catch { /* skip */ }
+  }
+  return out;
+}
+
+function readQaSessions() {
+  const { getDb } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch { return _readJson(_resolveFilePath('qa-sessions.json')) || []; }
+  _resyncQaSessionsIfDiverged(db);
+  const out = _readQaSessionsFromSqlOnly(db);
+  if (out.length === 0) {
+    const fallback = _readJson(_resolveFilePath('qa-sessions.json'));
+    if (Array.isArray(fallback) && fallback.length > 0) return fallback;
+    return [];
+  }
+  return out;
+}
+
+function applyQaSessionsMutation(mutator) {
+  const { getDb, withTransaction } = require('./db');
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`small-state-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    _resyncQaSessionsIfDiverged(db);
+    const before = _readQaSessionsFromSqlOnly(db);
+    const beforeSnap = JSON.parse(JSON.stringify(before));
+    const next = mutator(before);
+    const after = (next === undefined || next === null)
+      ? before
+      : (Array.isArray(next) ? next : before);
+
+    const indexById = (arr) => {
+      const out = new Map();
+      for (const s of arr) {
+        if (s && s.id) out.set(String(s.id), s);
+      }
+      return out;
+    };
+    const beforeMap = indexById(beforeSnap);
+    const afterMap = indexById(after);
+
+    const now = Date.now();
+    const upsert = db.prepare(`
+      INSERT INTO qa_sessions (id, state, primary_project, qa_run_id, created_at, updated_at, completed_at, data)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        state           = excluded.state,
+        primary_project = excluded.primary_project,
+        qa_run_id       = excluded.qa_run_id,
+        created_at      = excluded.created_at,
+        updated_at      = excluded.updated_at,
+        completed_at    = excluded.completed_at,
+        data            = excluded.data
+    `);
+    const del = db.prepare('DELETE FROM qa_sessions WHERE id = ?');
+    let wrote = false;
+    for (const [id, session] of afterMap) {
+      const prev = beforeMap.get(id);
+      if (!prev || JSON.stringify(prev) !== JSON.stringify(session)) {
+        upsert.run(
+          id,
+          String(session.state || 'pending'),
+          _qaSessionPrimaryProject(session),
+          session.qaRunId || null,
+          _toMs(session.createdAt) || now,
+          _toMs(session.updatedAt) || _toMs(session.createdAt) || now,
+          _toMs(session.completedAt),
+          JSON.stringify(session),
+        );
+        wrote = true;
+      }
+    }
+    for (const [id] of beforeMap) {
+      if (!afterMap.has(id)) { del.run(id); wrote = true; }
+    }
+    return { wrote, result: after };
+  });
+}
+
+function _mirrorQaSessionsJson(filePath) {
+  try {
+    const shared = require('./shared');
+    const { getDb } = require('./db');
+    const arr = _readQaSessionsFromSqlOnly(getDb());
+    const target = filePath || _resolveFilePath('qa-sessions.json');
+    shared.safeWrite(target, arr);
+    const h = _fileContentHash(target);
+    if (h != null) _qaSessionsHash = h;
+  } catch { /* mirror best-effort */ }
+}
+
 // ─── Test seam ─────────────────────────────────────────────────────────────
 
 function _resetAllForTest() {
@@ -531,11 +839,15 @@ function _resetAllForTest() {
     db.exec('DELETE FROM pipeline_runs');
     db.exec('DELETE FROM managed_processes');
     db.exec('DELETE FROM worktree_pool');
+    try { db.exec('DELETE FROM qa_runs'); } catch { /* migration not applied */ }
+    try { db.exec('DELETE FROM qa_sessions'); } catch { /* migration not applied */ }
   } catch { /* not initialized */ }
   _scheduleRunsHash = null;
   _pipelineRunsHash = null;
   _managedProcessesHash = null;
   _worktreePoolHash = null;
+  _qaRunsHash = null;
+  _qaSessionsHash = null;
 }
 
 module.exports = {
@@ -555,6 +867,14 @@ module.exports = {
   readWorktreePool,
   applyWorktreePoolMutation,
   _mirrorWorktreePoolJson,
+  // qa_runs
+  readQaRuns,
+  applyQaRunsMutation,
+  _mirrorQaRunsJson,
+  // qa_sessions
+  readQaSessions,
+  applyQaSessionsMutation,
+  _mirrorQaSessionsJson,
   // test seam
   _resetAllForTest,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2108",
+  "version": "0.1.2109",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"