@yemi33/minions 0.1.2378 → 0.1.2380

package/docs/design-inbox-entries-schema.md

@@ -1,7 +1,7 @@
 # inbox_entries Table Schema
 
 ## Overview
-The `inbox_entries` table is the persistent store for operator and agent inbox messages within the Minions orchestration engine. It provides a time-ordered, unread-tracking message queue decoupled from the runtime work-item/dispatch lifecycle.
+The `inbox_entries` table and `engine/inbox-store.js` implement a persistent, time-ordered, unread-tracking message queue decoupled from the runtime work-item/dispatch lifecycle. The store API exists, but production engine, dashboard, and consolidation paths do not consume it yet; those paths still use their existing inbox mechanisms.
 
 ## Schema Specification
 
@@ -9,26 +9,27 @@ The `inbox_entries` table is the persistent store for operator and agent inbox m
 
 | Column | Type | Constraints | Purpose |
 |--------|------|-----------|---------|
-| `id` | TEXT | PRIMARY KEY | Unique message identifier; generated as `<recipient>-<timestamp>-<sender>-<seq>` format |
+| `id` | TEXT | PRIMARY KEY | Unique message identifier; generated as `<recipient>-<timestamp>-<sender>-<seq>-<counter>-<random>` |
 | `recipient_session_id` | TEXT | NOT NULL | Session ID of the inbox owner (operator or agent); routes messages to specific actor |
 | `sender_id` | TEXT | NOT NULL | Identifier of the message originator; structured as `<agent-id>` or `'system'` or `'operator'` |
 | `sender_name` | TEXT | NOT NULL | Human-readable sender name for UI display; persisted at write-time for offline/archived reference |
-| `sender_type` | TEXT | NOT NULL | Enum: `'agent'`, `'system'`, `'operator'`; constrains allowed sender_id values |
-| `interaction_id` | TEXT | NOT NULL | Group ID linking related messages (e.g., work-item dispatch feedback, PR review batch); enables threading and deduplication |
-| `sequence` | INTEGER | NOT NULL, DEFAULT 0 | Per-interaction message counter; disambiguates bursts and enables ordering within same millisecond |
+| `sender_type` | TEXT | NOT NULL | Sender category; `createInboxEntry()` accepts `'agent'`, `'system'`, or `'operator'` |
+| `interaction_id` | TEXT | NOT NULL | Caller-supplied group ID for related messages |
+| `sequence` | INTEGER | NOT NULL, DEFAULT 0 | Caller-supplied per-interaction ordering metadata; not required to be unique |
 | `summary` | TEXT | NOT NULL | Title/subject line; used for list views and user scanning; always present even if content is truncated |
 | `content` | TEXT | NOT NULL | Full message body; may contain Markdown, code blocks, or structured JSON sidecars (not yet parsed at table level) |
-| `unread` | INTEGER | NOT NULL, DEFAULT 1 | Boolean flag (0/1); toggled by reader, cleared on archive/delete; enables fast unread-count queries |
+| `unread` | INTEGER | NOT NULL, DEFAULT 1 | Boolean flag (0/1); changed by the read/unread mutators |
 | `sent_at` | INTEGER | NOT NULL | Unix timestamp (milliseconds) of message creation; primary sort key for time-ordered display |
 | `read_at` | INTEGER | Nullable | Unix timestamp (milliseconds) when recipient first read the message; null until marked read |
 | `notified_at` | INTEGER | Nullable | Unix timestamp (milliseconds) of last notification event sent to operator; null if no notification dispatched |
 
 ### Constraints & Relationships
 
-- **PK constraint:** `id` is globally unique across all inboxes; collision risk is negligible given the composite structure (recipient + timestamp + sender + seq).
+- **PK constraint:** `id` is globally unique across all inboxes. The store combines caller context with a process-local counter and random suffix, then retries a conflicting insert up to five times.
 - **FK (soft):** `recipient_session_id` does NOT enforce a referential constraint to `sessions` table (sessions may be archived). Queries SHOULD handle missing recipients gracefully.
-- **FK (soft):** `sender_id` is informational only; no validation that the sender exists in the `config.agents` or active sessions. Invalid senders are logged but do not block writes.
-- **No composite index on (recipient_session_id, sent_at):** See Performance section.
+- **FK (soft):** `sender_id` is informational only; no validation requires it to exist in `config.agents` or active sessions.
+- **Application validation:** `createInboxEntry()` accepts only `agent`, `system`, or `operator` for `sender_type`; SQLite does not enforce that enum.
+- **Indexes:** Migration 019 creates composite recipient/time and interaction indexes. See Performance Considerations.
 
 ## Architectural Rationale
 
