@yemi33/minions 0.1.2286 → 0.1.2287

package/engine/prd-store.js

@@ -0,0 +1,264 @@
+// engine/prd-store.js
+//
+// Phase 10 step 2: SQL mirror for PRD state. PRD content writes go to the
+// canonical prd/*.json file AND are mirrored into the plans/prds/prd_items/
+// prd_verify_prs tables created by migration 015. JSON stays canonical and is
+// still the only thing read in this step — the SQL side is a passive mirror so
+// the read-flip (step 3) has a trustworthy source.
+//
+// All entry points are BEST-EFFORT: a SQLite failure (Node < 22.5, locked DB,
+// schema not yet migrated) must never break a PRD JSON write. Callers wrap via
+// the thin `mirror*`/`remove*` helpers which swallow and return {ok:false}.
+
+const path = require('path');
+const fs = require('fs');
+
+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 _bool01(v) { return v ? 1 : 0; }
+
+// Resolve <MINIONS_DIR>/prd/<f>.json → {filename, archived:0}; the
+// prd/archive/<f>.json variant → {filename, archived:1}; anything else → null.
+// Path comparison is normalized + case-insensitive on the directory prefix so
+// Windows drive-letter / separator differences don't cause a miss.
+function parsePrdPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+  let minionsDir;
+  try { minionsDir = require('./shared').MINIONS_DIR; } catch { return null; }
+  if (!minionsDir) return null;
+  const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+  const full = norm(filePath);
+  const prdRoot = norm(path.join(minionsDir, 'prd'));
+  const archiveRoot = norm(path.join(minionsDir, 'prd', 'archive'));
+  if (!full.endsWith('.json')) return null;
+  const base = path.basename(filePath);
+  if (full === norm(path.join(archiveRoot, base)) && full.startsWith(archiveRoot + '/')) {
+    return { filename: base, archived: 1 };
+  }
+  if (full === norm(path.join(prdRoot, base)) && full.startsWith(prdRoot + '/')) {
+    return { filename: base, archived: 0 };
+  }
+  return null;
+}
+
+// (filename, archived) → plans.id, preferring the same archived bucket.
+function _resolvePlanId(db, sourcePlan, archived) {
+  if (!sourcePlan) return null;
+  const same = db.prepare('SELECT id FROM plans WHERE filename=? AND archived=? ORDER BY id LIMIT 1').get(sourcePlan, archived);
+  if (same) return same.id;
+  const other = db.prepare('SELECT id FROM plans WHERE filename=? ORDER BY id LIMIT 1').get(sourcePlan);
+  return other ? other.id : null;
+}
+
+// Core upsert: write/replace the prds row + its prd_items + prd_verify_prs for
+// (filename, archived). Returns the prds.id. Runs inside a transaction.
+function _upsertPrd(db, filename, archived, prd, now) {
+  const sourcePlan = prd.source_plan || prd.sourcePlan || null;
+  const planId = _resolvePlanId(db, sourcePlan, archived);
+  const existing = db.prepare('SELECT id, created_at FROM prds WHERE filename=? AND archived=?').get(filename, archived);
+
+  let prdId;
+  if (existing) {
+    prdId = existing.id;
+    db.prepare(`
+      UPDATE prds SET plan_id=?, project=?, version=?, status=?,
+        completed_at=?, completion_notified=?, plan_stale=?, source_plan=?,
+        source_plan_modified_at=?, data=?, updated_at=? WHERE id=?
+    `).run(
+      planId, prd.project || null, prd.version != null ? String(prd.version) : null, prd.status || null,
+      _toMs(prd.completedAt || prd.completed_at), _bool01(prd._completionNotified), _bool01(prd.planStale),
+      sourcePlan, prd.sourcePlanModifiedAt || prd.source_plan_modified_at || null,
+      JSON.stringify(prd), now, prdId,
+    );
+    db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(prdId);
+    db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(prdId);
+  } else {
+    const info = db.prepare(`
+      INSERT INTO prds (plan_id, filename, project, version, status, archived,
+        completed_at, completion_notified, plan_stale, source_plan,
+        source_plan_modified_at, data, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      planId, filename, prd.project || null, prd.version != null ? String(prd.version) : null, prd.status || null, archived,
+      _toMs(prd.completedAt || prd.completed_at), _bool01(prd._completionNotified), _bool01(prd.planStale),
+      sourcePlan, prd.sourcePlanModifiedAt || prd.source_plan_modified_at || null,
+      JSON.stringify(prd), _toMs(prd.generated_at || prd.createdAt) || now, now,
+    );
+    prdId = Number(info.lastInsertRowid);
+  }
+
+  const insItem = db.prepare(`
+    INSERT INTO prd_items (prd_id, feature_id, name, project, status, type, work_item_id, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const features = Array.isArray(prd.missing_features) ? prd.missing_features : [];
+  for (const ft of features) {
+    if (!ft || typeof ft !== 'object') continue;
+    try {
+      insItem.run(prdId, ft.id || null, ft.name || null, ft.project || prd.project || null,
+        ft.status || null, ft.type || null, ft.workItemId || ft.work_item_id || null,
+        JSON.stringify(ft), now);
+    } catch { /* dup (prd_id, feature_id) → skip */ }
+  }
+
+  const insVp = db.prepare(`
+    INSERT INTO prd_verify_prs (prd_id, pr_id, url, title, status, project, merged_at, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const verifyPrs = Array.isArray(prd.verifyPrs) ? prd.verifyPrs : [];
+  for (const vp of verifyPrs) {
+    if (!vp || typeof vp !== 'object') continue;
+    try {
+      insVp.run(prdId, vp.id != null ? String(vp.id) : null, vp.url || null, vp.title || null,
+        vp.status || null, vp.project || prd.project || null, _toMs(vp.mergedAt || vp.merged_at),
+        JSON.stringify(vp), now);
+    } catch { /* best-effort */ }
+  }
+  return prdId;
+}
+
+// Mirror a PRD object to SQL for the given prd/*.json path. Best-effort.
+function mirrorPrdToSql(filePath, prd) {
+  const parsed = parsePrdPath(filePath);
+  if (!parsed || !prd || typeof prd !== 'object' || Array.isArray(prd)) return { ok: false, reason: 'not-a-prd' };
+  try {
+    const { getDb, withTransaction } = require('./db');
+    const db = getDb();
+    withTransaction(db, () => _upsertPrd(db, parsed.filename, parsed.archived, prd, Date.now()));
+    try { require('./db-events').emitStateEvent('prds', { filename: parsed.filename, archived: parsed.archived }); } catch { /* event optional */ }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e && e.message };
+  }
+}
+
+// Remove a PRD (and its items/verify rows) from SQL for the given path. Best-effort.
+function removePrdFromSql(filePath) {
+  const parsed = parsePrdPath(filePath);
+  if (!parsed) return { ok: false, reason: 'not-a-prd' };
+  try {
+    const { getDb, withTransaction } = require('./db');
+    const db = getDb();
+    withTransaction(db, () => {
+      const row = db.prepare('SELECT id FROM prds WHERE filename=? AND archived=?').get(parsed.filename, parsed.archived);
+      if (!row) return;
+      db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(row.id);
+      db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(row.id);
+      db.prepare('DELETE FROM prds WHERE id=?').run(row.id);
+    });
+    try { require('./db-events').emitStateEvent('prds', { filename: parsed.filename, archived: parsed.archived, removed: true }); } catch { /* optional */ }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e && e.message };
+  }
+}
+
+// Read one PRD back from SQL as the original object (the `data` blob). Used by
+// the divergence test now and the read-flip in step 3.
+function readPrdFromSql(filePath) {
+  const parsed = parsePrdPath(filePath);
+  if (!parsed) return null;
+  try {
+    const { getDb } = require('./db');
+    const row = getDb().prepare('SELECT data FROM prds WHERE filename=? AND archived=?').get(parsed.filename, parsed.archived);
+    return row ? JSON.parse(row.data) : null;
+  } catch { return null; }
+}
+
+// Per-process mtime cache so reconciliation re-mirrors only files that actually
+// changed on disk since this process last saw them (empty after restart → the
+// first read re-mirrors everything once). Keyed `${archived} ${filename}`.
+const _reconcileMtimes = new Map();
+
+function _prdDirsFor(minionsDir) {
+  return [
+    { dir: path.join(minionsDir, 'prd'), archived: 0 },
+    { dir: path.join(minionsDir, 'prd', 'archive'), archived: 1 },
+  ];
+}
+
+// Reconcile the SQL mirror from the prd/ + prd/archive/ directories: re-mirror
+// files that are new or changed on disk (catches PRDs written OUTSIDE the
+// mutateJsonFileLocked chokepoint — e.g. the plan-to-prd agent writing the JSON
+// directly, or an archive file-move), and drop SQL rows whose backing file is
+// gone. Best-effort; safe to call on every read. Returns a small stats object.
+function reconcilePrdsFromDisk() {
+  let minionsDir;
+  try { minionsDir = require('./shared').MINIONS_DIR; } catch { return { ok: false }; }
+  if (!minionsDir) return { ok: false };
+  let db;
+  try { db = require('./db').getDb(); } catch { return { ok: false }; }
+
+  let mirrored = 0, removed = 0;
+  const seen = new Set(); // `${archived} ${filename}` present on disk
+  for (const { dir, archived } of _prdDirsFor(minionsDir)) {
+    let files;
+    try { files = fs.readdirSync(dir).filter(f => f.endsWith('.json')); } catch { continue; }
+    for (const f of files) {
+      const key = `${archived} ${f}`;
+      seen.add(key);
+      const full = path.join(dir, f);
+      let mtime;
+      try { mtime = Math.round(fs.statSync(full).mtimeMs); } catch { continue; }
+      if (_reconcileMtimes.get(key) === mtime) continue; // unchanged since last seen
+      const prd = _readJsonObj(full);
+      if (!prd) continue;
+      try {
+        const { withTransaction } = require('./db');
+        withTransaction(db, () => _upsertPrd(db, f, archived, prd, Date.now()));
+        _reconcileMtimes.set(key, mtime);
+        mirrored += 1;
+      } catch { /* best-effort */ }
+    }
+  }
+  // Drop rows whose backing file disappeared (delete/move not caught by a hook).
+  try {
+    const rows = db.prepare('SELECT id, filename, archived FROM prds').all();
+    for (const r of rows) {
+      const key = `${r.archived} ${r.filename}`;
+      if (seen.has(key)) continue;
+      try {
+        require('./db').withTransaction(db, () => {
+          db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(r.id);
+          db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(r.id);
+          db.prepare('DELETE FROM prds WHERE id=?').run(r.id);
+        });
+        _reconcileMtimes.delete(key);
+        removed += 1;
+      } catch { /* best-effort */ }
+    }
+  } catch { /* best-effort */ }
+  return { ok: true, mirrored, removed };
+}
+
+// List every PRD row as { filename, archived, plan } where plan is the parsed
+// data blob. Sorted by (archived, filename) for deterministic consumer order
+// (matches the disk-scan order once the caller also sorts). Read-flip source.
+function listPrdRows() {
+  try {
+    const db = require('./db').getDb();
+    const rows = db.prepare('SELECT filename, archived, data FROM prds ORDER BY archived, filename').all();
+    const out = [];
+    for (const r of rows) {
+      let plan;
+      try { plan = JSON.parse(r.data); } catch { continue; }
+      out.push({ filename: r.filename, archived: !!r.archived, plan });
+    }
+    return out;
+  } catch { return []; }
+}
+
+module.exports = {
+  parsePrdPath,
+  mirrorPrdToSql,
+  removePrdFromSql,
+  readPrdFromSql,
+  reconcilePrdsFromDisk,
+  listPrdRows,
+  _reconcileMtimes, // exported for tests (reset between cases)
+  _upsertPrd, // exported for tests
+};

package/engine/queries.js

@@ -2150,70 +2150,108 @@ function getPrdInfo(config) {
     { dir: PRD_DIR, archived: false },
     { dir: path.join(PRD_DIR, 'archive'), archived: true },
   ];
-  for (const { dir, archived } of planDirs) {
+
+  // Phase 10 step 3 (read-flip) — both the disk scan and the SQL-mirror source
+  // funnel each PRD through this one processor, so the consumed shape
+  // (existingPrds / verifyPrsByPlan / allPrdItems) is identical by construction.
+  // The only difference is where `plan` + `mtimeMs` come from. Equivalence of the
+  // two paths is proven by test/unit/db-phase10-read-flip.test.js.
+  const processPrd = (pf, archived, plan, mtimeMs) => {
+    if (!plan || !plan.missing_features) return;
+    // Staleness: gate on actual source-plan content change rather than mtime
+    // alone (W-mqfevwr60018bd09). Pure path / pure mtime drifts return
+    // stale=false so a repointed source_plan doesn't masquerade as a revision.
+    let planStale = false;
+    if (!archived && plan.source_plan) {
+      try { planStale = shared.isSourcePlanContentStale(PLANS_DIR, plan).stale; } catch { /* optional */ }
+    }
+    existingPrds.push({
+      file: pf,
+      status: plan.status || 'active',
+      planStale: planStale || plan.planStale || false,
+      completedAt: plan.completedAt || '',
+      _archived: archived,
+    });
+    if (Array.isArray(plan.verifyPrs) && plan.verifyPrs.length > 0) {
+      verifyPrsByPlan[pf] = plan.verifyPrs.map(r => ({
+        id: r.id, url: r.url || '', title: r.title || '',
+        status: r.status || 'active', project: r.project || '',
+        ...(r.mergedAt ? { mergedAt: r.mergedAt } : {}),
+      }));
+    }
+    for (const f of plan.missing_features) {
+      allPrdItems.push({
+        ...f, _source: pf, _planStatus: plan.status || 'active',
+        _planSummary: plan.plan_summary || pf, _planProject: plan.project || '',
+        _archived: archived, _sourcePlan: plan.source_plan || '',
+        _branchStrategy: plan.branch_strategy || 'parallel',
+        _planStale: planStale || plan.planStale || false, _lastSyncedFromPlan: plan.lastSyncedFromPlan || null,
+        _prdUpdatedAt: new Date(mtimeMs).toISOString(),
+        _prdCompletedAt: plan.completedAt || '',
+      });
+    }
+  };
+
+  let useSqlReads = false;
+  try { useSqlReads = require('./features').isFeatureOn('prdReadsFromSql', config); } catch { /* fall back to disk */ }
+
+  if (useSqlReads) {
+    // SQL source: reconcile the mirror from disk (catches PRDs written outside
+    // the dual-write chokepoint — plan-to-prd agent direct writes, archive
+    // moves, deletes), then read each PRD's content from SQL. Files still live on
+    // disk in this phase, so stat them for the mtime fields + `age`.
     try {
-      const planFiles = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-      for (const pf of planFiles) {
+      const prdStore = require('./prd-store');
+      prdStore.reconcilePrdsFromDisk();
+      for (const { filename, archived, plan } of prdStore.listPrdRows()) {
         try {
-          const filePath = path.join(dir, pf);
-          const stat = fs.statSync(filePath);
-          if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
-
-          // Per-file mtime cache: only re-read files that changed
-          const cached = _prdFileCache.get(filePath);
-          let plan;
-          if (cached && cached.mtimeMs === stat.mtimeMs) {
-            plan = cached.plan;
-          } else {
-            plan = readJsonNoRestore(filePath);
-            _prdFileCache.set(filePath, { mtimeMs: stat.mtimeMs, plan });
-          }
-          if (!plan || !plan.missing_features) continue;
-
-          // Staleness: gate on actual source-plan content change rather
-          // than mtime alone (W-mqfevwr60018bd09). Pure path / pure mtime
-          // drifts return stale=false here so a repointed source_plan
-          // doesn't masquerade as a real revision in the cached PRD info.
-          let planStale = false;
-          if (!archived && plan.source_plan) {
-            try {
-              planStale = shared.isSourcePlanContentStale(PLANS_DIR, plan).stale;
-            } catch { /* optional */ }
-          }
-          existingPrds.push({
-            file: pf,
-            status: plan.status || 'active',
-            planStale: planStale || plan.planStale || false,
-            completedAt: plan.completedAt || '',
-            _archived: archived,
-          });
-          if (Array.isArray(plan.verifyPrs) && plan.verifyPrs.length > 0) {
-            verifyPrsByPlan[pf] = plan.verifyPrs.map(r => ({
-              id: r.id, url: r.url || '', title: r.title || '',
-              status: r.status || 'active', project: r.project || '',
-              ...(r.mergedAt ? { mergedAt: r.mergedAt } : {}),
-            }));
-          }
-          for (const f of plan.missing_features) {
-            allPrdItems.push({
-              ...f, _source: pf, _planStatus: plan.status || 'active',
-              _planSummary: plan.plan_summary || pf, _planProject: plan.project || '',
-              _archived: archived, _sourcePlan: plan.source_plan || '',
-              _branchStrategy: plan.branch_strategy || 'parallel',
-              _planStale: planStale || plan.planStale || false, _lastSyncedFromPlan: plan.lastSyncedFromPlan || null,
-              _prdUpdatedAt: new Date(stat.mtimeMs).toISOString(),
-              _prdCompletedAt: plan.completedAt || '',
-            });
-          }
+          const dir = archived ? path.join(PRD_DIR, 'archive') : PRD_DIR;
+          let mtimeMs = 0;
+          try {
+            const stat = fs.statSync(path.join(dir, filename));
+            mtimeMs = stat.mtimeMs;
+            if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
+          } catch { /* file may have just moved/deleted between reconcile and read */ }
+          processPrd(filename, archived, plan, mtimeMs);
         } catch { /* optional */ }
       }
-      // Clean stale entries from file cache when dirs changed
-      if (dirsChanged) {
-        for (const cachedPath of _prdFileCache.keys()) {
-          if (cachedPath.startsWith(dir) && !fs.existsSync(cachedPath)) _prdFileCache.delete(cachedPath);
+    } catch {
+      // Hard SQL failure → fall back to the disk scan so the dashboard never
+      // goes blank on a transient DB problem.
+      useSqlReads = false;
+    }
+  }
+
+  if (!useSqlReads) {
+    for (const { dir, archived } of planDirs) {
+      try {
+        const planFiles = fs.readdirSync(dir).filter(f => f.endsWith('.json')).sort();
+        for (const pf of planFiles) {
+          try {
+            const filePath = path.join(dir, pf);
+            const stat = fs.statSync(filePath);
+            if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
+
+            // Per-file mtime cache: only re-read files that changed
+            const cached = _prdFileCache.get(filePath);
+            let plan;
+            if (cached && cached.mtimeMs === stat.mtimeMs) {
+              plan = cached.plan;
+            } else {
+              plan = readJsonNoRestore(filePath);
+              _prdFileCache.set(filePath, { mtimeMs: stat.mtimeMs, plan });
+            }
+            processPrd(pf, archived, plan, stat.mtimeMs);
+          } catch { /* optional */ }
         }
-      }
-    } catch { /* optional */ }
+        // Clean stale entries from file cache when dirs changed
+        if (dirsChanged) {
+          for (const cachedPath of _prdFileCache.keys()) {
+            if (cachedPath.startsWith(dir) && !fs.existsSync(cachedPath)) _prdFileCache.delete(cachedPath);
+          }
+        }
+      } catch { /* optional */ }
+    }
   }
 
   if (allPrdItems.length === 0) return { progress: null, status: null };

package/engine/runtimes/copilot.js

@@ -433,6 +433,17 @@ function _mapEffort(level) {
 // `fallbackModel` opts are silently ignored (their capability flags are false
 // so engine code shouldn't pass them, but we tolerate them gracefully).
 
+// Map MIME type to file extension for --attachment temp file naming.
+const _MIME_EXT = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+};
+function _mimeToExt(mimeType) {
+  return _MIME_EXT[String(mimeType || '').toLowerCase()] || 'bin';
+}
+
 function buildArgs(opts = {}) {
   const {
     model,
@@ -445,6 +456,8 @@ function buildArgs(opts = {}) {
     suppressAgentsMd,
     reasoningSummaries,
     disabledMcpServers,
+    images,
+    tmpDir,
   } = opts;
 
   const args = [
@@ -498,6 +511,22 @@ function buildArgs(opts = {}) {
   // the `=`, commander.js treats the next token as a positional, not the value.
   if (sessionId) args.push(`--resume=${sessionId}`);
 
+  // W-mqv7324u0021db5d — image attachments. Write each base64 payload to a
+  // temp file in tmpDir and emit --attachment <path> (flag is repeatable).
+  // tmpDir is required; skip silently when absent so callers without image
+  // support don't crash (defense-in-depth on top of the caps.imageInput gate).
+  if (Array.isArray(images) && images.length && tmpDir) {
+    for (let i = 0; i < images.length; i++) {
+      const img = images[i];
+      if (!img || !img.dataBase64) continue;
+      const ext = _mimeToExt(img.mimeType);
+      const filename = `img-${i}-${Date.now().toString(36)}.${ext}`;
+      const filePath = path.join(tmpDir, filename);
+      fs.writeFileSync(filePath, Buffer.from(img.dataBase64, 'base64'));
+      args.push('--attachment', filePath);
+    }
+  }
+
   return args;
 }
 
@@ -1214,11 +1243,9 @@ const capabilities = {
   resumePromptCarryover: true,
   // Adapter implements createStreamConsumer(ctx) — required by llm.js accumulator
   streamConsumer: true,
-  // P-7b2e4d01: `--attachment <path>` is documented for non-interactive mode
-  // but the headless smoke test was inconclusive (spike P-3f8a1c92). Stub false
-  // until a clean re-test passes; enabling it also needs temp-file materializing
-  // of the base64 payload (a different adapter-local path than Claude's inline).
-  imageInput: false,
+  // `--attachment <path>` works in non-interactive mode (live-tested; see W-mqv7324u0021db5d).
+  // Base64 payloads are materialized to tmp files inside llmTmpDir before spawn.
+  imageInput: true,
 };
 
 // Install hint surfaced when `resolveBinary()` returns null. Covers all

package/engine/shared.js

@@ -1866,6 +1866,17 @@ function mutateJsonFileLocked(filePath, mutateFn, {
         try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
       }
       safeWrite(filePath, finalData);
+      // Phase 10 step 2 — dual-write PRD content to SQL. The single chokepoint:
+      // every prd/*.json mutation through mutateJsonFileLocked mirrors into the
+      // prds/prd_items/prd_verify_prs tables. JSON stays canonical (nothing
+      // reads SQL yet); this keeps the mirror trustworthy for the read-flip.
+      // BEST-EFFORT: parsePrdPath fast-rejects non-PRD paths, and a SQLite
+      // failure must never break the JSON write. mirrorPrdToSql swallows
+      // internally; the require is guarded for the (engine-agnostic) load order.
+      try {
+        const prdStore = require('./prd-store');
+        if (prdStore.parsePrdPath(filePath)) prdStore.mirrorPrdToSql(filePath, finalData);
+      } catch { /* mirror is best-effort — never break the canonical JSON write */ }
       // Side-effect hook fired only when an actual write happened. Callers
       // use this to emit cache-invalidation signals (events table row) so
       // skip-write-unchanged paths (dedup, idempotent no-op POSTs) don't
@@ -2635,12 +2646,21 @@ const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
 function resolveCheckoutMode(project, workItemType) {
   if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
   const canonical = project.checkoutMode;
-  // liveValidation without checkoutMode: 'live' is a misconfiguration — warn and ignore.
-  if (project.liveValidation && canonical !== CHECKOUT_MODES.LIVE) {
+  // Resolve the effective mode: canonical field first, then legacy worktreeMode fallback.
+  let effectiveMode;
+  if (canonical === CHECKOUT_MODES.LIVE || canonical === CHECKOUT_MODES.WORKTREE) {
+    effectiveMode = canonical;
+  } else if (project.worktreeMode === 'live') {
+    effectiveMode = CHECKOUT_MODES.LIVE;
+  } else {
+    effectiveMode = CHECKOUT_MODES.WORKTREE;
+  }
+  // liveValidation without an effective live mode is a misconfiguration — warn and ignore.
+  if (project.liveValidation && effectiveMode !== CHECKOUT_MODES.LIVE) {
     log('warn', 'resolveCheckoutMode: liveValidation is set but checkoutMode is not "live" — liveValidation ignored',
       { projectName: project.name });
   }
-  if (canonical === CHECKOUT_MODES.LIVE) {
+  if (effectiveMode === CHECKOUT_MODES.LIVE) {
     // Apply liveValidation routing when the block is present and workItemType is provided.
     if (project.liveValidation && workItemType !== undefined) {
       return workItemType === project.liveValidation.type
@@ -2649,11 +2669,6 @@ function resolveCheckoutMode(project, workItemType) {
     }
     return CHECKOUT_MODES.LIVE;
   }
-  if (canonical === CHECKOUT_MODES.WORKTREE) return CHECKOUT_MODES.WORKTREE;
-  // Legacy field fallback (only consulted when checkoutMode is absent/unknown).
-  const legacy = project.worktreeMode;
-  if (legacy === 'live') return CHECKOUT_MODES.LIVE;
-  // legacy 'isolated' (and anything else) → the default worktree behavior.
   return CHECKOUT_MODES.WORKTREE;
 }
 
@@ -4387,6 +4402,7 @@ const FAILURE_CLASS = {
   SPAWN_PHASE_STALL: 'spawn-phase-stall', // W-mq0e2dae000a003d: process spawned and ran startup-only events (MCP init / hooks) but never emitted real task progress; CPU usage stayed below threshold past the grace window. Engine kills the wedged child and treats this as retryable (fresh-session) so a re-spawn can clear a transient MCP wedge.
   OUTPUT_TRUNCATED: 'output-truncated',   // P-8e4c2a17: the agent streamed more stdout than the engine's hard capture cap (engine.js AGENT_OUTPUT_CAP_BYTES, 1MB) BEFORE the terminal `result` event arrived. The result (session id, completion block, final text) lives at the END of the stream, so it fell outside the captured window and parseOutput found nothing — the dispatch would otherwise fail as an opaque UNKNOWN and retry to death. Surfaced loudly with an actionable message; non-retryable (mechanical retry just reproduces the overflow — the agent must reduce output volume or the task must be split).
   VERIFY_MISSING_PR: 'verify-missing-pr', // W-mqsk1ip00006cbae: a verify WI exited done but no PR was attached (neither _prUrl/_pr on the item nor a matching pull-requests.json entry for the plan). Flipped to failed so the plan doesn't silently advance without an E2E PR. Retryable — agent may have phantom-crashed before pushing the branch.
+  PROJECT_NOT_FOUND: 'project_not_found', // W-mqv2wsy30002e090: a work item's `project` field names a project that is not configured (resolveConfiguredProject / formatUnknownProjectError → `Project "<name>" not found. Known projects: …`). Stamped at discovery time so the dashboard PR-column renderer surfaces the red failReason snippet like other non-retryable failures instead of burying it in the Agent column. Non-retryable — operator must fix the WI's project field or configure the project.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 

package/engine/watch-actions.js

@@ -562,7 +562,10 @@ registerActionType(WATCH_ACTION_TYPE.WEBHOOK, {
 // minions-api — first-class loopback API caller for the in-process dashboard.
 // Restricts `endpoint` to paths starting with `/api/` so a watch can't reach
 // external hosts (use `webhook` for that). Always targets
-// `http://127.0.0.1:${MINIONS_PORT||7331}${endpoint}` and sets
+// `http://127.0.0.1:${shared.readDashboardPortFile(MINIONS_DIR)?.port||7331}${endpoint}`
+// — the *actual* bound dashboard port from the dashboard-port.json beacon, not
+// the frozen MINIONS_PORT env (which stays at the requested value when the
+// dashboard falls back to 7332+ on EADDRINUSE) — and sets
 // `X-Minions-Internal: 1` so dashboard handlers can recognize that the
 // request originated from the engine's own action surface (Origin/Referer
 // are intentionally absent — the dashboard's origin gate already allows