@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/persistence/state-operations.js

@@ -0,0 +1,350 @@
+// Explicit operational tooling for the SQL-only runtime state store.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { getDb } = require('../db');
+
+/** How many ids per entity are sampled into a state summary. */
+const IDENTITY_SAMPLE_LIMIT = 50;
+
+function _quoteSqlString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+/** Table names are interpolated into SQL, so they are validated, never trusted. */
+function _tableNames(db) {
+  const names = db.prepare(`
+    SELECT name FROM sqlite_master
+    WHERE type='table' AND name NOT LIKE 'sqlite_%'
+    ORDER BY name
+  `).all().map(row => row.name);
+  for (const name of names) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe table name: ${name}`);
+  }
+  return names;
+}
+
+function checkState(db = getDb()) {
+  const schemaVersion = Number(db.prepare('SELECT COALESCE(MAX(version), 0) AS version FROM schema_version').get().version) || 0;
+  const quickCheck = db.prepare('PRAGMA quick_check').all().map(row => Object.values(row)[0]);
+  const foreignKeyViolations = db.prepare('PRAGMA foreign_key_check').all();
+  const invariants = {
+    orphanPrdItems: Number(db.prepare('SELECT COUNT(*) AS n FROM prd_items pi LEFT JOIN prds p ON p.id=pi.prd_id WHERE p.id IS NULL').get().n) || 0,
+    orphanVerifyPrs: Number(db.prepare('SELECT COUNT(*) AS n FROM prd_verify_prs vp LEFT JOIN prds p ON p.id=vp.prd_id WHERE p.id IS NULL').get().n) || 0,
+    brokenWorkItemPrdLinks: Number(db.prepare('SELECT COUNT(*) AS n FROM work_items wi LEFT JOIN prd_items pi ON pi.id=wi.prd_item_id WHERE wi.prd_item_id IS NOT NULL AND pi.id IS NULL').get().n) || 0,
+  };
+  const ok = quickCheck.length === 1
+    && quickCheck[0] === 'ok'
+    && foreignKeyViolations.length === 0
+    && Object.values(invariants).every(count => count === 0);
+  return { ok, schemaVersion, quickCheck, foreignKeyViolations, invariants };
+}
+
+/** Absolute path of the `main` database file behind an open connection. */
+function _mainDbFile(db) {
+  try {
+    const row = db.prepare('PRAGMA database_list').all().find(entry => entry.name === 'main');
+    return row && row.file ? row.file : null;
+  } catch { return null; }
+}
+
+function _walBytes(db) {
+  const file = _mainDbFile(db);
+  if (!file) return 0;
+  try { return fs.statSync(`${file}-wal`).size; } catch { return 0; }
+}
+
+// Best-effort WAL quiescence. Deliberately PASSIVE: TRUNCATE/RESTART block
+// until every reader is on the newest snapshot, so with the engine and
+// dashboard connected they either burn the busy timeout and report `busy` (a
+// RESULT ROW that `db.exec()` silently discards, which is how the old code
+// claimed a checkpoint it never got) or raise outright and abort the whole
+// backup. Quiescence is an optimisation here, not a correctness requirement,
+// so every failure is captured and reported instead of thrown.
+function _passiveCheckpoint(db) {
+  try {
+    const row = db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get() || {};
+    const busy = Number(row.busy) || 0;
+    const log = Number(row.log);
+    const checkpointed = Number(row.checkpointed);
+    // `log` is the total frame count in the WAL and `checkpointed` the number
+    // already folded back into the database, so equality means fully quiesced.
+    // Both are -1 outside WAL mode, which is also quiesced.
+    const complete = busy === 0
+      && Number.isFinite(log)
+      && Number.isFinite(checkpointed)
+      && checkpointed >= log;
+    return { checkpointed: complete, error: null };
+  } catch (e) {
+    return { checkpointed: false, error: (e && e.message) ? e.message : String(e) };
+  }
+}
+
+function backupState(targetPath) {
+  if (!targetPath) throw new Error('state backup requires an output path');
+  const resolved = path.resolve(targetPath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  if (fs.existsSync(resolved)) throw new Error(`backup target already exists: ${resolved}`);
+  const db = getDb();
+  const walBytesAtStart = _walBytes(db);
+  const checkpoint = _passiveCheckpoint(db);
+  if (checkpoint.error) {
+    console.warn(`[state] backup: WAL checkpoint skipped, continuing (non-fatal): ${checkpoint.error}`);
+  }
+  // Authoritative step. VACUUM INTO takes a read transaction whose snapshot
+  // already includes committed WAL frames and writes a standalone, internally
+  // consistent database, so it is correct with or without the checkpoint above
+  // and is the ONLY step allowed to fail the backup. Never byte-copy state.db:
+  // that drops committed-but-uncheckpointed transactions.
+  db.exec(`VACUUM INTO ${_quoteSqlString(resolved)}`);
+  return {
+    ok: true,
+    path: resolved,
+    bytes: fs.statSync(resolved).size,
+    checkpointed: checkpoint.checkpointed,
+    walBytesAtStart,
+  };
+}
+
+function _sampleIds(db, table, column = 'id', limit = IDENTITY_SAMPLE_LIMIT) {
+  try {
+    return db.prepare(`SELECT "${column}" AS id FROM "${table}" ORDER BY "${column}" LIMIT ${Number(limit) | 0}`)
+      .all().map(row => String(row.id));
+  } catch { return []; }
+}
+
+/**
+ * Row-level census of the SQL state, used to prove state continuity across an
+ * install/migration/restore. The table list is derived from `sqlite_master` so
+ * tables added by future migrations are covered without touching this module.
+ */
+function summarizeState(db = getDb()) {
+  const schemaVersion = Number(db.prepare('SELECT COALESCE(MAX(version), 0) AS version FROM schema_version').get().version) || 0;
+  const tables = {};
+  for (const table of _tableNames(db)) {
+    // A table that cannot be counted (an FTS shadow table on a read-only
+    // handle, say) records `null` — unknown, never a fabricated zero.
+    try { tables[table] = Number(db.prepare(`SELECT COUNT(*) AS n FROM "${table}"`).get().n) || 0; }
+    catch { tables[table] = null; }
+  }
+  const identities = {
+    workItems: _sampleIds(db, 'work_items'),
+    pullRequests: _sampleIds(db, 'pull_requests'),
+  };
+  const fingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    schemaVersion,
+    tables: Object.keys(tables).sort().map(name => [name, tables[name]]),
+  })).digest('hex');
+  return { schemaVersion, tables, identities, fingerprint };
+}
+
+function _assertSummary(summary, label) {
+  if (!summary || typeof summary !== 'object' || !summary.tables || typeof summary.tables !== 'object') {
+    throw new Error(`compareStateSummaries: ${label} summary is missing or malformed`);
+  }
+}
+
+/**
+ * Pure comparison of two `summarizeState()` results. A table that was non-empty
+ * before and is empty after is a hard regression, so a fresh/empty database can
+ * never be reported as a match for a populated baseline.
+ *
+ * `opts.ignoreTables` opts specific tables out; everything else is compared.
+ * This module deliberately holds no policy about WHICH tables are durable —
+ * that judgement belongs to the caller, because it depends on what the caller is
+ * gating. The install-time gate in `bin/install-internal-minions.js` derives its
+ * `ignoreTables` from an explicit durable-table ALLOWLIST
+ * (`CONTINUITY_DURABLE_TABLES`) rather than a denylist of volatile tables: most
+ * of the SQL state legitimately shrinks across a package cutover, so a denylist
+ * fails open on every table nobody remembered to enumerate.
+ */
+function compareStateSummaries(before, after, opts = {}) {
+  _assertSummary(before, 'before');
+  _assertSummary(after, 'after');
+  const ignore = new Set(Array.isArray(opts.ignoreTables) ? opts.ignoreTables : []);
+  const regressions = [];
+  const missingTables = [];
+  const emptyAfterNonEmptyBefore = [];
+  for (const table of Object.keys(before.tables).sort()) {
+    if (ignore.has(table)) continue;
+    if (!Object.prototype.hasOwnProperty.call(after.tables, table)) {
+      missingTables.push(table);
+      continue;
+    }
+    const beforeCount = before.tables[table];
+    const afterCount = after.tables[table];
+    // A null count means the table could not be counted on one side; treat it
+    // as unknown rather than inventing a regression.
+    if (!Number.isFinite(beforeCount) || !Number.isFinite(afterCount)) continue;
+    if (beforeCount > 0 && afterCount === 0) emptyAfterNonEmptyBefore.push(table);
+    if (afterCount < beforeCount) regressions.push({ table, before: beforeCount, after: afterCount });
+  }
+  const ok = regressions.length === 0 && missingTables.length === 0 && emptyAfterNonEmptyBefore.length === 0;
+  return { ok, regressions, missingTables, emptyAfterNonEmptyBefore };
+}
+
+/** Open a backup file read-only and run the same integrity + census checks against it. */
+function verifyBackup(backupPath) {
+  if (!backupPath) throw new Error('state verify-backup requires a backup path');
+  const resolved = path.resolve(backupPath);
+  if (!fs.existsSync(resolved)) throw new Error(`backup not found: ${resolved}`);
+  const { installSqliteWarningFilter } = require('../db');
+  installSqliteWarningFilter();
+  const { DatabaseSync } = require('node:sqlite');
+  // Read-only so verifying can never mutate, WAL, or lock the artifact it is
+  // supposed to be vouching for.
+  const db = new DatabaseSync(resolved, { readOnly: true });
+  try {
+    const integrity = checkState(db);
+    const summary = summarizeState(db);
+    return { ok: integrity.ok, path: resolved, integrity, summary };
+  } finally {
+    try { db.close(); } catch { /* already closed */ }
+  }
+}
+
+function exportState(targetPath) {
+  if (!targetPath) throw new Error('state export requires an output path');
+  const resolved = path.resolve(targetPath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  const db = getDb();
+  const tables = _tableNames(db);
+  const data = {
+    format: 'minions-sql-diagnostic-export-v1',
+    exportedAt: new Date().toISOString(),
+    integrity: checkState(),
+    tables: {},
+  };
+  for (const table of tables) {
+    data.tables[table] = db.prepare(`SELECT * FROM "${table}"`).all();
+  }
+  const tmp = `${resolved}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, resolved);
+  return { ok: true, path: resolved, tables: tables.length, bytes: fs.statSync(resolved).size };
+}
+
+function _readJson(filePath, expected) {
+  if (!fs.existsSync(filePath)) return null;
+  const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  if (expected === 'array' && !Array.isArray(value)) throw new Error(`expected array in ${filePath}`);
+  if (expected === 'object' && (!value || typeof value !== 'object' || Array.isArray(value))) {
+    throw new Error(`expected object in ${filePath}`);
+  }
+  return value;
+}
+
+function importLegacyJson(sourceRoot) {
+  if (!sourceRoot) throw new Error('state import-legacy-json requires a source directory');
+  const root = path.resolve(sourceRoot);
+  if (!fs.statSync(root).isDirectory()) throw new Error(`legacy source is not a directory: ${root}`);
+  const imported = {};
+  const replace = (modulePath, fn, value) => {
+    if (value == null) return;
+    require(modulePath)[fn](() => value);
+    imported[fn] = (imported[fn] || 0) + 1;
+  };
+
+  replace(
+    './small-state-store',
+    'applyEngineStateMutation',
+    _readJson(path.join(root, 'engine', 'state.json'), 'object'),
+  );
+  replace('../dispatch-store', 'applyDispatchMutation', _readJson(path.join(root, 'engine', 'dispatch.json'), 'object'));
+  replace('../observability/metrics-store', 'applyMetricsMutation', _readJson(path.join(root, 'engine', 'metrics.json'), 'object'));
+  replace('../watches/store', 'applyWatchesMutation', _readJson(path.join(root, 'engine', 'watches.json'), 'array'));
+
+  const small = [
+    ['schedule-runs.json', 'applyScheduleRunsMutation', 'object'],
+    ['pipeline-runs.json', 'applyPipelineRunsMutation', 'object'],
+    ['managed-processes.json', 'applyManagedProcessesMutation', 'object'],
+    ['worktree-pool.json', 'applyWorktreePoolMutation', 'object'],
+    ['qa-runs.json', 'applyQaRunsMutation', 'array'],
+    ['qa-sessions.json', 'applyQaSessionsMutation', 'array'],
+    ['pr-links.json', 'applyPrLinksMutation', 'object'],
+    ['cooldowns.json', 'applyCooldownsMutation', 'object'],
+    ['pending-rebases.json', 'applyPendingRebasesMutation', 'array'],
+    ['cc-sessions.json', 'applyCcSessionsMutation', 'array'],
+    ['doc-sessions.json', 'applyDocSessionsMutation', 'object'],
+  ];
+  for (const [filename, fn, shape] of small) {
+    replace('./small-state-store', fn, _readJson(path.join(root, 'engine', filename), shape));
+  }
+  replace(
+    './small-state-store',
+    'applyCcGlobalSessionMutation',
+    _readJson(path.join(root, 'engine', 'cc-session.json'), 'object'),
+  );
+
+  const workItemsStore = require('../planning/work-items-store');
+  const pullRequestsStore = require('./pull-requests-store');
+  const importScope = (scope, dir) => {
+    const workItems = _readJson(path.join(dir, 'work-items.json'), 'array');
+    if (workItems) {
+      workItemsStore.applyWorkItemsMutation(scope, () => workItems);
+      imported.workItemScopes = (imported.workItemScopes || 0) + 1;
+    }
+    const archivedWorkItems = _readJson(path.join(dir, 'work-items-archive.json'), 'array');
+    if (archivedWorkItems) {
+      workItemsStore.replaceArchivedWorkItems(scope, archivedWorkItems);
+      imported.archivedWorkItemScopes = (imported.archivedWorkItemScopes || 0) + 1;
+    }
+    const pullRequests = _readJson(path.join(dir, 'pull-requests.json'), 'array');
+    if (pullRequests) {
+      pullRequestsStore.applyPullRequestsMutation(scope, () => pullRequests);
+      imported.pullRequestScopes = (imported.pullRequestScopes || 0) + 1;
+    }
+  };
+  importScope('central', root);
+  try {
+    for (const entry of fs.readdirSync(path.join(root, 'projects'), { withFileTypes: true })) {
+      if (entry.isDirectory() && entry.name !== '.archived') {
+        importScope(entry.name, path.join(root, 'projects', entry.name));
+      }
+    }
+  } catch { /* projects are optional */ }
+
+  const prdStore = require('../planning/prd-store');
+  for (const [dir, archived] of [[path.join(root, 'prd'), false], [path.join(root, 'prd', 'archive'), true]]) {
+    let files = [];
+    try { files = fs.readdirSync(dir).filter(name => name.endsWith('.json')); } catch { continue; }
+    for (const filename of files) {
+      const prd = _readJson(path.join(dir, filename), 'object');
+      prdStore.writePrd(filename, prd, { archived });
+      imported.prds = (imported.prds || 0) + 1;
+    }
+  }
+
+  const logs = _readJson(path.join(root, 'engine', 'log.json'), 'array');
+  if (logs) {
+    const db = getDb();
+    const { withTransaction } = require('../db');
+    withTransaction(db, () => {
+      db.exec('DELETE FROM logs');
+      const insert = db.prepare('INSERT INTO logs (ts_ms, level, message, meta) VALUES (?, ?, ?, ?)');
+      for (const entry of logs) {
+        const timestamp = Date.parse(entry.timestamp);
+        const meta = { ...entry };
+        delete meta.timestamp;
+        delete meta.level;
+        delete meta.message;
+        const { level, message } = entry;
+        insert.run(Number.isFinite(timestamp) ? timestamp : Date.now(), level || 'info', String(message || ''), Object.keys(meta).length ? JSON.stringify(meta) : null);
+      }
+    });
+    imported.logs = logs.length;
+  }
+  return { ok: true, source: root, imported, integrity: checkState() };
+}
+
+module.exports = {
+  checkState,
+  backupState,
+  summarizeState,
+  compareStateSummaries,
+  verifyBackup,
+  exportState,
+  importLegacyJson,
+  _passiveCheckpoint, // exported for testing
+};

