@yemi33/minions 0.1.2379 → 0.1.2380

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
 {

package/docs/slim-ux/concepts.md

@@ -33,7 +33,7 @@ Watches, etc. It is the primary human-to-fleet interface.
 
 **Where it lives.**
 - System prompt: `prompts/cc-system.md`
-- Per-tab session state: `engine/cc-sessions.json` (also legacy `engine/cc-session.json`).
+- Per-tab and global session state: `engine/state.db` (`cc_sessions`).
 - Direct CLI invocation: `engine/llm.js` `callLLM({ direct: true })` — bypasses
   `spawn-agent.js` and runs the runtime CLI itself.
 
@@ -70,10 +70,8 @@ Plan, Note, Schedule, Watch, Knowledge entry, Pinned note). Per-call cap is
 the home page eventually reduce to a Work Item.
 
 **Where it lives.**
-- Central queue: `work-items.json` (root).
-- Per-project queue: `projects/<name>/work-items.json` (`projectWorkItemsPath`,
-  `engine/shared.js` line ~1530).
-- In-flight copy: `engine/dispatch.json` (`pending[] / active[] / completed[]`).
+- Durable records: `engine/state.db` `work_items`, keyed by central/project scope.
+- In-flight dispatch rows: `engine/state.db` `dispatches`.
 
 **Backing classes / functions.**
 - Status constants: `engine/shared.js` line 1348 (`WI_STATUS`).
@@ -327,7 +325,7 @@ engine drops a Work Item into the queue.
 
 **Where it lives.**
 - Definitions: `config.json` `schedules: []` (3-field cron `min hour dow`).
-- Last-run history: `engine/schedule-runs.json`.
+- Last-run history: `engine/state.db` `schedule_runs`.
 
 **Backing classes / functions.**
 - Cron parser: `engine/scheduler.js`
@@ -361,7 +359,7 @@ analogous to **Watch** (event-driven instead of time-driven).
 (merged, build passes, build fails, status changes, new comments, vote changes). Watches are
 event-driven, schedules are time-driven.
 
-**Where it lives.** `engine/watches.json` (`engine/watches.js` line 17 `_watchesPath`).
+**Where it lives.** `engine/state.db` `watches`.
 
 **Backing classes / functions.**
 - Status constants: `engine/shared.js` line 1380 (`WATCH_STATUS`).
@@ -389,11 +387,11 @@ A merged-PR watch is the canonical "tell me when X ships" primitive.
 
 **What it is.** A multi-stage workflow. Stages can be a Work Item (`task`), a `meeting`, or a
 `plan`. Stages can declare dependencies on previous stages. Pipelines run via triggers (manual,
-schedule, watch) and persist their state in `pipeline-runs.json`.
+schedule, watch) and persist run state in SQLite.
 
 **Where it lives.**
 - Definitions: `pipelines/*.json` (one file per pipeline).
-- Run state: `engine/pipeline-runs.json`.
+- Run state: `engine/state.db` `pipeline_runs`.
 
 **Backing classes / functions.**
 - Dirs: `engine/pipeline.js` lines 19–24 (`PIPELINES_DIR`, `PIPELINE_RUNS_PATH`, `PLANS_DIR`,
@@ -427,7 +425,7 @@ unrelated to ADO/GitHub Actions pipelines, even though the word collides.
 dispatch holds the agent's PID, prompt sidecar path, worktree path, and current status until the
 process exits.
 
-**Where it lives.** Inside `engine/dispatch.json`'s `active[]` array.
+**Where it lives.** Active rows in `engine/state.db` `dispatches`.
 
 **Backing classes / functions.**
 - `mutateDispatch`: `engine/dispatch.js` line 60 (the only safe RMW path).
@@ -450,7 +448,7 @@ tick. Read shape via `/api/status` (line 6838).
 
 ## 13. Dispatch Queue
 
-**What it is.** The three-bucket structure inside `engine/dispatch.json`:
+**What it is.** The sectioned view reconstructed from SQL dispatch rows:
 
 - `pending[]` — admitted Work Items waiting on agent / dependency / cooldown / budget.
 - `active[]` — currently spawned.
@@ -460,7 +458,7 @@ The queue's invariants are: max concurrent (default 5), per-PR / per-branch lock
 agents fighting on the same branch, dependency-aware spawning (`depends_on` IDs must be done
 first), retry on failure up to `ENGINE_DEFAULTS.maxRetries`.
 
-**Where it lives.** `engine/dispatch.json`.
+**Where it lives.** `engine/state.db` `dispatches`.
 
 **Backing classes / functions.** All in `engine/dispatch.js`. Mutation only via `mutateDispatch`
 line 60. Queue dedupe keys: `getDispatchProjectKey` line 80, `getPrDispatchTargetKey` line 85,
@@ -502,12 +500,11 @@ record). It also feeds **Pull Request** sync (`pr` field).
 
 ## 15. Pull Request (as tracked in minions)
 
