@yemi33/minions 0.1.2108 → 0.1.2110

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/onboarding.md

@@ -2,7 +2,7 @@
 
 A fast, hands-on walkthrough for new contributors. Follow the eight steps below in order. Each step is independent enough that you can stop, take a break, and resume without losing state.
 
-> **Prerequisites:** Node.js 18+, Git, and a working Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) authenticated against your Anthropic API key or Claude Max subscription. See the top-level [README.md](../README.md#prerequisites) for the full list.
+> **Prerequisites:** Node.js 22.5+ (required by `package.json#engines` for the `node:sqlite` runtime backing the state DB), Git, and a working Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) authenticated against your Anthropic API key or Claude Max subscription. See the top-level [README.md](../README.md#prerequisites) for the full list.
 
 > **Screenshots:** This walkthrough is intentionally text-only on the first pass. If you want annotated dashboard screenshots, run the [`capture-demos`](../README.md#dashboard) skill after Step 5; it drives Playwright over the running dashboard and writes images you can drop alongside each section.
 
@@ -15,7 +15,7 @@ You only need to clone if you intend to modify Minions itself. End users normall
 ```bash
 git clone https://github.com/yemi33/minions.git ~/minions-dev
 cd ~/minions-dev
-npm install     # installs dev tooling (Playwright); engine itself has zero deps
+npm install     # installs dev tooling (Playwright) + the lone runtime dep (@azure-devops/mcp); engine is otherwise built on Node built-ins
 ```
 
 You should now have:

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`);
+  },
+};