@yemi33/minions 0.1.2072 → 0.1.2074

package/docs/README.md

@@ -23,6 +23,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.
 - [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
+- [qa-runbook-lifecycle.md](qa-runbook-lifecycle.md) — End-to-end QA runbook lifecycle (W-mpeiwz6k0005bf34): runbook + run-record storage, `POST /api/qa/runbooks/run` dispatch into the `qa-validate` playbook, artifact contract, and how the `/qa` page mirrors managed-spawn observability.
 - [qa-runbooks.md](qa-runbooks.md) — Per-project QA runbook schema, storage layout (`projects/<name>/runbooks/<id>.json`), CRUD endpoints, run-record lifecycle, and the `qa-validate` agent sidecar contract.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
 - [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-05-25 against `engine.js` `tickInner()` (lines 6293-6947) and `routing.md`.
+> Last verified: 2026-05-28 against `engine.js` `tickInner()` and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -15,6 +15,7 @@ tick()
   1b. checkIdleThreshold()       Notify on excessive agent idleness
   1c. meetingTimeouts()          Advance round-based meetings whose timer fired
   2.  consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
+  2.1 autoSweepKb()              Periodic KB sweep (opt-in via engine.autoConsolidateMemory, 4h cadence)
   2.5 runCleanup()               Periodic cleanup (every 10 ticks ≈ 10min)
   2.52 sweepKeepProcesses()      keep_processes TTL/dead-PID sweep (every 30 ticks)
   2.53 sweepManagedSpawn()       managed_spawn TTL/dead-PID/log-rotate sweep (every 30 ticks)

package/docs/kb-sweep.md

@@ -114,6 +114,14 @@ Sweep state is mirrored to `engine/kb-sweep-state.json` so the dashboard can rec
 
 Memory still wins when present; the disk file is a fallback (source: [`engine/kb-sweep.js:298-320`](../engine/kb-sweep.js#L298), [`dashboard.js:4296-4354`](../dashboard.js#L4296)). A separate `engine/kb-swept.json` is written after each successful sweep with the human-readable summary line shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:407`](../engine/kb-sweep.js#L407)).
 
+## Automatic Periodic Sweep (opt-in)
+
+The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `false` — source: [`engine/shared.js:1835`](../engine/shared.js#L1835)):
+
+- When `engine.autoConsolidateMemory: true`, every tick the engine consults `shouldAutoSweep()` from [`engine/kb-sweep.js`](../engine/kb-sweep.js) and, when the 4-hour cadence has elapsed since the last completion, calls `spawnSweepRunnerDetached()` to fire-and-forget a fresh `engine/kb-sweep-runner.js` process (source: [`engine.js`](../engine.js) tick step 2.1).
+- The inbox→`notes.md` consolidation runs every tick *regardless* of this flag via `consolidateInbox()`; `autoConsolidateMemory` controls **only** the heavier `knowledge/` sweep.
+- The detached runner survives `minions restart` (same pattern used by the manual trigger), and the in-flight guard above prevents overlap with manual sweeps.
+
 ## Dashboard UI
 
 The KB page surfaces sweep state in two places:

package/engine/db/migrations/007-watches.js

@@ -0,0 +1,95 @@
+// engine/db/migrations/007-watches.js
+//
+// Phase 6: move engine/watches.json into a `watches` table.
+//
+// watches.json is an array of watch jobs polled every 3 ticks. Most
+// installs carry only a handful (operator-defined notifications, plan-
+// completion gates, etc), but the table is still indexed by status +
+// target_type so dashboards / future filters can do "show active PR
+// watches" without pulling the whole array.
+//
+// Schema is the same hybrid pattern Phases 2/3/5 use: typed projection
+// columns for the hot filters, a `data` TEXT blob for everything else.
+
+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;
+}
+
+module.exports = {
+  version: 7,
+  description: 'watches: schema + watches.json backfill',
+  up(db) {
+    db.exec(`
+      CREATE TABLE watches (
+        id              TEXT PRIMARY KEY,
+        target          TEXT,
+        target_type     TEXT,
+        condition       TEXT,
+        status          TEXT NOT NULL,
+        owner           TEXT,
+        created_at      INTEGER,
+        last_checked    INTEGER,
+        last_triggered  INTEGER,
+        data            TEXT NOT NULL,
+        updated_at      INTEGER NOT NULL
+      );
+      CREATE INDEX idx_watches_status       ON watches(status);
+      CREATE INDEX idx_watches_target_type  ON watches(target_type);
+      CREATE INDEX idx_watches_target       ON watches(target);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const watchesPath = path.join(minionsDir, 'engine', 'watches.json');
+    if (!fs.existsSync(watchesPath)) return;
+
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(watchesPath, 'utf8')); }
+    catch (e) {
+      throw new Error(`engine/db/007-watches: cannot parse watches.json: ${e.message}`);
+    }
+    if (!Array.isArray(raw)) return;
+
+    const now = Date.now();
+    const insert = db.prepare(`
+      INSERT INTO watches (id, target, target_type, condition, status, owner, created_at, last_checked, last_triggered, data, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    let inserted = 0;
+    for (const w of raw) {
+      if (!w || typeof w !== 'object' || !w.id) continue;
+      try {
+        insert.run(
+          String(w.id),
+          typeof w.target === 'string' ? w.target : (w.target == null ? null : JSON.stringify(w.target)),
+          w.targetType || null,
+          w.condition || null,
+          String(w.status || 'active'),
+          w.owner || null,
+          _toMs(w.created_at),
+          _toMs(w.last_checked),
+          _toMs(w.last_triggered),
+          JSON.stringify(w),
+          now,
+        );
+        inserted += 1;
+      } catch { /* duplicate id — skip defensively */ }
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v7: backfilled ${inserted} watches; watches.json kept as dual-write mirror`);
+  },
+};

package/engine/db/migrations/008-small-state.js

@@ -0,0 +1,155 @@
+// engine/db/migrations/008-small-state.js
+//
+// Phase 7: move the four remaining small state files into SQL in one
+// migration. Each gets its own table — the files are too dissimilar to
+// share schemas — but they ship together because they're all simple,
+// low-traffic singletons.
+//
+//   engine/schedule-runs.json      -> schedule_runs
+//   engine/pipeline-runs.json      -> pipeline_runs
+//   engine/managed-processes.json  -> managed_processes
+//   engine/worktree-pool.json      -> worktree_pool
+
+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: 8,
+  description: 'schedule_runs + pipeline_runs + managed_processes + worktree_pool',
+  up(db) {
+    db.exec(`
+      CREATE TABLE schedule_runs (
+        schedule_id  TEXT PRIMARY KEY,
+        data         TEXT NOT NULL,
+        updated_at   INTEGER NOT NULL
+      );
+
+      CREATE TABLE pipeline_runs (
+        pipeline_id  TEXT NOT NULL,
+        run_id       TEXT NOT NULL,
+        status       TEXT,
+        started_at   INTEGER,
+        data         TEXT NOT NULL,
+        updated_at   INTEGER NOT NULL,
+        PRIMARY KEY (pipeline_id, run_id)
+      );
+      CREATE INDEX idx_pipeline_runs_status   ON pipeline_runs(status);
+      CREATE INDEX idx_pipeline_runs_pipeline ON pipeline_runs(pipeline_id);
+
+      CREATE TABLE managed_processes (
+        name        TEXT PRIMARY KEY,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+
+      CREATE TABLE worktree_pool (
+        entry_id    TEXT PRIMARY KEY,
+        data        TEXT NOT NULL,
+        updated_at  INTEGER NOT NULL
+      );
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+    const now = Date.now();
+    let inserted = 0;
+
+    // ── schedule_runs ──────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'schedule-runs.json'), null);
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const ins = db.prepare(`INSERT INTO schedule_runs (schedule_id, data, updated_at) VALUES (?, ?, ?)`);
+        for (const [scheduleId, value] of Object.entries(raw)) {
+          try {
+            ins.run(scheduleId, JSON.stringify(value), now);
+            inserted += 1;
+          } catch { /* duplicate / corrupt — skip */ }
+        }
+      }
+    }
+
+    // ── pipeline_runs ──────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'pipeline-runs.json'), null);
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const ins = db.prepare(`
+          INSERT INTO pipeline_runs (pipeline_id, run_id, status, started_at, data, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?)
+        `);
+        for (const [pipelineId, runs] of Object.entries(raw)) {
+          if (!Array.isArray(runs)) continue;
+          for (const run of runs) {
+            if (!run || !run.runId) continue;
+            try {
+              ins.run(
+                pipelineId,
+                String(run.runId),
+                run.status || null,
+                _toMs(run.startedAt),
+                JSON.stringify(run),
+                now,
+              );
+              inserted += 1;
+            } catch { /* duplicate / corrupt — skip */ }
+          }
+        }
+      }
+    }
+
+    // ── managed_processes ──────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'managed-processes.json'), null);
+      if (raw && Array.isArray(raw.specs)) {
+        const ins = db.prepare(`INSERT INTO managed_processes (name, data, updated_at) VALUES (?, ?, ?)`);
+        for (const spec of raw.specs) {
+          if (!spec || typeof spec !== 'object' || !spec.name) continue;
+          try {
+            ins.run(String(spec.name), JSON.stringify(spec), now);
+            inserted += 1;
+          } catch { /* duplicate name — skip */ }
+        }
+      }
+    }
+
+    // ── worktree_pool ──────────────────────────────────────────────────────
+    {
+      const raw = _readJsonOr(path.join(minionsDir, 'engine', 'worktree-pool.json'), null);
+      if (raw && Array.isArray(raw.entries)) {
+        const ins = db.prepare(`INSERT INTO worktree_pool (entry_id, data, updated_at) VALUES (?, ?, ?)`);
+        for (const entry of raw.entries) {
+          if (!entry || typeof entry !== 'object') continue;
+          // Worktree pool entries don't have an obvious unique id field;
+          // use the worktree path (always unique within a single pool).
+          const id = entry.path || entry.id || JSON.stringify(entry).slice(0, 64);
+          try {
+            ins.run(String(id), JSON.stringify(entry), now);
+            inserted += 1;
+          } catch { /* duplicate — skip */ }
+        }
+      }
+    }
+
+    // eslint-disable-next-line no-console
+    console.log(`[db-migrate] v8: backfilled ${inserted} small-state rows; JSON files kept as dual-write mirrors`);
+  },
+};

package/engine/managed-spawn.js

@@ -850,7 +850,7 @@ function _toStateRecord(spec, runtime, ctx) {
 function recordManagedSpec(spec, runtime, ctx) {
   if (!spec || !spec.name) throw new Error('recordManagedSpec: spec.name required');
   const statePath = _getStatePath();
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
     }
@@ -865,7 +865,7 @@ function recordManagedSpec(spec, runtime, ctx) {
 function recordManagedBatch(items, ctx) {
   if (!Array.isArray(items) || items.length === 0) return;
   const statePath = _getStatePath();
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
     }
@@ -886,7 +886,7 @@ function removeManagedSpec(name) {
   if (typeof name !== 'string' || name.length === 0) return;
   let killPid = null;
   const statePath = _getStatePath();
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const idx = data.specs.findIndex(s => s && s.name === name);
     if (idx < 0) return data;
@@ -1033,7 +1033,7 @@ async function runHealthcheck(spec) {
 // lock — this acquires its own.
 function _markHealthy(name, now) {
   const statePath = _getStatePath();
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
     if (!rec) return data;
@@ -1334,7 +1334,7 @@ function _runManagedReconcile(opts) {
   const statePath = _getStatePath();
   const ttlPidsToKill = [];
   const survivors = []; // [{name, log_path}] post-mutation, used for log rotation + bootReconcile probes
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       stats.malformed++;
       return _initialStateShape();
@@ -1387,7 +1387,7 @@ function sweepManagedSpawn(opts) {
 // to (re)establish initial truth on engine restart).
 function _markBootProbe(name, result) {
   const statePath = _getStatePath();
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
     if (!rec) return data;
@@ -1440,7 +1440,7 @@ function removeManagedSpecsForProject(projectName) {
   const statePath = _getStatePath();
   let toKill = [];
   let logPaths = [];
-  shared.mutateJsonFileLocked(statePath, (data) => {
+  shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || !Array.isArray(data.specs)) {
       return _initialStateShape();
     }

package/engine/pipeline.js

@@ -8,7 +8,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
-const { safeJson, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR } = shared;
+const { safeJson, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR } = shared;
 const routing = require('./routing');
 const http = require('http');
 const { parseCronExpr, shouldRunNow } = require('./scheduler');
@@ -90,18 +90,16 @@ function startRun(pipelineId, pipeline) {
   const run = { runId, pipelineId, startedAt: ts(), status: PIPELINE_STATUS.RUNNING, stages };
 
   let alreadyActive = false;
-  mutateJsonFileLocked(PIPELINE_RUNS_PATH, (data) => {
+  mutatePipelineRuns((data) => {
     if (!data[pipelineId]) data[pipelineId] = [];
-    // Guard: skip if there's already an active run (prevents race between ticks)
     if (data[pipelineId].some(r => r.status === PIPELINE_STATUS.RUNNING || r.status === PIPELINE_STATUS.PAUSED)) {
       alreadyActive = true;
       return data;
     }
-    // Keep last 10 runs per pipeline
     if (data[pipelineId].length >= 10) data[pipelineId] = data[pipelineId].slice(-9);
     data[pipelineId].push(run);
     return data;
-  }, { defaultValue: {} });
+  });
 
   if (alreadyActive) {
     log('info', `Pipeline ${pipelineId}: skipped startRun — active run already exists`);
@@ -118,14 +116,14 @@ function updateRunStage(pipelineId, runId, stageId, updates) {
       throw new Error(`updateRunStage: invalid status '${updates.status}' (expected one of: ${validStatuses.join('|')})`);
     }
   }
-  mutateJsonFileLocked(PIPELINE_RUNS_PATH, (data) => {
+  mutatePipelineRuns((data) => {
     const runs = data[pipelineId] || [];
     const run = runs.find(r => r.runId === runId);
     if (run && run.stages[stageId]) {
       Object.assign(run.stages[stageId], updates);
     }
     return data;
-  }, { defaultValue: {} });
+  });
 }
 
 function completeRun(pipelineId, runId, status) {
@@ -135,7 +133,7 @@ function completeRun(pipelineId, runId, status) {
   // never shows "in progress" for a stage inside a closed run.
   const TERMINAL = new Set([PIPELINE_STATUS.COMPLETED, PIPELINE_STATUS.FAILED, PIPELINE_STATUS.STOPPED]);
   const anomalies = [];
-  mutateJsonFileLocked(PIPELINE_RUNS_PATH, (data) => {
+  mutatePipelineRuns((data) => {
     const runs = data[pipelineId] || [];
     const run = runs.find(r => r.runId === runId);
     if (run) {
@@ -158,7 +156,7 @@ function completeRun(pipelineId, runId, status) {
       }
     }
     return data;
-  }, { defaultValue: {} });
+  });
   log('info', `Pipeline ${pipelineId}: run ${runId} → ${status}`);
   if (anomalies.length > 0) {
     log('warn', `Pipeline ${pipelineId}: run ${runId} closed COMPLETED with non-terminal stages [${anomalies.join(', ')}] — forced to completed`);

package/engine/pull-requests-store.js

@@ -62,15 +62,16 @@ function _readJsonArrayFallback(scope) {
   }
 }
 
-// Track (mtime, size) per scope so back-to-back writes inside the same
-// ms tick still get detected as external edits (mtime-only checks miss
-// them on Windows because NTFS reports ms-rounded mtimeMs).
-const _lastMirrorByScope = new Map();
+// Content-hash fingerprint per scope: same-length swaps (timestamps,
+// reviewStatus enums) collide on (mtime, size) but never on SHA-1.
+const _lastMirrorHashByScope = new Map();
 
-function _statFingerprint(filePath) {
+const crypto = require('crypto');
+
+function _fileContentHash(filePath) {
   try {
-    const st = fs.statSync(filePath);
-    return { mtime: st.mtimeMs, size: st.size };
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha1').update(buf).digest('hex');
   }
   catch { return null; }
 }
@@ -105,23 +106,19 @@ function _hydrateScopeFromJson(db, scope) {
 
 function _resyncScopeIfJsonDiverged(db, scope) {
   const jsonPath = _filePathForScope(scope);
-  const current = _statFingerprint(jsonPath);
-  const lastMirror = _lastMirrorByScope.get(scope);
-  if (current == null) return;
-  // In-sync iff BOTH mtime AND size match. Size catches same-ms-tick
-  // external writes that mtime alone misses. Resync is idempotent.
-  if (lastMirror != null
-    && current.mtime === lastMirror.mtime
-    && current.size === lastMirror.size) return;
-  if (lastMirror == null) {
+  const currentHash = _fileContentHash(jsonPath);
+  const lastHash = _lastMirrorHashByScope.get(scope);
+  if (currentHash == null) return;
+  if (lastHash != null && currentHash === lastHash) return;
+  if (lastHash == null) {
     const sqlHas = db.prepare('SELECT 1 FROM pull_requests WHERE scope = ? LIMIT 1').get(scope);
     if (sqlHas) {
-      _lastMirrorByScope.set(scope, current);
+      _lastMirrorHashByScope.set(scope, currentHash);
       return;
     }
   }
   _hydrateScopeFromJson(db, scope);
-  _lastMirrorByScope.set(scope, current);
+  _lastMirrorHashByScope.set(scope, currentHash);
 }
 
 function readPullRequestsForScope(scope) {
@@ -269,12 +266,23 @@ function applyPullRequestsMutation(scope, mutator) {
 function _mirrorJsonFromSql(scope, filePath) {
   try {
     const shared = require('./shared');
-    const items = readPullRequestsForScope(scope);
-    for (const pr of items) { if (pr && pr._scope) delete pr._scope; }
+    const { getDb } = require('./db');
+    // Read SQL directly for this scope — bypass JSON fallback so a
+    // mutation that empties SQL for the scope doesn't resurrect stale
+    // JSON content.
+    const db = getDb();
+    const rows = db.prepare('SELECT data FROM pull_requests WHERE scope = ? ORDER BY rowid').all(scope);
+    const items = [];
+    for (const row of rows) {
+      const pr = _parseRow(row);
+      if (!pr) continue;
+      if (pr._scope) delete pr._scope;
+      items.push(pr);
+    }
     const target = filePath || _filePathForScope(scope);
     shared.safeWrite(target, items);
-    const fp = _statFingerprint(target);
-    if (fp != null) _lastMirrorByScope.set(scope, fp);
+    const h = _fileContentHash(target);
+    if (h != null) _lastMirrorHashByScope.set(scope, h);
   } catch {
     // Mirror failures are non-fatal — SQL has already committed.
   }

package/engine/scheduler.js

@@ -25,7 +25,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const routing = require('./routing');
-const { safeJson, safeWrite, mutateJsonFileLocked, ts, dateStamp, WI_STATUS, WORK_TYPE } = shared;
+const { safeJson, safeWrite, mutateJsonFileLocked, mutateScheduleRuns, ts, dateStamp, WI_STATUS, WORK_TYPE } = shared;
 
 const SCHEDULE_RUNS_PATH = path.join(shared.MINIONS_DIR, 'engine', 'schedule-runs.json');
 
@@ -194,10 +194,10 @@ function writeScheduleRunEntry(runs, scheduleId, workItemId) {
 
 function recordScheduleRun(scheduleId, workItemId) {
   let entry = null;
-  mutateJsonFileLocked(SCHEDULE_RUNS_PATH, (runs) => {
+  mutateScheduleRuns((runs) => {
     entry = writeScheduleRunEntry(runs, scheduleId, workItemId);
     return runs;
-  }, { defaultValue: {} });
+  });
   return entry;
 }
 
@@ -212,7 +212,7 @@ function discoverScheduledWork(config) {
 
   // Use file-locked mutation to prevent race conditions on rapid calls
   const work = [];
-  mutateJsonFileLocked(SCHEDULE_RUNS_PATH, (runs) => {
+  mutateScheduleRuns((runs) => {
     for (const sched of schedules) {
       if (!sched.id || !sched.cron || !sched.title) continue;
       if (sched.enabled === false) continue; // strict false check — undefined/null default to enabled per schema
@@ -236,7 +236,8 @@ function discoverScheduledWork(config) {
       // the double-fire window alongside the same-minute guard (W-mo3zu273f8tm).
       writeScheduleRunEntry(runs, sched.id, workItem.id);
     }
-  }, { defaultValue: {} });
+    return runs;
+  });
 
   return work;
 }

package/engine/shared.js

@@ -2744,6 +2744,106 @@ const WATCH_ACTION_TYPE = {
   RESUME_PLAN: 'resume-plan',
 };
 
+/**
+ * Phase 7 — small state file mutators. Each routes through the
+ * small-state-store, mirrors back to its JSON file, and emits a topic
+ * event on real writes. SQLite failure falls through to the legacy
+ * mutateJsonFileLocked path.
+ */
+function _smallStateMutator({ filePath, applyMutation, mirror, topic, defaultValue }) {
+  return (mutator) => {
+    try {
+      const store = require('./small-state-store');
+      const { wrote, result } = store[applyMutation]((obj) => mutator(obj) || obj);
+      if (wrote) {
+        try { store[mirror](filePath); } catch { /* mirror best-effort */ }
+        try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+      }
+      return result;
+    } catch (e) {
+      if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) throw e;
+    }
+    return mutateJsonFileLocked(filePath, (data) => {
+      if (data == null) data = defaultValue();
+      return mutator(data) || data;
+    }, {
+      defaultValue: defaultValue(),
+      onWrote: () => {
+        try { require('./db-events').emitStateEvent(topic); } catch { /* optional */ }
+      },
+    });
+  };
+}
+
+const mutateScheduleRuns = _smallStateMutator({
+  filePath: path.join(MINIONS_DIR, 'engine', 'schedule-runs.json'),
+  applyMutation: 'applyScheduleRunsMutation',
+  mirror: '_mirrorScheduleRunsJson',
+  topic: 'schedule_runs',
+  defaultValue: () => ({}),
+});
+
+const mutatePipelineRuns = _smallStateMutator({
+  filePath: path.join(MINIONS_DIR, 'engine', 'pipeline-runs.json'),
+  applyMutation: 'applyPipelineRunsMutation',
+  mirror: '_mirrorPipelineRunsJson',
+  topic: 'pipeline_runs',
+  defaultValue: () => ({}),
+});
+
+const mutateManagedProcesses = _smallStateMutator({
+  filePath: path.join(MINIONS_DIR, 'engine', 'managed-processes.json'),
+  applyMutation: 'applyManagedProcessesMutation',
+  mirror: '_mirrorManagedProcessesJson',
+  topic: 'managed_processes',
+  defaultValue: () => ({ specs: [] }),
+});
+
+const mutateWorktreePool = _smallStateMutator({
+  filePath: path.join(MINIONS_DIR, 'engine', 'worktree-pool.json'),
+  applyMutation: 'applyWorktreePoolMutation',
+  mirror: '_mirrorWorktreePoolJson',
+  topic: 'worktree_pool',
+  defaultValue: () => ({ entries: [] }),
+});
+
+/**
+ * Route a watches mutation through the SQL store. Same shape as
+ * mutateWorkItems / mutatePullRequests: mutator receives the watches
+ * array, mutates in place or returns a replacement, and the store
+ * diffs by id. Falls back to the legacy mutateJsonFileLocked path on
+ * SQLite failure.
+ */
+function mutateWatches(mutator) {
+  const watchesPath = path.join(MINIONS_DIR, 'engine', 'watches.json');
+  try {
+    const store = require('./watches-store');
+    const { wrote, result } = store.applyWatchesMutation((arr) => {
+      if (!Array.isArray(arr)) arr = [];
+      return mutator(arr) || arr;
+    });
+    if (wrote) {
+      try { store._mirrorJsonFromSql(watchesPath); } catch { /* mirror best-effort */ }
+      try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
+    }
+    return result;
+  } catch (e) {
+    if (!e || !/SQLite unavailable|no such table|node:sqlite/.test(String(e.message))) {
+      throw e;
+    }
+    // SQLite unavailable — fall through to legacy JSON path.
+  }
+  return mutateJsonFileLocked(watchesPath, (data) => {
+    if (!Array.isArray(data)) data = [];
+    return mutator(data) || data;
+  }, {
+    defaultValue: [],
+    onWrote: () => {
+      try { require('./db-events').emitStateEvent('watches'); } catch { /* optional */ }
+    },
+  });
+}
+
 /**
  * Route a metrics mutation through the SQL store with a JSON dual-write
  * mirror. Same shape as mutateWorkItems / mutatePullRequests: mutator
@@ -5225,7 +5325,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, mutateMetrics, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,