@@ -36,71 +37,62 @@ The `inbox_entries` table is the persistent store for operator and agent inbox m
 
 1. **Separate inbox table vs. inline dispatch/work-item attachments.**
    - Inboxes can outlive their source work items (e.g., a feedback message remains useful after the WI is done).
-   - Decoupling allows independent inbox lifecycle (archive, export, cleanup) without cascading work-item deletes.
-   - Supports rich async consolidation (team notes, KB articles) that don't belong to any single WI.
+   - Decoupling allows independent read/unread and deletion lifecycle without cascading work-item deletes.
 
 2. **`unread` flag instead of soft-delete or status enum.**
    - Fast count queries for badge (`SELECT COUNT(*) WHERE recipient_session_id = ? AND unread = 1`).
-   - Unread state is mutable; allows mark-as-read UX without data loss.
-   - Simplifies archive/export (no tombstone filtering needed).
+   - Unread state is mutable; allows mark-as-read and mark-as-unread behavior without deleting content.
 
 3. **`sender_type` as an explicit column.**
-   - Allows schema validation (e.g., "agent" senders must have valid IDs; "system" is always valid).
+   - Allows application-level validation of the sender category.
    - Enables filtered views ("show only agent messages" or "system alerts only") without string parsing.
 
 4. **`interaction_id` for grouping.**
-   - Enables undo/redo on related messages (e.g., canceling all build-failure notifications from one dispatch).
-   - Supports consolidation: multiple small notifications can be collapsed into one summary message.
+   - `getInboxByInteraction()` retrieves related messages in chronological order.
 
 5. **Persistent `sender_name` at write-time.**
    - Operator may rename agents or disable them; storing the name ensures historical accuracy.
-   - UI doesn't need to perform runtime lookups on archived inboxes.
+   - Future consumers can render the stored name without a runtime agent lookup.
 
 6. **Unix timestamps (milliseconds) instead of ISO strings.**
    - Enables range queries (`sent_at BETWEEN ? AND ?`) without parsing.
    - Smaller column footprint; easier to sort.
    - Downside: not human-readable; UI must convert to locale strings.
 
-### Entity Relationships
+### Integration Status
 
-- **inbox_entries ← dispatch WI feedback:** A failed dispatch may create multiple inbox entries (error summary, retry recommendation, logs snippet). Threaded via `interaction_id`.
-- **inbox_entries ← PR reviews:** Humans and auto-review agents post comments; summarized as inbox alerts to project owners via `interaction_id` per-PR.
-- **inbox_entries ← consolidation:** `engine/consolidation.js` reads inbox entries to extract `agent:` frontmatter and route findings into per-agent knowledge files.
+The table currently has no foreign keys and `engine/inbox-store.js` has no production callers. Dispatch feedback, PR notifications, dashboard inbox views, and consolidation are potential consumers, not implemented relationships. Until those call sites migrate, this table is not the source of truth for `notes/inbox/` or agent steering inbox files.
 
 ## Performance Considerations
 
 ### Indexing Strategy
 
-**Current indexes (recommended):**
-- `idx_recipient_sent` on `(recipient_session_id, sent_at DESC)` — enables efficient "unread count" and "latest N messages" queries without table scans.
-- `idx_interaction` on `(interaction_id)` — enables grouping/dedup queries (e.g., "was this interaction already notified?").
+**Current indexes (created by migration 019):**
+- `idx_inbox_recipient_sent` on `(recipient_session_id, sent_at DESC)` — supports recipient-scoped chronological reads.
+- `idx_inbox_interaction` on `(interaction_id)` — supports grouping by interaction.
 - PK `id` is implicit index.
 
 **Query patterns:**
-- **Unread count per session:** `SELECT COUNT(*) WHERE recipient_session_id = ? AND unread = 1` → must scan `idx_recipient_sent` to avoid full table.
-- **Latest messages:** `SELECT * WHERE recipient_session_id = ? ORDER BY sent_at DESC LIMIT 20` → seeks on `idx_recipient_sent` DESC.
-- **Thread view:** `SELECT * WHERE interaction_id = ? ORDER BY sent_at` → seeks on `idx_interaction`, then sorts in application or via secondary index.
-- **Cleanup:** `DELETE WHERE sent_at < ? AND unread = 0` → full table scan (acceptable; cleanup is infrequent, low-priority background task).
+- **Unread count per session:** `SELECT COUNT(*) ... WHERE recipient_session_id = ? AND unread = 1` narrows by recipient, then filters `unread`.
+- **Latest messages:** `SELECT * ... WHERE recipient_session_id = ? ORDER BY sent_at DESC LIMIT ? OFFSET ?` uses `idx_inbox_recipient_sent`.
+- **Thread view:** `SELECT * ... WHERE interaction_id = ? ORDER BY sent_at ASC` uses `idx_inbox_interaction`, then sorts matching rows.
+- **Cleanup:** `deleteInboxEntriesOlderThan(timestampMs, { unreadOnly })` deletes all older rows by default or only rows with `unread = 1`; no production cleanup job calls it yet.
 
 **Missing indexes (future optimization):**
 - `idx_sender_id` — if queries like "messages from this agent" are common, consider adding.
 - `idx_unread` — if badge ("N unread") is a hot query, consider combining with recipient (`idx_recipient_unread` on `(recipient_session_id, unread)`).
 