-**What it is.** A row in `projects/<name>/pull-requests.json`. Tracks status, vote tally, build
+**What it is.** A project-scoped row in the SQL PR store. Tracks status, vote tally, build
 state, review verdict, and the work item that created it. *Not* the GitHub/ADO PR itself —
 minions polls the host and writes a sanitized snapshot here.
 
-**Where it lives.** `projects/<name>/pull-requests.json` (`projectPrPath`, `engine/shared.js`
-line 1546). Cross-project links also tracked in `engine/pr-links.json`.
+**Where it lives.** `engine/state.db` `pull_requests`; cross-project links use `pr_links`.
 
 **Backing classes / functions.**
 - Status / pollable constants: `engine/shared.js` line 1372 (`PR_STATUS`,
@@ -541,7 +538,7 @@ Examples: Ripley (architect / explorer), Dallas (engineer), Lambert (analyst), R
 - Default roster: `engine/shared.js` line 1486 (`DEFAULT_AGENTS`).
 - Charter: `agents/<id>/charter.md` — read by `getAgentCharter` (`engine/queries.js` line 505).
 - Per-agent config (cli, model, budget, skills): `config.json` `agents.<id>`.
-- Metrics: `engine/metrics.json` (per-agent token / cost / quality / runtime).
+- Metrics: `engine/state.db` `metrics` (per-agent token / cost / quality / runtime).
 
 **Backing classes / functions.**
 - Charter loader: `engine/queries.js` line 505.
@@ -569,14 +566,14 @@ gets which work type.
 
 **Where it lives.**
 - Definitions: `config.json` `projects: []`.
-- State: `projects/<name>/{work-items.json, pull-requests.json}`.
+- Runtime records: project-scoped rows in `engine/state.db`.
 - Removal artifact: `projects/.archived/<name>-YYYYMMDD/`.
 
 **Backing classes / functions.**
 - Helpers: `engine/shared.js`
-  - `getProjects` (~line 1502)
-  - `projectStateDir`, `projectWorkItemsPath` (~line 1530)
-  - `projectPrPath` (line 1546).
+  - `getProjects`
+  - `stateScope`, `readWorkItems`, `readPullRequests`
+  - `projectStateDir` for file-backed project definitions/artifacts.
 - Removal: `engine/projects.js` `removeProject` (canonical teardown — never edit `config.json`
   directly).
 
@@ -658,13 +655,14 @@ consolidates the **Inbox**, and so on. It's also the gatekeeper for control stat
 
 **Where it lives.**
 - Process: `engine.js` (root).
-- State: `engine/control.json` (mode), `engine/log.json` (audit ring buffer, max 2500 trimmed
-  to 2000), `engine/metrics.json` (counters), `engine/dispatch.json` (queue).
+- State: `engine/state.db` (logs, metrics, queues, watches, schedules, PRDs) plus
+  `engine/control.json` for process coordination.
 
 **Backing classes / functions.**
 - Tick: `engine.js` (top-level `tick()`).
 - Defaults: `engine/shared.js` line 860 (`ENGINE_DEFAULTS`).
-- Concurrency caps: `mutateJsonFileLocked` for all shared-JSON RMW.
+- Concurrency: SQLite transactions for runtime records; file locks only for intentionally
+  file-backed definitions and coordination sidecars.
 - Restart re-attach: PID files in `engine/tmp/pid-<id>.pid` + `live-output.log` mtimes,
   20-min grace.
 
@@ -839,6 +837,6 @@ Pipeline (stages: task / meeting / plan) ──► spawns Work Items / Meetings
 Schedule (cron) ──► spawns Work Items
 Watch (event)   ──► spawns notifications / Work Items / pipeline-continuations
 
-Engine reads:  routing.md, config.json, all state JSON
-Engine writes: control.json, log.json, metrics.json, dispatch.json, project state files
+Engine reads:  routing.md, config.json, definitions, engine/state.db
+Engine writes: control.json, artifacts, engine/state.db
 ```

package/docs/watches.md

@@ -4,7 +4,7 @@ Persistent monitoring jobs that fire inbox notifications and follow-up actions w
 
 ## What a Watch Is
 
-A watch is a record persisted in `engine/state.db`; `engine/watches.json` is a passive diagnostic mirror. It binds:
+A watch is a record persisted in `engine/state.db`. It binds:
 
 | Field        | Purpose                                                                 |
 |--------------|-------------------------------------------------------------------------|
@@ -130,7 +130,7 @@ module.exports = {
 
 Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both dev checkouts and installed `~/.minions/` layouts. Missing folder is silent; per-file failures are isolated (load errors log a `WARN` line, don't abort boot). Tests can re-scan via the exported `_loadPluginTargetTypes()`.
 
-**Canonical plugin example:** [`watches.d/http.js`](../watches.d/http.js) (W-mp7i22mu00191b07) ships a generic `http` target type — point a watch at any URL or `{ url, method, headers, body, extract, expected, regex, timeoutMs }` config and the plugin exposes `status-change`, `value-change`, `value-equals`, `value-matches`, and `http-error` conditions. Auth headers support `{{env.GH_TOKEN}}`-style substitution at fetch time (secrets are never stored in `watches.json`). All conditions are change-based (`absoluteConditions: []`).
+**Canonical plugin example:** [`watches.d/http.js`](../watches.d/http.js) (W-mp7i22mu00191b07) ships a generic `http` target type — point a watch at any URL or `{ url, method, headers, body, extract, expected, regex, timeoutMs }` config and the plugin exposes `status-change`, `value-change`, `value-equals`, `value-matches`, and `http-error` conditions. Auth headers support `{{env.GH_TOKEN}}`-style substitution at fetch time (secrets are never persisted in watch records). All conditions are change-based (`absoluteConditions: []`).
 
 ## Tick Integration
 
@@ -222,10 +222,10 @@ CC will discover the endpoints from `GET /api/routes` and `POST /api/watches` wi
 
 When a watch fires:
 
-- `engine/watches.json` entry gets `triggerCount++`, `last_triggered=<ISO>`, `_lastTriggerMessage=<message>`, and a refreshed `_lastState`.
+- The SQL watch record gets `triggerCount++`, `last_triggered=<ISO>`, `_lastTriggerMessage=<message>`, and a refreshed `_lastState`.
 - An inbox file lands at `notes/inbox/<owner>/watch-<watchId>-<n>.md` (when `notify === 'inbox'`).
 - If `action` is set, a follow-up runs (work item, webhook POST, plan archive, ...) and writes `_lastActionResult` (`{ type, ok, summary, dispatchedItemId?, at }`) back onto the watch.
-- `engine.log.json` gets `Watch triggered: <id> — <message>` and `Watch <id> action <type>: <summary>`.
+- The SQL engine log gets `Watch triggered: <id> — <message>` and `Watch <id> action <type>: <summary>`.
 
 Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `stopAfter > 0` flips it to `expired` once `triggerCount >= stopAfter`.
 
@@ -236,14 +236,14 @@ Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `
 | Watch never fires                                                       | Check `status === 'active'`; check `last_checked` advancing each cycle; confirm engine tick is running and `interval` isn't longer than your test window |
 | `evaluateWatch` returns `"<label> <target> not found"`                   | `fetchEntity` got nothing back — wrong `target` (e.g. PR display id vs canonical id), the target type isn't loaded, or the underlying file (PR cache, plan PRD) doesn't exist |
 | `"Unknown target type"` / `"Unknown condition"`                         | The registry doesn't recognise the value. Check `GET /api/watches/target-types` to see what's registered server-side; condition must be in that target type's `conditions[]` |
-| Change condition fires immediately on first tick                        | Won't happen — baseline `_lastState` is captured on the first check before `evaluate` runs *(source: `engine/watches.js:434`)*. If you see this, suspect manual edits to `watches.json` |
+| Change condition fires immediately on first tick                        | Won't happen — baseline `_lastState` is captured on the first check before `evaluate` runs *(source: `engine/watches.js`)*. If you see this, inspect the persisted watch through the API |
 | Absolute watch fires forever instead of once                            | `stopAfter` is set to a non-zero value; only `stopAfter === 0` triggers fire-once expiration |
 | Action runs but inbox notification doesn't                              | `notify` field isn't `'inbox'`, or `owner` is empty. `notify` and `action` are independent — both can fire, or only one |
 | `_lastActionResult.ok === false` with `"unknown action type"`           | The `action.type` isn't registered. List with `listActionTypes()` / `GET /api/watches/action-types` |
 | Webhook action returns `"only http/https allowed"`                      | URLs must use `http://` or `https://` schemes; other protocols are rejected by design *(source: `engine/watch-actions.js` `WEBHOOK` handler)* |
-| Trigger fires but follow-up `dispatch-work-item` is missing              | Check the engine log for `Watch <id> action <type>: <summary>`. Common reasons: missing `title`, the project's `work-items.json` couldn't be written, or the WI landed in central `work-items.json` because no project was specified |
+| Trigger fires but follow-up `dispatch-work-item` is missing              | Check the engine log for `Watch <id> action <type>: <summary>`. Common reasons: missing `title`, a project-scope write failed, or the WI landed in the central scope because no project was specified |
 | Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watch-actions.js:482-484`)* |
-| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick *(source: `engine.js:7443`)*. Inspect `engine/log.json` for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
+| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick. Inspect the engine log for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
 
 ## See Also
 

package/docs/workspace-manifests.md

@@ -84,7 +84,7 @@ const { MEMORY_SCOPES, WORKSPACE_MANIFEST_DEFAULTS,
 
 ## Audit trail
 
-Because rejections route through the standard `completeDispatch(... ERROR ...)` path, the existing dispatch + inbox + dashboard timeline machinery already surfaces every manifest rejection. No new state file or event topic was added. Per-agent audit of what each minion actually touched can be derived from existing `engine/dispatch.json` records filtered by `failure_class === 'workspace-manifest-repo-forbidden'`.
+Because rejections route through the standard `completeDispatch(... ERROR ...)` path, the existing dispatch + inbox + dashboard timeline machinery already surfaces every manifest rejection. No new table or event topic was added. Per-agent audit can be derived from SQL dispatch records filtered by `failure_class === 'workspace-manifest-repo-forbidden'`.
 
 ## Rollout guidance
 

package/docs/worktree-lifecycle.md

@@ -45,7 +45,7 @@ recycle worktree dirs across branches.
 - **Return** in `onAgentClose` BEFORE `completeDispatch`:
   `git reset --hard HEAD` → `git clean -fd` → `git fetch origin <main>`
   → `git checkout --detach origin/<main>` → mark IDLE.
-- **State** at `engine/worktree-pool.json`; git ops outside any lock.
+- **State** in SQLite (`worktree_pool`); git ops outside the transaction.
 
 ## Ownership marker is never "dirty" (#284)
 

package/engine/abandoned-pr-reconciliation.js

@@ -20,7 +20,7 @@
  * The version-gated one-shot model gives us exactly what we need: re-probe
  * once per release that bumps `ENGINE_DEFAULTS.abandonedReconciliationVersion`,
  * then never again until the next bump. First boot after this lands cleans up
- * the historical false-flips; subsequent boots are a single state.json read +
+ * the historical false-flips; subsequent boots are a single state-marker read +
  * version compare → no-op.
  *
  * ## Why a separate WI from W-mp5trwh60008386d?
@@ -37,14 +37,13 @@
  * Errors here must NOT block boot — the catch in cli.js logs and continues.
  */
 
-const path = require('path');
 const shared = require('./shared');
 
 const { ENGINE_DEFAULTS, log, mutateEngineState, readEngineState } = shared;
 
 /**
  * Run the version-gated startup reconciliation pass. Idempotent across reruns
- * at the same code version: state.json gates re-execution.
+ * at the same code version: persisted engine state gates re-execution.
  *
  * @param {object} config — engine config (used to enumerate projects)
  * @param {object} [options]
@@ -82,7 +81,7 @@ async function runStartupReconciliation(config, options = {}) {
     const projects = shared.getProjects(config);
     projectCount = projects.length;
     for (const p of projects) {
-      const prs = shared.safeJsonArr(shared.projectPrPath(p));
+      const prs = shared.readPullRequests(p);
       preCount += prs.filter(pr =>
         pr.status === shared.PR_STATUS.ABANDONED && !pr._reconciliation404Confirmed
       ).length;
@@ -128,7 +127,7 @@ async function runStartupReconciliation(config, options = {}) {
         return state;
       });
     } catch (err) {
-      // State.json write failure is unfortunate but non-fatal: next boot will
+      // Marker persistence failure is non-fatal: next boot will
       // re-run the pass, which is idempotent (already-flipped PRs aren't
       // abandoned anymore, confirmed-404s carry the marker). Log and continue.
       log('warn', `Abandoned PR reconciliation: failed to persist version marker: ${err.message}`);