@yemi33/minions 0.1.2378 → 0.1.2380

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

package/engine/acp-transport.js

@@ -97,9 +97,10 @@ const WARM_MAX_CONCURRENT = 3;
 // W-mqid8uev). resolveBinary() resolves the real JS entry
 // (node_modules/@github/copilot/index.js) and reports whether to spawn it
 // directly (native) or under the current Node process (shim).
-function spawnAcp({ cwd } = {}) {
+function spawnAcp({ cwd, env } = {}) {
   const copilot = require('./runtimes/copilot');
-  const resolved = copilot.resolveBinary({ env: process.env });
+  const workerEnv = env || process.env;
+  const resolved = copilot.resolveBinary({ env: workerEnv });
   if (!resolved || !resolved.bin) {
     throw new Error(
       `copilot binary not resolvable -- ${copilot.installHint || 'install the GitHub Copilot CLI'}`
@@ -114,6 +115,7 @@ function spawnAcp({ cwd } = {}) {
   return spawn(execBin, execArgs, {
     stdio: ['pipe', 'pipe', 'pipe'],
     cwd: cwd || process.cwd(),
+    env: workerEnv,
     windowsHide: true,
     // Don't pass shell:true — the native/leadingArgs handling above already
     // produces a directly-spawnable argv, and a shell wrapper would swallow
@@ -139,6 +141,33 @@ function hashMcpServers(mcpServers) {
   return crypto.createHash('sha256').update(json).digest('hex');
 }
 
+function _stableObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+function hashProcessContext(processEnv) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(_stableObject(processEnv)))
+    .digest('hex');
+}
+
+function buildTrustedSessionContext(sessionContext) {
+  const context = _stableObject(sessionContext);
+  if (Object.keys(context).length === 0) return '';
+  const json = JSON.stringify(context, null, 2).replace(/<\/system/gi, '<\\/system');
+  return [
+    'Trusted pooled-dispatch context (session-scoped):',
+    'These values are the authoritative equivalents of the same-named environment variables for this ACP session.',
+    'Use them directly; do not try to recover them from the reusable worker process environment.',
+    json,
+  ].join('\n');
+}
+
 // Bug B (issue #2479): `model` and `effort` were stored on the Worker but
 // never forwarded to ACP `session/new`, so any model override was silently
 // dropped. Build the params object here and only include fields that are
@@ -216,12 +245,17 @@ function mapAcpToolCallToToolUse(update) {
  * logger (default no-op); consumers wire their own env-gated trace prefix.
  */
 class Worker {
-  constructor({ id, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd, internals, trace }) {
+  constructor({
+    id, model, effort, mcpServers, mcpServersHash, processEnv, processContextHash,
+    systemPromptHash, cwd, internals, trace,
+  }) {
     this.id = id;
     this.model = model;
     this.effort = effort;
     this.mcpServers = mcpServers || [];
     this.mcpServersHash = mcpServersHash;
+    this.processEnv = processEnv;
+    this.processContextHash = processContextHash;
     this.systemPromptHash = systemPromptHash;
     this.cwd = cwd || process.cwd();
     this._internals = internals;
@@ -249,7 +283,7 @@ class Worker {
   async _spawnAndInit() {
     let proc;
     try {
-      proc = this._internals.spawnAcp({ cwd: this.cwd });
+      proc = this._internals.spawnAcp({ cwd: this.cwd, env: this.processEnv });
     } catch (err) {
       // spawn() threw synchronously — typically ENOENT (copilot binary not
       // on PATH) or EACCES. Surface as worker-spawn-failed so the consumer
@@ -440,7 +474,10 @@ class Worker {
 
   // ── Stream a single turn ───────────────────────────────────────────────
   stream(promptText, opts = {}) {
-    const { onChunk, onToolUse, onToolUpdate, onDone, onError, signal, systemPromptText } = opts;
+    const {
+      onChunk, onToolUse, onToolUpdate, onDone, onError, signal,
+      systemPromptText, trustedSessionContext, deferSystemPrompt,
+    } = opts;
     if (this.killed) {
       const err = new Error('acp-transport: worker is closed');
       if (onError) try { onError(err); } catch { /* swallow */ }
@@ -458,10 +495,12 @@ class Worker {
     // adapter pattern of <system>...</system> prepended to the first user
     // message remains correct.
     let prompt = promptText;
-    if (!this.firstSystemPromptSent && systemPromptText) {
-      prompt = `<system>\n${systemPromptText}\n</system>\n\n${promptText}`;
+    const trustedContextText = buildTrustedSessionContext(trustedSessionContext);
+    const trustedSystemText = [systemPromptText, trustedContextText].filter(Boolean).join('\n\n');
+    if (!this.firstSystemPromptSent && trustedSystemText) {
+      prompt = `<system>\n${trustedSystemText}\n</system>\n\n${promptText}`;
     }
-    this.firstSystemPromptSent = true;
+    if (!deferSystemPrompt) this.firstSystemPromptSent = true;
 
     const id = this.nextReqId++;
     const inflight = {
@@ -586,6 +625,8 @@ module.exports = {
   spawnAcp,
   killImmediate,
   hashMcpServers,
+  hashProcessContext,
+  buildTrustedSessionContext,
   buildSessionNewParams,
   extractChunkText,
   mapAcpToolCallToToolUse,

package/engine/ado-status.js

@@ -14,7 +14,7 @@
  *
  * Output: JSON to stdout. Exit 0 on success, 1 on error/not-found.
  *
- * Cached (default): reads pull-requests.json maintained by the engine (~3 min stale).
+ * Cached (default): reads engine-maintained SQL state (~3 min stale).
  * Live (--live):    makes fresh ADO API calls — use when engine isn't running or you
  *                   just pushed and need up-to-the-moment build status.
  */
@@ -23,7 +23,7 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, safeJsonArr, projectPrPath, getProjects, MINIONS_DIR } = shared;
+const { safeJson, readPullRequests, getProjects, MINIONS_DIR } = shared;
 
 // ── Arg parsing ──────────────────────────────────────────────────────────────
 
@@ -56,7 +56,7 @@ const prNumber = parseInt(prNumberArg, 10);
 
 function findInCache(projects) {
   for (const project of projects) {
-    const prs = safeJsonArr(projectPrPath(project));
+    const prs = readPullRequests(project);
     shared.normalizePrRecords(prs, project);
     const pr = prs.find(p => p.prNumber === prNumber || p.id === shared.getCanonicalPrId(project, prNumber) || shared.getPrDisplayId(p) === `PR-${prNumber}`);
     if (!pr) continue;
@@ -104,7 +104,7 @@ async function main() {
   if (!live) {
     const result = findInCache(projects);
     if (result) { console.log(JSON.stringify(result, null, 2)); return; }
-    console.error(`PR #${prNumber} not found in cached pull-requests.json`);
+    console.error(`PR #${prNumber} not found in the cached PR store`);
     console.error('Tip: try --live for a fresh ADO API call, or check the PR number is correct.');
     process.exit(1);
   }
@@ -133,7 +133,7 @@ async function main() {
     return;
   }
 
-  console.error(`PR #${prNumber} not found (tried live ADO API and cached pull-requests.json).`);
+  console.error(`PR #${prNumber} not found (tried live ADO API and the cached PR store).`);
   process.exit(1);
 }
 

package/engine/ado.js

@@ -279,7 +279,7 @@ function repairAdoProjectConfig(project, purpose, prs = null) {
   const missingBefore = getMissingAdoProjectConfigFields(project);
   if (missingBefore.length === 0) return false;
 
-  const trackedPrs = prs || shared.safeJsonArr(shared.projectPrPath(project));
+  const trackedPrs = prs || shared.readPullRequests(project);
   for (const candidate of collectAdoRepairCandidates(project, trackedPrs)) {
     const repairs = {};
     if (!project.adoOrg && candidate.adoOrg) repairs.adoOrg = candidate.adoOrg;
@@ -1199,7 +1199,7 @@ async function forEachActivePr(config, token, callback) {
     }
 
     if (projectUpdated > 0) {
-      mutateJsonFileLocked(shared.projectPrPath(project), (currentPrs) => {
+      shared.mutatePullRequests(project, (currentPrs) => {
         // Merge back only fields changed by callbacks; preserve concurrent disk updates.
         for (const { before, after } of updatedRecords) {
           const updatedPrNumber = shared.getPrNumber(after);
@@ -1244,9 +1244,9 @@ async function forEachActivePr(config, token, callback) {
     }
   }
 
-  // BUG-C2 — Also poll manually-linked ADO PRs from central pull-requests.json.
+  // BUG-C2 — Also poll manually linked ADO PRs from the central PR store.
   // Mirror of engine/github.js:540-633. Without this block, any ADO PR enrolled
-  // into central pull-requests.json via the dashboard attach UI or
+  // into the central PR store via the dashboard attach UI or
   // lifecycle.enrollPrFromCanonicalId is never polled (status, build, review,
   // comments, abandoned-reconciliation all freeze permanently).
   //
@@ -1272,8 +1272,7 @@ async function forEachActivePr(config, token, callback) {
   //      in that project's per-project file, so the project loop will really see
   //      them. Blindly skipping all project-compatible IDs caused a permanent
   //      orphan when the record lived in the central file (#328).
-  const centralPath = path.join(shared.MINIONS_DIR, 'pull-requests.json');
-  const centralPrs = shared.safeJsonArr(centralPath);
+  const centralPrs = shared.readPullRequests('central');
   const configuredAdoProjects = projects.filter(p => !isGitHubProject(p) && p.adoOrg && p.adoProject);
 
   const activeCentral = centralPrs.filter(pr => {
@@ -1287,7 +1286,7 @@ async function forEachActivePr(config, token, callback) {
     // polled (fix for #328).
     const owningProject = configuredAdoProjects.find(p => shared.isPrCompatibleWithProject(p, { id: pr.id }, ''));
     if (owningProject) {
-      const projectPrs = shared.safeJsonArr(shared.projectPrPath(owningProject));
+      const projectPrs = shared.readPullRequests(owningProject);
       if (projectPrs.some(p => p.id === pr.id)) return false; // present in per-project file → project loop handles it
     }
     return true;
@@ -1353,7 +1352,7 @@ async function forEachActivePr(config, token, callback) {
   }
 
   if (centralUpdated > 0) {
-    mutateJsonFileLocked(centralPath, (currentPrs) => {
+    shared.mutatePullRequests('central', (currentPrs) => {
       for (const { before, after } of updatedCentralRecords) {
         const idx = currentPrs.findIndex(p => p.id === after.id);
         if (idx >= 0) {
@@ -1457,7 +1456,7 @@ async function pollPrStatus(config) {
         }
         // F6 (P-f6commentedit): drop the comment-edit dedup map on merge/abandon
         // — no further re-dispatch path can fire from this PR, so keeping it
-        // around would only bloat pull-requests.json.
+        // around would only bloat the PR store.
         if (pr.humanFeedback && pr.humanFeedback.editsSeen) {
           delete pr.humanFeedback.editsSeen;
         }
@@ -1911,7 +1910,7 @@ async function pollPrStatus(config) {
     // review status flipped, etc.) is dropped via clearPrNoOpFixAttempt. The
     // dispatch gate already ignores these stale records (isPrNoOpFixCausePaused
     // re-validates the fingerprint), but without this sweep they linger in
-    // pull-requests.json forever — bloating the file and confusing the
+    // PR store forever — bloating the registry and confusing the
     // dashboard `pr-paused-chip`. Runs AFTER all live-field updates so the
     // fingerprint comparison uses post-poll PR state.
     try {
@@ -2160,7 +2159,7 @@ async function pollPrHumanComments(config) {
 
 /**
  * Reconcile PRs: find active ADO PRs created by the minions that aren't tracked
- * in pull-requests.json, and add them. Matches PRs to work items by branch name.
+ * in the PR store, and add them. Matches PRs to work items by branch name.
  */
 async function reconcilePrs(config) {
   // #3758 — inert when no project actually uses ADO.
@@ -2207,18 +2206,15 @@ async function reconcilePrs(config) {
 
     if (adoPrs.length === 0) continue;
 
-    const prPath = shared.projectPrPath(project);
-    const existingPrs = shared.safeJsonArr(prPath);
+    const existingPrs = shared.readPullRequests(project);
     shared.normalizePrRecords(existingPrs, project);
     const existingIds = new Set(existingPrs.map(p => p.id));
     let projectAdded = 0;
     let metadataUpdated = 0;
 
     // Load work items to match branches to work item IDs
-    const wiPath = shared.projectWorkItemsPath(project);
-    const workItems = shared.safeJsonArr(wiPath);
-    const centralWiPath = path.join(shared.MINIONS_DIR, 'work-items.json');
-    const centralItems = shared.safeJsonArr(centralWiPath);
+    const workItems = shared.readWorkItems(project);
+    const centralItems = shared.readWorkItems('central');
     const allItems = [...workItems, ...centralItems];
 
     let projectUpdated = 0;
@@ -2251,9 +2247,9 @@ async function reconcilePrs(config) {
             log('warn', `ADO: invalid sourceRefName "${branch.slice(0, 64)}" for PR ${prId}: ${refErr.message}`);
           }
         }
-        // PR already tracked — write link to pr-links.json if we can extract an ID
+        // PR already tracked — write a PR link if we can extract an ID
         if (confirmedItemId) {
-          shared.upsertPullRequestRecord(prPath, existing || {
+          shared.upsertPullRequestRecord(project, existing || {
             id: prId,
             prNumber: adoPr.pullRequestId,
             title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
@@ -2312,7 +2308,7 @@ async function reconcilePrs(config) {
         sourcePlan: linkedItem?.sourcePlan || '',
         itemType: linkedItem?.itemType || '',
       };
-      const upserted = shared.upsertPullRequestRecord(prPath, entry, { project, itemId: confirmedItemId });
+      const upserted = shared.upsertPullRequestRecord(project, entry, { project, itemId: confirmedItemId });
       existingPrs.push(upserted.record || entry);
       existingIds.add(prId);
       projectAdded++;
@@ -2331,7 +2327,7 @@ async function reconcilePrs(config) {
     const backfilled = shared.backfillPrPrdItems(existingPrs, shared.getPrLinks());
 
     if (projectAdded > 0 || projectUpdated > 0 || backfilled > 0 || metadataUpdated > 0) {
-      mutateJsonFileLocked(prPath, (currentPrs) => {
+      shared.mutatePullRequests(project, (currentPrs) => {
         // Merge reconciled PRs into the locked copy by ID
         for (const pr of existingPrs) {
           const idx = currentPrs.findIndex(p => p.id === pr.id);
@@ -2905,7 +2901,7 @@ async function reconcileAbandonedPrs(config) {
     // log line is honest about what we left behind.
     let pending = 0;
     for (const project of projects) {
-      const prs = shared.safeJsonArr(shared.projectPrPath(project));
+      const prs = shared.readPullRequests(project);
       pending += prs.filter(pr =>
         pr.status === shared.PR_STATUS.ABANDONED && !pr._reconciliation404Confirmed
       ).length;
@@ -2926,8 +2922,7 @@ async function reconcileAbandonedPrs(config) {
       continue;
     }
 
-    const prPath = shared.projectPrPath(project);
-    const prs = shared.safeJsonArr(prPath);
+    const prs = shared.readPullRequests(project);
     const abandonedPrs = prs.filter(pr =>
       pr.status === shared.PR_STATUS.ABANDONED
       && !pr._reconciliation404Confirmed
@@ -3010,7 +3005,7 @@ async function reconcileAbandonedPrs(config) {
 
     if (updates.length > 0) {
       const reconciledAt = ts();
-      shared.mutatePullRequests(prPath, (currentPrs) => {
+      shared.mutatePullRequests(project, (currentPrs) => {
         for (const upd of updates) {
           const pr = currentPrs.find(p => shared.getPrNumber(p) === upd.prNumber);
           if (!pr) continue;