-### Size Estimates & Cleanup
+### Cleanup
 
-- **Row size:** ~500–2000 bytes (summary + content; content can be verbose with logs/code snippets).
-- **Growth:** ~5–50 entries/day (depends on agent activity and verbose flagging).
-- **Retention:** No automatic cleanup; operators may archive/export and manually delete aged entries. Engine does NOT auto-prune.
-- **Recommended**: Implement a dashboard setting to soft-delete entries older than N days (default 30) with an undo/export option.
+- **Retention:** No automatic cleanup is wired. The store exposes explicit single, batch, and age-based hard-delete helpers.
 
 ## Migration & Backward Compatibility
 
-- **Migration 018 or later** creates `inbox_entries` as part of SQL state cutover. Legacy `inbox/` Markdown files are NOT imported; operators must re-send or manually recreate critical messages.
-- **No schema versioning needed** for now; table is immutable-append-only (reads/writes only).
+- **Migration 019** creates `inbox_entries` and its two secondary indexes. It does not import existing Markdown inbox files.
+- The store supports inserts, read/unread updates, notification timestamps, and hard deletes. Every mutator attempts a best-effort `inbox` state event after a real change so dashboard cache versions can advance once consumers are wired.
 
 ## Related Code
 
-- **Writes:** `engine/inbox-store.js` (primary mutator; uses `getDb()` and `emitStateEvent`).
-- **Reads:** `engine/queries.js#getInboxForSession()`, dashboard `/api/inbox`, `engine/consolidation.js`.
-- **UI:** `dashboard/pages/inbox.html`, `dashboard/js/inbox.js`.
-
+- **Schema:** `engine/db/migrations/019-inbox-entries.js`.
+- **Store:** `engine/inbox-store.js` (reads, transactional mutators, and best-effort `emitStateEvent('inbox', ...)` after real changes).
+- **Consumers:** none in production yet.

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Implemented**
 
-> **Implementation status (as of 2026-06):** Migrations 001–018 implement the full SQLite cutover. `engine/state.db` is the sole runtime-state authority; migration 018 validates the database, records a durable cutover marker, and retires known legacy mirrors. Historical migrations retain one-time JSON import support. Normal runtime never reads or writes retired mirrors. `minions state check`, `backup`, and `export` provide operations support; explicit offline recovery import is available through `minions state import-legacy-json <dir> --confirm`. Sections 1–3 below are retained as historical design rationale.
+> **Implementation status:** Migrations 001–024 implement the full SQLite cutover and final compatibility cleanup. `engine/state.db` is the sole runtime-state authority; migration 018 records the cutover, migrations 020–024 absorb the remaining scoped/archive/session state and one-time PRD collision repair. Historical migrations retain one-time JSON import support. Normal runtime never references retired mirrors. `minions state check`, `backup`, and `export` provide operations support; explicit offline recovery import is available through `minions state import-legacy-json <dir> --confirm`. Sections 1–3 below are retained as historical design rationale.
 
 ## Executive Summary
 

package/docs/documentation-audit-2026-07-09.md

@@ -13,11 +13,11 @@ canonical data, or misunderstand routing and dashboard behavior.
 |---|---|---|
 | Node.js 18+ was sufficient | Node.js 22.5+ is required for `node:sqlite` | `package.json:68` |
 | Agent dispatch was described as Claude-only | Copilot is the default fleet runtime; Claude and Codex remain supported | `engine/shared.js:3520`, `engine/runtimes/index.js` |