package/engine/{steering-store.js → persistence/steering-store.js}

@@ -1,8 +1,8 @@
-// engine/steering-store.js — SQL-backed observable delivery state for
+// engine/persistence/steering-store.js — SQL-backed observable delivery state for
 // inbox steering messages.
 //
 // One row per steering message in the steering_deliveries table.
-// Mirrors the shape of engine/dispatch-store.js / engine/small-state-store.js:
+// Mirrors the shape of engine/persistence/dispatch-store.js / engine/persistence/small-state-store.js:
 //   - routes every read/write through getDb() (no JSON sidecar)
 //   - emits emitStateEvent('steering', {agentId, id, status}) on every
 //     status transition so the dashboard's MAX(events.id) cache check
@@ -80,7 +80,7 @@ function insert(rec) {
     throw new Error(`steering-store.insert: invalid status '${status}'`);
   }
 
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   const db = getDb();
   const existing = db.prepare('SELECT * FROM steering_deliveries WHERE id = ?').get(id);
   if (existing) return _rowToRecord(existing);
@@ -120,7 +120,7 @@ function updateStatus(id, status, opts = {}) {
   if (!VALID_STATUSES.has(status)) {
     throw new Error(`steering-store.updateStatus: invalid status '${status}'`);
   }
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   const db = getDb();
   const row = db.prepare('SELECT * FROM steering_deliveries WHERE id = ?').get(id);
   if (!row) return null;
@@ -159,7 +159,7 @@ function listForAgent(agentId, opts = {}) {
     throw new Error(`steering-store.listForAgent: invalid status '${status}'`);
   }
   let db;
-  try { const { getDb } = require('./db'); db = getDb(); }
+  try { const { getDb } = require('../db'); db = getDb(); }
   catch { return []; }
   const statusClause = status === null ? '' : ' AND status = ?';
   const params = status === null
@@ -177,7 +177,7 @@ function listForAgent(agentId, opts = {}) {
 function getById(id) {
   if (!id) return null;
   let db;
-  try { const { getDb } = require('./db'); db = getDb(); }
+  try { const { getDb } = require('../db'); db = getDb(); }
   catch { return null; }
   const row = db.prepare('SELECT * FROM steering_deliveries WHERE id = ?').get(String(id));
   return _rowToRecord(row);

package/engine/{issues.js → planning/issues.js}

@@ -5,8 +5,8 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync: _execFileSync } = require('child_process');
-const shared = require('./shared');
-const ghToken = require('./gh-token');
+const shared = require('../core/shared');
+const ghToken = require('../providers/gh-token');
 
 const DEFAULT_REPO = 'opg-microsoft/minions';
 const DEFAULT_LABELS = ['bug'];

package/engine/{plan-prd-validation.js → planning/plan-prd-validation.js}

@@ -1,8 +1,8 @@
 'use strict';
 
 const path = require('path');
-const api = require('./api-validation');
-const shared = require('./shared');
+const api = require('../api/api-validation');
+const shared = require('../core/shared');
 
 const COMPLEXITY_VALUES = Object.freeze(['small', 'medium', 'large']);
 const BRANCH_STRATEGY_VALUES = Object.freeze(['parallel', 'shared-branch']);
@@ -37,6 +37,12 @@ const PLAN_ACTION_STATUSES = Object.freeze({
     shared.PLAN_STATUS.AWAITING_APPROVAL,
     shared.PLAN_STATUS.APPROVED,
     shared.PLAN_STATUS.PAUSED,
+    // W-msa0mrus00mh466f — a PRD already in `revision-requested` is gated by the
+    // handler's own revision state machine, not by this table: an ACTIVE
+    // revision is rejected with `revision-in-progress` (plus the existing work
+    // item id), while a FAILED/dangling one must stay re-requestable so the PRD
+    // is not stranded in `revision-requested` with no way out.
+    shared.PLAN_STATUS.REVISION_REQUESTED,
   ]),
   discuss: new Set([
     shared.PLAN_STATUS.AWAITING_APPROVAL,

package/engine/planning/prd-result-sidecar.js

@@ -0,0 +1,190 @@
+// engine/planning/prd-result-sidecar.js
+//
+// The one-shot plan-to-PRD result sidecar contract (W-ms9tcry701xz0389).
+//
+// A plan-to-prd agent writes exactly ONE envelope to
+// `agents/<agent-id>/prd-result.json`:
+//
+//   { "filename": "<expected>.json", "work_item": "W-…", "prd": { … } }
+//
+// The engine validates that envelope against the work item's PERSISTED
+// expected identity (`item._prdFilename`, stable across retries) and imports
+// it into the SQL PRD store. Both import sites — the pre-spawn recovery in
+// `engine.js#discoverCentralWorkItems` and the post-completion import in
+// `engine/orchestration/lifecycle.js` — go through this module so the
+// validation and consume semantics can never drift apart.
+//
+// Two invariants this module exists to hold:
+//
+//  1. FAIL CLOSED. There is no permissive filename fallback: an envelope that
+//     does not DECLARE the expected filename is rejected rather than assumed
+//     to be ours. Combined with the source-plan check (and the optional
+//     `work_item` binding) a sidecar left behind by a different work item or
+//     a different source plan can never be imported.
+//  2. EXACTLY ONCE. The sidecar is CLAIMED with an atomic rename before the
+//     PRD is written, and the claim is removed after a successful import. A
+//     concurrent or repeated consume finds no file, so one sidecar can never
+//     materialize two PRDs, and a consumed sidecar can never be inherited by
+//     a later unrelated dispatch from the same agent.
+
+const fs = require('fs');
+const path = require('path');
+
+const shared = require('../core/shared');
+
+const PRD_RESULT_FILENAME = 'prd-result.json';
+// Sibling of the sidecar, inside the same agent directory, so the claim rename
+// is always an intra-directory (atomic) move on every supported platform.
+const PRD_RESULT_CLAIM_FILENAME = 'prd-result.claimed.json';
+
+// Stable outcome codes. Callers branch on these, never on the prose `reason`.
+const PRD_RESULT_OUTCOME = Object.freeze({
+  IMPORTED: 'imported',
+  ABSENT: 'absent',
+  NO_AGENT: 'no-agent',
+  UNREADABLE: 'unreadable',
+  REJECTED: 'rejected',
+  ALREADY_CONSUMED: 'already-consumed',
+  CLAIM_FAILED: 'claim-failed',
+  IMPORT_FAILED: 'import-failed',
+});
+
+/** Absolute path of an agent's one-shot PRD result sidecar. */
+function prdResultSidecarPath(agentsDir, agentId) {
+  if (!agentsDir || !agentId) return null;
+  return path.join(agentsDir, String(agentId), PRD_RESULT_FILENAME);
+}
+
+/**
+ * Validate a parsed sidecar envelope against the dispatch's authoritative
+ * expectations. Returns `{ ok: true, filename, prd }` or
+ * `{ ok: false, reason }` — never throws for malformed agent input.
+ *
+ * `workItemId` is enforced only when the envelope declares `work_item`: the
+ * field is newer than the filename/source-plan binding, and an envelope that
+ * matches BOTH the expected filename and the source plan is by construction
+ * the PRD for this work item's plan (same-plan work items converge on one
+ * PRD filename by design).
+ */
+function validatePrdResultEnvelope(envelope, { expectedFilename, planFile, workItemId } = {}) {
+  if (!expectedFilename) return { ok: false, reason: 'no expected PRD filename is pinned on the work item' };
+  if (!planFile) return { ok: false, reason: 'work item has no planFile to validate the sidecar against' };
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
+    return { ok: false, reason: 'sidecar is not a JSON object' };
+  }
+
+  const declared = envelope.filename;
+  if (typeof declared !== 'string' || !declared) {
+    return { ok: false, reason: `sidecar does not declare a "filename" (expected "${expectedFilename}")` };
+  }
+  if (declared !== expectedFilename) {
+    return { ok: false, reason: `sidecar filename "${declared}" does not match expected "${expectedFilename}"` };
+  }
+
+  const declaredWi = envelope.work_item;
+  if (declaredWi != null && declaredWi !== '' && workItemId && String(declaredWi) !== String(workItemId)) {
+    return { ok: false, reason: `sidecar work_item "${declaredWi}" belongs to another work item (expected "${workItemId}")` };
+  }
+
+  const prd = envelope.prd;
+  if (!prd || typeof prd !== 'object' || Array.isArray(prd)) {
+    return { ok: false, reason: 'sidecar has no "prd" object' };
+  }
+  if (!shared.prdMatchesSourcePlan(prd.source_plan, planFile)) {
+    return { ok: false, reason: `sidecar source_plan "${prd.source_plan ?? '(unknown)'}" does not match "${planFile}"` };
+  }
+
+  try {
+    require('./prd-store').validatePrdFilename(declared);
+  } catch (err) {
+    return { ok: false, reason: `sidecar filename is not importable: ${err.message}` };
+  }
+
+  return { ok: true, filename: declared, prd };
+}
+
+/**
+ * Read → validate → atomically claim → import → remove an agent's one-shot
+ * PRD result sidecar.
+ *
+ * Returns `{ imported, code, reason, filename }`. `code` is the stable,
+ * machine-readable outcome (`PRD_RESULT_OUTCOME.*`) — callers branch on it
+ * rather than on the human-readable `reason` prose. A rejected sidecar is left
+ * in place untouched (it may legitimately belong to a sibling work item that
+ * has not been retried yet); only a sidecar this call successfully imported is
+ * removed. Never throws.
+ *
+ * `revisionForPrd` is the work item's `_revisionForPrd` reverse stamp
+ * (W-msa0mrus00mh466f). When it names the PRD being imported, the envelope is
+ * normalized through `shared.applyPrdRevisionCompletion` as part of the SAME
+ * `writePrd` that imports it, so a completed revision is never observable
+ * alongside the stale recovery controls it just resolved. The rule lives here
+ * — beside the only write — for the same reason the validation does: both
+ * import sites must apply it identically or a recovered revision silently
+ * lands in a different state than a completed one.
+ */
+function consumePrdResultSidecar({
+  agentsDir, agentId, expectedFilename, planFile, workItemId, revisionForPrd, plansDir,
+} = {}) {
+  const resultPath = prdResultSidecarPath(agentsDir, agentId);
+  if (!resultPath) {
+    return { imported: false, code: PRD_RESULT_OUTCOME.NO_AGENT, reason: 'no agent to read a sidecar from', filename: null };
+  }
+  if (!fs.existsSync(resultPath)) {
+    return { imported: false, code: PRD_RESULT_OUTCOME.ABSENT, reason: 'no sidecar on disk', filename: null };
+  }
+
+  const envelope = shared.safeJsonNoRestore(resultPath);
+  if (envelope === null) {
+    return { imported: false, code: PRD_RESULT_OUTCOME.UNREADABLE, reason: 'sidecar is not readable JSON', filename: null };
+  }
+
+  const verdict = validatePrdResultEnvelope(envelope, { expectedFilename, planFile, workItemId });
+  if (!verdict.ok) {
+    return { imported: false, code: PRD_RESULT_OUTCOME.REJECTED, reason: verdict.reason, filename: null };
+  }
+
+  // Atomic claim: whoever wins the rename owns the import. A loser (or a
+  // repeat call) sees ENOENT and reports "already consumed" instead of
+  // materializing the same PRD twice.
+  const claimPath = path.join(path.dirname(resultPath), PRD_RESULT_CLAIM_FILENAME);
+  try {
+    fs.renameSync(resultPath, claimPath);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { imported: false, code: PRD_RESULT_OUTCOME.ALREADY_CONSUMED, reason: 'sidecar already consumed', filename: null };
+    }
+    return { imported: false, code: PRD_RESULT_OUTCOME.CLAIM_FAILED, reason: `could not claim sidecar: ${err.message}`, filename: null };
+  }
+
+  try {
+    const prdStore = require('./prd-store');
+    // A revision import is normalized into the SAME write that imports it.
+    // Gated on the structural `_revisionForPrd` ⇄ expected-filename relation
+    // (never title text), so a plain regeneration is written untouched.
+    const finalPrd = revisionForPrd && revisionForPrd === expectedFilename
+      ? shared.applyPrdRevisionCompletion(verdict.prd, {
+        plansDir,
+        previous: prdStore.readPrd(expectedFilename),
+      })
+      : verdict.prd;
+    prdStore.writePrd(verdict.filename, finalPrd);
+  } catch (err) {
+    // Import failed — put the sidecar back so the content is not lost and a
+    // later attempt (or the agent's own retry) can still recover it.
+    try { fs.renameSync(claimPath, resultPath); } catch { /* best effort */ }
+    return { imported: false, code: PRD_RESULT_OUTCOME.IMPORT_FAILED, reason: `PRD import failed: ${err.message}`, filename: null };
+  }
+
+  try { fs.unlinkSync(claimPath); } catch { /* claim file is inert once imported */ }
+  return { imported: true, code: PRD_RESULT_OUTCOME.IMPORTED, reason: null, filename: verdict.filename };
+}
+
+module.exports = {
+  PRD_RESULT_FILENAME,
+  PRD_RESULT_CLAIM_FILENAME,
+  PRD_RESULT_OUTCOME,
+  prdResultSidecarPath,
+  validatePrdResultEnvelope,
+  consumePrdResultSidecar,
+};