-| Root and per-project JSON trackers were described as primary state | Migrated runtime state is primary in `engine/state.db`; JSON trackers are passive mirrors | `engine/dispatch-store.js:49-68`, `CLAUDE.md` "State storage" |
+| Root and per-project JSON trackers were described as primary state | `engine/state.db` is the sole runtime-state authority; retired trackers are migration inputs only | `engine/db/migrations/018-sql-only-cutover.js`, `CLAUDE.md` "State storage" |
 | `minions preflight` was documented as a public command | `minions doctor` is public; lighter checks run internally during initialization and startup | `bin/minions.js:1207-1264`, `engine/cli.js:232-255` |
 | Git repository host default was documented as ADO | The fallback host is GitHub | `engine/projects.js:504`, `engine/projects.js:564` |
 | `WORK_TYPE` documentation omitted complex build fixes | Added `BUILD_FIX_COMPLEX` | `engine/shared.js:4370-4396`, `routing.md:10-28` |
-| Command Center sessions were described as a JSON-file store | Sessions are stored in SQLite; the JSON file is a mirror | `engine/shared.js:1830`, `engine/db/migrations/011-remaining-state.js` |
+| Command Center sessions were described as a JSON-file store | Per-tab and global sessions are stored only in SQLite | `engine/small-state-store.js`, `engine/db/migrations/022-global-cc-session.js` |
 | Watches were described as checking every three ticks and persisting to JSON | The default cadence is 18 ticks; persistence routes through the SQL watch store | `engine/shared.js` `watchPollEvery`, `engine/watches-store.js` |
 | Two local documentation links targeted files that are not shipped | Removed the runtime `notes.md` link and the stale managed-spawn plan link | `docs/README.md`, `docs/managed-spawn.md` |
 

package/docs/engine-restart.md

@@ -10,11 +10,11 @@ When the engine restarts, it loses its in-memory process handles (`activeProcess
 
 | State | Storage | Survives Restart |
 |-------|---------|-----------------|
-| Dispatch queue (pending/active/completed) | `engine/state.db` (`dispatches`; `engine/dispatch.json` is a passive mirror) | Yes |
+| Dispatch queue (pending/active/completed) | `engine/state.db` (`dispatches`) | Yes |
 | Agent status (working/idle/error) | Derived from `engine/state.db` | Yes |
 | Agent live output | `agents/*/live-output.log` | Yes (mtime used for orphan cleanup) |
 | Process handles (`ChildProcess`) | In-memory Map | **No** |
-| Cooldown timestamps | In-memory Map | **No** (repopulated from `engine/cooldowns.json`) |
+| Cooldown timestamps | In-memory Map + `engine/state.db` | Yes (repopulated from SQL) |
 
 ## Protection Mechanisms
 
@@ -37,7 +37,20 @@ After the grace period expires, a dispatch with a tracked live process keeps run
 
 If there is no live tracked process, the engine uses `live-output.log` mtime as indirect evidence. Once the log is stale for `engine.heartbeatTimeout`, the dispatch is treated as an orphan and marked failed.
 
-### 3. Stop Warning
+### 3. Intentional Restart Drains Pooled Leases
+
+`engine.js stop` writes a shutdown request into `control.json`; it does not
+tree-kill the daemon. The running engine stops dispatching new work and drains
+fleet ACP-pool leases for up to `engine.shutdownTimeout` (5 minutes by
+default). Cold-spawn agents are detached and are not part of this wait, so they
+can survive for restart reattachment. A pooled lease cannot be reattached:
+when the drain deadline expires it is cancelled and terminalized as a
+retryable timeout before the old engine exits.
+
+Unexpected crashes remain fail-safe: persisted `item.pooled` dispatches never
+trust the worker PID and are reaped through the normal retry path on startup.
+
+### 4. Stop Warning
 
 `engine.js stop` checks for active dispatches and warns:
 ```
@@ -45,16 +58,15 @@ WARNING: 2 agent(s) are still working:
   - Dallas: [office-bohemia] Build & test PR PR-4959092
   - Rebecca: [office-bohemia] Review PR PR-4964594
 
-These agents will continue running but the engine won't monitor them.
-On next start, they'll get a 20-min grace period before being marked as orphans.
+Detached agents will continue for restart reattachment; pooled agents will drain before exit.
 To kill them now, run: node engine.js kill
 ```
 
-### 4. Exponential Backoff on Failures
+### 5. Exponential Backoff on Failures
 
 If an agent is killed as an orphan and the work item retries, cooldowns use exponential backoff (2^failures, max 8x) to prevent spam-retrying broken tasks.
 
-### 5. Crash-Loop Counter + Alert (W-mr2azk6i000y06e0)
+### 6. Crash-Loop Counter + Alert (W-mr2azk6i000y06e0)
 
 The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/supervisor.js#checkEngine` (dead-PID), `engine/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
 
@@ -80,7 +92,7 @@ T+0s     engine.js stop (warns about active agents)
          Engine process exits. Agents keep running as OS processes.
 
 T+30s    Code changes made. engine.js start.
-         Engine reads dispatch.json — finds 2 active items.
+         Engine reads SQL dispatch state — finds 2 active items.
          Sets grace period: 20 min from now.
          Logs: "2 active dispatch(es) from previous session"
 

package/docs/harness-mode.md

@@ -88,5 +88,5 @@ Within a single tick the standard scheduled-work dedup is keyed by `_scheduleId`
 
 - Tri-agent items are **schedule-driven** — there's no manual "fire a harness mission" entry point. Add a schedule with `harness_mode: "tri_agent"` to opt in.
 - Iteration pairs always reuse the original mission's artifact path, threshold, max-iterations, and rubric. The evaluator's verdict feedback is appended to the next generator's prompt.
-- Mission state lives entirely on disk: the work-items.json trio + the artifact file. No new DB tables.
+- Mission work-item state uses the existing SQL store; mission artifacts remain file-backed. No new tables are required.
 - Each iteration's evaluator is a separate work item, so dispatch retries, cooldowns, and steering apply normally to every role.

package/docs/managed-spawn.md

@@ -172,7 +172,7 @@ Single quotes (`'…'`) work the same way. No `powershell -Command "& '<path>' <
 ┌───────────────────────────────────────────────────────────────────┐
 │ 3. spawnManagedSpec(spec) per spec                                │
 │    - Uses the proven Windows detached-spawn pattern               │
-│    - Records each in engine/managed-processes.json (locked write) │
+│    - Records each in the SQL managed-process store                │
 │    - Stdio → engine/managed-logs/<name>.log (append fd, NOT pipe) │
 └───────────────────────────────────┬───────────────────────────────┘
                                     │
@@ -241,7 +241,7 @@ The list endpoint returns an ETag; pass it as `If-None-Match` on follow-up polls
 | Kill (PID terminated, removed from state) | `POST /api/managed-processes/kill` `{"name":"…"}` | Per-row "Kill" button |
 | Restart (kill old PID, respawn from saved state, kick first healthcheck) | `POST /api/managed-processes/restart` `{"name":"…"}` | Per-row "Restart" button |
 
-Killing a spec from outside Minions (raw `Stop-Process`) leaves a stale row in `managed-processes.json` until the next 30-tick sweep notices the dead PID. Prefer the API.
+Killing a spec from outside Minions (raw `Stop-Process`) leaves a stale SQL row until the next 30-tick sweep notices the dead PID. Prefer the API.
 
 ### View logs
 
@@ -282,9 +282,9 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js` (`ENGINE_DEFAUL
 
 ## Performance budget
 
-- **Per-tick contribution**: zero unless the 30-tick sweep fires. The sweep is `O(N)` over specs in `managed-processes.json` with one `process.kill(pid, 0)` per spec.
+- **Per-tick contribution**: zero unless the 30-tick sweep fires. The sweep is `O(N)` over managed specs with one `process.kill(pid, 0)` per spec.
 - **Healthcheck loops**: per-spec, self-scheduled (not tick-coupled). 10 specs × 1s pre-healthy cadence ⇒ 10 probes/s peak. Post-healthy drops to one probe per `healthBackoffSec` (30s).
-- **Lock contention** on `managed-processes.json`: writes batch on transitions (healthy ↔ unhealthy), and `last_health_at` only persists every `healthBackoffSec` to avoid flap. See [`test/perf/managed-spawn-load.test.js`](../test/perf/managed-spawn-load.test.js) for the 10-spec / 3-project load assertion.
+- **Write contention**: SQL updates batch on transitions (healthy ↔ unhealthy), and `last_health_at` only persists every `healthBackoffSec` to avoid flap. See [`test/perf/managed-spawn-load.test.js`](../test/perf/managed-spawn-load.test.js) for the 10-spec / 3-project load assertion.
 - **Hard cap recommendation**: 50 specs across one engine. Above that, `process.kill(pid, 0)` shells out enough on Windows to dent tick latency.
 
 ## Source map

package/docs/onboarding.md

@@ -30,8 +30,7 @@ minions config set-cli claude
 ```
 
 `minions init` creates `~/.minions/`. Primary migrated runtime state lives in
-`engine/state.db` (SQLite, WAL mode). Files such as `engine/dispatch.json` and
-`engine/metrics.json` are passive diagnostic mirrors; `engine/control.json`
+`engine/state.db` (SQLite, WAL mode). Retired JSON mirrors are removed; `engine/control.json`
 remains a live JSON control file.
 
 ## 2. Link a project

package/docs/pr-comment-followup.md

@@ -66,7 +66,7 @@ playbook contract. The poller is unchanged; the carve-out is purely additive.
    - Validates `meta.pr_followup` shape (all four fields required, ≤ 512
      chars each). Malformed → `400 { error: "<message>" }`.
    - Checks for an existing follow-up with the same `parent_comment_id` in
-     the target project's `work-items.json`. Duplicate → `409 {
+     the target project's SQL work-item scope. Duplicate → `409 {
      error: "followup_already_dispatched", existingWiId: "W-…" }` (no second WI
      created).
    - Persists the validated `meta.pr_followup`, and stores
@@ -104,7 +104,7 @@ playbook contract. The poller is unchanged; the carve-out is purely additive.
    ```
    `engine/lifecycle.js processCompletionFollowups` logs each entry at `info`
    and warns if the claimed `wi_id` is missing from any project's
-   `work-items.json` (catches reverted or non-landing dispatches).
+   SQL work-item store (catches reverted or non-landing dispatches).
 
 ## Server contract reference
 
@@ -131,7 +131,7 @@ Any missing/empty field, oversized field, or non-string value → `400` with a
 descriptive message.
 
 **Dedup.** A second `POST /api/work-items` with the same
-`meta.pr_followup.parent_comment_id` in the same project's `work-items.json`
+`meta.pr_followup.parent_comment_id` in the same project's SQL scope
 returns `409 { error: "followup_already_dispatched", existingWiId: "<id>" }`.
 This is checked under the same `mutateWorkItems` lock used to insert the new
 WI, so two pollers racing on the same comment cannot both win.

package/docs/pr-review-fix-loop.md

@@ -5,7 +5,7 @@ How the engine manages the lifecycle of a PR from creation through review, fix,
 ## 1. Implement agent creates PR
 
 - Agent pushes code, output contains PR URL
-- `syncPrsFromOutput()` (lifecycle.js) extracts URL via regex, creates `pull-requests.json` entry, links to work item via `addPrLink()`
+- `syncPrsFromOutput()` (lifecycle.js) extracts the URL, creates a SQL PR record, and links it to the work item via `addPrLink()`
 
 ## 2. Engine discovers PR needs review
 

package/docs/proposals/repo-pool-for-live-checkout.md

@@ -87,8 +87,7 @@ additive.
 ### Persistence (survives restart)
 
 - Dispatch state lives in **SQLite** `engine/state.db` `dispatches` table via
-  `engine/dispatch-store.js` (`readDispatchSectioned` / `applyDispatchMutation`),
-  mirrored read-only to `dispatch.json` (source: `engine/dispatch-store.js:49,244,298`).
+  `engine/dispatch-store.js` (`readDispatchSectioned` / `applyDispatchMutation`).
   Each active dispatch is one JSON record. **Because `liveProjectsInUse` is
   rebuilt from `dispatch.active` every tick, recording the claimed enlistment
   path on the active dispatch record makes the per-path claim automatically

package/docs/qa-runbook-lifecycle.md

@@ -9,7 +9,7 @@ W-mpdad3mq000m53bb).
 
 ## Runbook location
 
-`qa-runbooks.json` (engine state, JSON list keyed by `id`). Each entry:
+`<MINIONS_DIR>/projects/<project-name>/runbooks/<runbook-id>.json`. Each entry:
 `{ id, name, target, steps, expectedArtifacts, createdAt, createdBy }`.
 CRUD via `GET/POST /api/qa/runbooks` (POST returns the new runbook with
 engine-assigned `id`). `target` is a name from `/api/managed-processes` or
@@ -97,7 +97,7 @@ plain prose, the engine sets up a live target, an agent drafts a
 runner-native test file, and (with user approval) a second agent executes
 it. Sessions are a thin orchestration layer on top of the same
 `managed-spawn` + `qa-run-result.json` infrastructure that powers
-runbooks above — they reuse `qa-runs.json`, `engine/qa-artifacts/`, and
+runbooks above — they reuse the SQL QA-run store, `engine/qa-artifacts/`, and
 the existing `engine/lifecycle.js#runPostCompletionHooks` qa-run sidecar
 hook. Surfaced on `/qa` (sessions card list above the runbooks/runs
 tables) and proxied by the Command Center natural-language shortcut.
@@ -161,7 +161,7 @@ routing default):
    **Multi-project fan-out (W-mpq6xqzj000606d0):** when `spec.projects`
    contains more than one project name, SETUP is fanned out — one work item
    per project, queued in parallel into each project's own
-   `work-items.json`. The first project (`spec.projects[0]`) is the
+   the target project's SQL work-item scope. The first project (`spec.projects[0]`) is the
    **primary** (`meta.qaSession.primary === true`); the rest are
    **co-services** (`primary === false`). Each WI's
    `meta.qaSession.coServices` lists the co-service project names (only the
@@ -230,7 +230,7 @@ errors are mapped to HTTP via `_qaSessionsErrorToStatus`:
 
 ## File locations
 
-- **Session state**: `engine/qa-sessions.json` (single file, all projects,
+- **Session state**: `engine/state.db` `qa_sessions` (all projects,
   capped at `QA_SESSIONS_MAX_RECORDS = 500` via `createSession`-time
   rotation by `createdAt`).
 - **Drafted test files**: `engine/qa-tests/<sessionId>/test.<ext>`. Created

package/docs/qa-runbooks.md

@@ -11,7 +11,7 @@ Runbooks are per-project test plans. Each runbook is a single JSON file at:
 <MINIONS_DIR>/projects/<project-name>/runbooks/<runbook-id>.json
 ```
 
-This mirrors the `projects/<name>/pull-requests.json` precedent — anything
+This follows the project-scoped PR-store precedent — anything
 scoped to a single project lives under its `projects/<name>/` state dir
 rather than a root-level `runbooks/` directory. Two reasons:
 
@@ -99,7 +99,7 @@ unlink).
 
 The deferred follow-up items (W-mpeiwz6k0005bf34-b/c/d) have since landed. Brief pointers — see [CLAUDE.md](../CLAUDE.md) → "QA validation runs" for the deep dive:
 
-- **Run dispatch + persistence** (`engine/qa-runs.js`): `POST /api/qa/runbooks/run` creates a `qa-runs.json` record with `status ∈ pending|dispatched|running|passed|failed|error` and dispatches a `qa-validate` work item against the runbook's `target`. Read via `GET /api/qa/runs?limit=N&status=...` and `GET /api/qa/runs/<id>`.
+- **Run dispatch + persistence** (`engine/qa-runs.js`): `POST /api/qa/runbooks/run` creates a SQL QA-run record with `status ∈ pending|dispatched|running|passed|failed|error` and dispatches a `qa-validate` work item against the runbook's `target`. Read via `GET /api/qa/runs?limit=N&status=...` and `GET /api/qa/runs/<id>`.
 - **Artifact contract**: the `qa-validate` agent writes `agents/<id>/qa-run.json` before exit; the engine copies listed files into `engine/qa-artifacts/<runId>/` and serves them via `GET /api/qa/artifacts/<runId>/<file>` (path-traversal-gated, 403 on escape). Per-file size cap: `engine.qaArtifactsMaxBytes`.
 - **UI**: `/qa` dashboard page (`dashboard/pages/qa.html`, `dashboard/js/qa.js`) polls `GET /api/qa/runs` every 5s while active; auto-detects screenshots/videos/logs for inline preview.
 - **Playbook**: `playbooks/qa-validate.md` (routed via the synthetic `qa-validate` task-type in `routing.md`).

package/docs/rfc-completion-json.md

@@ -1,8 +1,11 @@
 # RFC: `completion.json` — Structured Agent Control-Plane Protocol
 
-> Author: Dallas (Engineer) | Date: 2026-04-27 | Status: **awaiting-approval**
+> Author: Dallas (Engineer) | Date: 2026-04-27 | Status: **historical design record**
 > Plan: `minions-2026-04-27.json` | Plan item: `P-7a8b9c1d` (SEC-07 / C1)
 > Note: this RFC lives in `docs/` rather than `plans/` because the repo's `.gitignore` excludes `plans/`. The task description explicitly allowed "or similar".
+> Storage references below describe the pre-SQL implementation evaluated by the
+> RFC. Current completion processing writes one-shot sidecars and persists runtime
+> records in `engine/state.db`.
 
 ## TL;DR
 

package/docs/runtime-adapters.md

@@ -139,7 +139,7 @@ process or a pooled lease. Assignment strategy, in order:
 4. Otherwise the request queues FIFO until a `release()` or worker crash frees
    a slot.
 
-Dispatch records persist `item.pooled = true` on disk (`dispatch.json`), not
+Dispatch records persist `item.pooled = true` in SQLite, not
 just the in-memory `activeProcesses._pooled` flag (which is wiped on engine
 restart) — the on-disk flag is what tells the restart-reattach path
 (`engine/cli.js`) that a live worker PID is a pooled lease, not a resumable

package/docs/self-improvement.md

@@ -12,7 +12,7 @@ Agent completes task
   ├─ 1. Learnings Inbox        → notes.md (all future agents see it)
   ├─ 2. Per-Agent History       → history.md (agent sees its own past)
   ├─ 3. Review Feedback Loop    → author gets reviewer's findings
-  └─ 4. Quality Metrics         → engine/metrics.json (tracks performance)
+  └─ 4. Quality Metrics         → engine/state.db (tracks performance)
 ```
 
 ## 1. Learnings Inbox → notes.md
@@ -182,7 +182,7 @@ Human comments on PR with "@minions fix the error handling here"
 
 ## 5. Quality Metrics
 
-The engine tracks per-agent performance metrics in `engine/metrics.json`. Updated after every task completion and PR review.
+The engine tracks per-agent performance metrics in the SQL metrics store. It updates them after every task completion and PR review.
 
 ### Metrics tracked
 
@@ -330,7 +330,7 @@ When a git merge or rebase produces conflicts in yarn.lock.
 | Stale flag auto-reset | 5 min (300,000ms) | `_consolidationInFlight` flag auto-resets after this duration to unblock future runs |
 | notes.md max size | 50KB | Trims to cap above this; overflow archived to `notes/archive/notes-overflow.md` (not discarded) |
 | Agent history entries | 20 | Max entries kept in history.md |
-| Metrics file | `engine/metrics.json` | Auto-created on first completion |
+| Metrics store | `engine/state.db` (`metrics`) | Created by database migrations |
 
 ## Files
 
@@ -340,6 +340,5 @@ When a git merge or rebase produces conflicts in yarn.lock.
 | `notes/archive/*.md` | Archived inbox files | Engine (consolidation) |
 | `notes.md` | Accumulated team knowledge | Engine (consolidation) |
 | `agents/<name>/history.md` | Per-agent task history | Engine (post-completion) |
-| `engine/metrics.json` | Quality metrics per agent | Engine (post-completion + review) |
+| `engine/state.db` `metrics` | Quality metrics per agent | Engine (post-completion + review) |
 | `notes/inbox/feedback-*.md` | Review feedback for authors | Engine (post-review) |
-

package/docs/shared-lifecycle-module-map.md

@@ -1,6 +1,8 @@
 # `engine/shared.js` / `engine/lifecycle.js` module-boundary audit
 
-**Status:** documentation only — no function bodies were moved or edited as part of this audit.
+**Status:** historical point-in-time audit. It predates the SQL-only state cutover cleanup;
+removed JSON-routing helpers and old line numbers below are retained only as audit evidence, not
+as the current API contract. Use `engine/shared.js` and `engine/lifecycle.js` for current symbols.
 
 **Scope:** `engine/shared.js` (9,877 lines, 338 top-level functions) and `engine/lifecycle.js`
 (6,988 lines, 121 top-level functions) as of this audit's HEAD commit. The PRD item that requested

package/docs/slim-ux/architecture-suggestions.md

@@ -81,7 +81,7 @@ shape:
 ```
 
 Plus `/api/events?since=…&limit=…` for paged reads. The engine already writes most of these
-moments to `engine/log.json` (the audit ring buffer); we just need to enrich them and expose
+moments to the SQL log store; we just need to enrich them and expose
 them. The History panel becomes one fetch.
 
 **Cost.** ~1.5 days. The hard part is catching every event-emit site — dispatch start, dispatch
@@ -98,8 +98,7 @@ each lifecycle path emits an event.
 **Problem.** Carlos called out "Work Items" and "Pipelines" as conceptually overlapping in the
 existing UI. Looking at the data: a Pipeline is a sequence of stages where each stage *is*
 either a Work Item, a Meeting, or a Plan. So a Pipeline isn't really a separate concept — it's
-a Work Item with a stage list. Yet they have entirely separate stores
-(`engine/dispatch.json` vs `engine/pipeline-runs.json`), separate API surfaces
+a Work Item with a stage list. Yet they have separate SQL tables, separate API surfaces
 (`/api/work-items*` vs `/api/pipelines*`), and separate UIs.
 
 **Proposal.** Don't merge the *storage* — that's a deep migration. Instead, introduce a
@@ -199,11 +198,11 @@ becomes a "freshness" badge on the Knowledge entry rather than a separate tab.
 
 **Problem.** Schedule = "fire on a cron pattern." Watch = "fire when a condition flips." They
 share most of the lifecycle (definition, fire history, pause/resume, expire/stopAfter). The
-two state files (`schedule-runs.json` / `watches.json`) and parallel CRUD APIs add maintenance
+two SQL stores and parallel CRUD APIs add maintenance
 without adding real concepts.
 
-**Proposal.** Generalize to **Trigger**, with two `kind`s: `cron` and `event`. Backend stays
-in two files for now (avoid the migration), but the API and UI present them as one.
+**Proposal.** Generalize to **Trigger**, with two `kind`s: `cron` and `event`. Backend tables
+stay separate, but the API and UI present them as one.
 
 ```jsonc
 {