@yemi33/minions 0.1.2369 → 0.1.2371

package/engine/lifecycle.js

@@ -16,7 +16,6 @@ const queries = require('./queries');
 const harness = require('./harness');
 const { isBranchActive } = require('./cooldown');
 const { worktreeMatchesBranch, getWorktreeBranch, cleanupMergedPrLocalBranch } = require('./cleanup');
-const { buildHarnessUsedSection } = require('./comment-format');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
   MINIONS_DIR, ENGINE_DIR, PLANS_DIR, PRD_DIR, INBOX_DIR, AGENTS_DIR } = queries;
 
@@ -520,17 +519,9 @@ function checkPlanCompletion(meta, config) {
 function archivePlan(planFile, plan, projects, config) {
   const planPath = path.join(PRD_DIR, planFile);
 
-  // Phase 10 — archive the PRD IN PLACE: flag it (archived/status/archivedAt)
-  // where it sits, rather than MOVING it to prd/archive/. This matches the
-  // canonical dashboard (_archivePrdPostProcess, #533) + watch-action archive
-  // paths. The legacy move was the LAST path still physically relocating a PRD,
-  // and it reintroduced the live↔archive basename-collision class (footgun #7)
-  // that the in-place flag model retired — plus it needed a .backup neutralize
-  // that is moot now that prd/*.json never gets a .backup sidecar at all (#570).
-  // mutateJsonFileLocked dual-writes the flag into SQL via the chokepoint; the
-  // archived-PRD scanner guards (#530) already treat status:'archived' correctly.
+  // Archive in place by flagging the authoritative SQL PRD.
   try {
-    if (fs.existsSync(planPath)) {
+    if (safeJsonNoRestore(planPath)) {
       mutateJsonFileLocked(planPath, (data) => {
         if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
         data.status = 'archived';
@@ -842,7 +833,9 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
   if (!_VALID_PRD_STATUSES.has(status)) return;
   try {
     const prdDir = path.join(MINIONS_DIR, 'prd');
-    const files = sourcePlan ? [sourcePlan] : require('fs').readdirSync(prdDir).filter(f => f.endsWith('.json'));
+    const files = sourcePlan
+      ? [sourcePlan]
+      : require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
     for (const pf of files) {
       const fpath = path.join(prdDir, pf);
       // Lock-free peek: most PRDs won't contain the ID, so skip the lock cost.
@@ -880,7 +873,6 @@ function stampPrdItemWorkItemId(itemId, sourcePlan) {
   if (!itemId || !sourcePlan) return;
   try {
     const fpath = path.join(PRD_DIR, sourcePlan);
-    if (!fs.existsSync(fpath)) return;
     const plan = safeJsonNoRestore(fpath);
     const feature = plan?.missing_features?.find(f => f.id === itemId);
     if (!feature || feature.workItemId === itemId) return;
@@ -896,7 +888,6 @@ function stampPrdItemPrUrl(itemId, sourcePlan, prUrl) {
   if (!itemId || !sourcePlan || !prUrl) return;
   try {
     const fpath = path.join(PRD_DIR, sourcePlan);
-    if (!fs.existsSync(fpath)) return;
     const plan = safeJsonNoRestore(fpath);
     const feature = plan?.missing_features?.find(f => f.id === itemId);
     if (!feature || feature.pr_url === prUrl) return;
@@ -916,9 +907,7 @@ function stampPrdItemPrUrl(itemId, sourcePlan, prUrl) {
 //    different ID than the original PRD feature, leaving the PRD status stale.
 
 function reconcilePrdStatuses(config) {
-  if (!fs.existsSync(PRD_DIR)) return;
-  let prdFiles;
-  try { prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json')); } catch { return; }
+  const prdFiles = require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
   if (prdFiles.length === 0) return;
 
   const allWorkItems = queries.getWorkItems(config);
@@ -1537,35 +1526,17 @@ function stampWiPrRef(meta, config) {
   const projects = (config && Array.isArray(config.projects))
     ? config.projects : shared.getProjects(config || {});
 
-  // 1. Search each project's pull-requests.json.
-  let found = null;
-  for (const p of projects) {
-    const pr = safeJsonArr(projectPrPath(p)).find(
-      r => Array.isArray(r.prdItems) && r.prdItems.includes(itemId)
-    );
-    if (pr) { found = pr; break; }
-  }
+  const prStore = require('./pull-requests-store');
+  const allPrs = prStore.readAllPullRequests();
+  let found = allPrs.find(r => Array.isArray(r.prdItems) && r.prdItems.includes(itemId)) || null;
 
-  // 2. Fall back to central pull-requests.json.
-  if (!found) {
-    found = safeJsonArr(path.join(MINIONS_DIR, 'pull-requests.json')).find(
-      r => Array.isArray(r.prdItems) && r.prdItems.includes(itemId)
-    );
-  }
-
-  // 3. Fall back to pr-links index (catches cases where prdItems wasn't
+  // Fall back to pr-links index (catches cases where prdItems wasn't
   //    populated but a pr-links entry links the PR to this WI).
   if (!found) {
     const prLinks = getPrLinks();
     const linkedPrId = Object.keys(prLinks).find(id => (prLinks[id] || []).includes(itemId));
     if (linkedPrId) {
-      for (const p of projects) {
-        const pr = safeJsonArr(projectPrPath(p)).find(r => r.id === linkedPrId);
-        if (pr) { found = pr; break; }
-      }
-      if (!found) {
-        found = safeJsonArr(path.join(MINIONS_DIR, 'pull-requests.json')).find(r => r.id === linkedPrId);
-      }
+      found = allPrs.find(r => r.id === linkedPrId) || null;
       // Worst case: only the canonical ID is known — at least stamp _pr.
       if (!found) found = { id: linkedPrId };
     }
@@ -1632,21 +1603,15 @@ function isPrAttachmentRequired(type, item, meta = {}) {
 
 function readOptionalJsonStrict(filePath, label, validate) {
   if (!filePath) return null;
-  let raw;
-  try {
-    raw = fs.readFileSync(filePath, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') return null;
-    throw new Error(`Cannot read ${label} JSON at ${filePath}: ${err.message}`);
-  }
   let parsed;
   try {
-    parsed = JSON.parse(raw);
+    parsed = shared.safeJson(filePath);
   } catch (err) {
-    throw new Error(`Corrupt ${label} JSON at ${filePath}: ${err.message}`);
+    throw new Error(`Cannot read ${label} state at ${filePath}: ${err.message}`);
   }
+  if (parsed == null) return null;
   if (validate && !validate(parsed)) {
-    throw new Error(`Invalid ${label} JSON shape at ${filePath}`);
+    throw new Error(`Invalid ${label} state shape at ${filePath}`);
   }
   return parsed;
 }
@@ -2109,7 +2074,7 @@ function markPrAttachmentVerificationError(meta, agentId, reason, resultSummary)
   const wiPath = resolveWorkItemPath(meta);
   let syncFailedToPrd = false;
   if (wiPath) {
-    mutateJsonFileLocked(wiPath, data => {
+    mutateWorkItems(wiPath, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
@@ -2253,7 +2218,7 @@ function enforceVerifyPrContract(type, meta, agentId, config, resultSummary) {
 
   const wiPath = resolveWorkItemPath(meta);
   if (wiPath) {
-    mutateJsonFileLocked(wiPath, data => {
+    mutateWorkItems(wiPath, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === item.id);
       if (!w) return data;
@@ -3701,7 +3666,7 @@ async function handlePostMerge(pr, project, config, newStatus) {
     // Mark PRD feature as implemented
     const prdDir = path.join(MINIONS_DIR, 'prd');
     try {
-      const planFiles = fs.readdirSync(prdDir).filter(f => f.endsWith('.json'));
+      const planFiles = require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
       let updated = 0;
       for (const pf of planFiles) {
         const planPath = path.join(prdDir, pf);
@@ -4247,28 +4212,6 @@ function handleInjectionFlag(dispatchItem, agentId, structuredCompletion, config
   return { description, sources, at };
 }
 
-// resolveHarnessPropagated(dispatchItem) — P-c6f5e8b3. Locate the spawn-time
-// `_harnessPropagated` manifest for a dispatch. The in-memory dispatchItem
-// (spawnAgent's closure object) normally carries it directly; after an engine
-// restart + re-attach the field may only live on the persisted dispatch record,
-// so fall back to scanning the live dispatch queues by id. Returns null when no
-// manifest was captured (grounding then marks every entry grounded:false — the
-// honest "no record" state).
-function resolveHarnessPropagated(dispatchItem) {
-  if (!dispatchItem) return null;
-  if (dispatchItem._harnessPropagated) return dispatchItem._harnessPropagated;
-  try {
-    const dispatch = getDispatch();
-    for (const queue of ['active', 'completed', 'pending']) {
-      const list = Array.isArray(dispatch?.[queue]) ? dispatch[queue] : null;
-      if (!list) continue;
-      const found = list.find(d => d && d.id === dispatchItem.id);
-      if (found && found._harnessPropagated) return found._harnessPropagated;
-    }
-  } catch { /* best-effort */ }
-  return null;
-}
-
 function parseCompletionReportFile(dispatchItem, opts = {}) {
   const reportPath = dispatchItem?.meta?.completionReportPath || shared.dispatchCompletionReportPath(dispatchItem?.id);
   if (!reportPath || !fs.existsSync(reportPath)) {
@@ -4434,19 +4377,7 @@ function promoteCompletionArtifacts(meta, agentId, dispatchId, structuredComplet
   const outputLog = opts.outputLog ? String(opts.outputLog) : '';
   const branch = opts.branch || meta.branch || '';
   const resultSummary = opts.resultSummary ? String(opts.resultSummary).slice(0, 500) : '';
-  // P-d5a6f7c4 (Harness Transparency, Stage 3 — surface). The grounded
-  // harnessUsed object (canonical { skills, mcpServers, commands, docs } shape
-  // with a strict-boolean `grounded` on each entry, produced upstream in
-  // runPostCompletionHooks via shared.groundHarnessUsed) rides here on
-  // structuredCompletion.harnessUsed. Persist it onto the work item as
-  // `_harnessUsed` so the dashboard work-item detail modal can render the
-  // "Repo harnesses used" section. `null`/absent when the agent reported no
-  // harness usage; only a plain-object survives normalization upstream.
-  const harnessUsed = shared.isPlainObject(structuredCompletion?.harnessUsed)
-    ? structuredCompletion.harnessUsed
-    : null;
-
-  if (artifacts.length === 0 && notes.length === 0 && !outputLog && !branch && !resultSummary && !harnessUsed) {
+  if (artifacts.length === 0 && notes.length === 0 && !outputLog && !branch && !resultSummary) {
     return { artifacts, notes };
   }
 
@@ -4465,7 +4396,6 @@ function promoteCompletionArtifacts(meta, agentId, dispatchId, structuredComplet
     if (meta.item?.sourcePlan) arts.sourcePlan = meta.item.sourcePlan;
     if (artifacts.length > 0) wi.artifacts = mergeCompletionArtifacts(wi.artifacts, artifacts);
     if (resultSummary) wi.resultSummary = resultSummary;
-    if (harnessUsed) wi._harnessUsed = harnessUsed;
     wi._artifacts = arts;
     return data;
   }, { defaultValue: [], skipWriteIfUnchanged: true });
@@ -4798,11 +4728,6 @@ function writeNonCleanAgentReport(dispatchItem, agentId, outcome, structuredComp
   const structuredLines = structuredCompletion
     ? Object.entries(structuredCompletion).map(([key, value]) => `- ${key}: ${value}`).join('\n')
     : '- none';
-  // #308 — fold the agent's grounded harness footprint into THIS final agent
-  // report instead of emitting a separate `harness-usage-*` inbox note per
-  // attempt. buildHarnessUsedSection returns '' for an absent/empty/malformed
-  // record, so the section is appended only when there is something to show.
-  const harnessSection = buildHarnessUsedSection(structuredCompletion?.harnessUsed);
   const content = [
     `# Agent ${outcome === 'partial' ? 'Partially Completed' : 'Reported Failure'}: ${title}`,
     '',
@@ -4817,7 +4742,6 @@ function writeNonCleanAgentReport(dispatchItem, agentId, outcome, structuredComp
     structuredLines,
     '',
     resultSummary ? `## Summary\n${resultSummary}` : '## Summary\n(no agent summary captured)',
-    harnessSection ? `\n${harnessSection}` : '',
   ].filter(Boolean).join('\n');
   shared.writeToInbox(agentId || 'engine', `agent-${outcome}-${dispatchItem.id}`, content, null, metadata);
 }
@@ -5389,6 +5313,81 @@ function applyGoalInvalidation(sourceWiId, invalidates, config) {
   }
 }
 
+function captureTaskMemoryEpisode(dispatchItem, agentId, outcome, structuredCompletion, resultSummary, config) {
+  if ((config?.engine?.memoryEpisodicCapture ?? ENGINE_DEFAULTS.memoryEpisodicCapture) !== true) return null;
+  if (!dispatchItem || !dispatchItem.id) return null;
+  if (structuredCompletion?.failure_class === FAILURE_CLASS.INJECTION_FLAGGED) return null;
+
+  const meta = dispatchItem.meta || {};
+  const item = meta.item || {};
+  const project = meta.project?.name
+    || (item._source && item._source !== 'central' ? item._source : '')
+    || dispatchItem.project
+    || '';
+  const files = structuredCompletion?.files_changed
+    || structuredCompletion?.affected_files
+    || [];
+  const redact = typeof shared.redactSecrets === 'function' ? shared.redactSecrets : String;
+  const fileList = (Array.isArray(files) ? files : String(files || '').split(','))
+    .map(value => redact(String(value).trim()).slice(0, 300))
+    .filter(Boolean)
+    .slice(0, 20);
+  const rawTests = structuredCompletion?.tests || 'N/A';
+  const tests = Array.isArray(rawTests)
+    ? rawTests.slice(0, 20).map(value => redact(String(value)).slice(0, 500))
+    : redact(String(rawTests)).slice(0, 2000);
+  const pr = redact(String(structuredCompletion?.pr || item._prUrl || item._pr || 'N/A')).slice(0, 1000);
+  const failureClass = redact(String(structuredCompletion?.failure_class || 'N/A')).slice(0, 200);
+  const safeSummary = redact(String(resultSummary || structuredCompletion?.summary || 'No summary reported')).slice(0, 4000);
+  const title = redact(String(item.title || item.name || dispatchItem.title || item.id || dispatchItem.id)).slice(0, 500);
+  const body = [
+    `Outcome: ${outcome}`,
+    `Work item: ${item.id || 'N/A'}`,
+    `Work type: ${dispatchItem.type || item.type || 'N/A'}`,
+    `Agent: ${agentId || dispatchItem.agent || 'unknown'}`,
+    `Project: ${project || 'N/A'}`,
+    `PR: ${pr}`,
+    `Tests: ${Array.isArray(tests) ? tests.join(', ') : tests}`,
+    `Failure class: ${failureClass}`,
+    fileList.length ? `Files: ${fileList.join(', ')}` : 'Files: N/A',
+    '',
+    'Summary:',
+    safeSummary,
+  ].join('\n');
+
+  try {
+    return require('./memory-store').upsertMemoryRecord({
+      memoryType: 'episodic',
+      scopeType: project ? 'project' : (agentId ? 'agent' : 'global'),
+      scopeKey: project || agentId || '',
+      title: `${outcome}: ${title}`,
+      body,
+      tags: ['task-episode', dispatchItem.type || item.type || 'unknown', outcome, ...fileList.slice(0, 12)],
+      sourceType: 'dispatch',
+      sourceRef: String(dispatchItem.id),
+      sourcePath: structuredCompletion?._path || null,
+      trust: 'system',
+      importance: outcome === 'failed' ? 0.85 : (outcome === 'partial' ? 0.75 : 0.6),
+      confidence: structuredCompletion ? 0.8 : 0.55,
+      metadata: {
+        dispatchId: dispatchItem.id,
+        workItemId: item.id || null,
+        agent: agentId || dispatchItem.agent || null,
+        project: project || null,
+        outcome,
+        workType: dispatchItem.type || item.type || null,
+        pr,
+        tests,
+        failureClass,
+        files: fileList,
+      },
+    });
+  } catch (err) {
+    log('warn', `Task memory episode write failed for ${dispatchItem.id}: ${err.message}`);
+    return null;
+  }
+}
+
 async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config, opts) {
 
   const detectPhantom = !!(opts && opts.detectPhantom);
@@ -5484,31 +5483,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       structuredCompletion.status = 'failed-injection-flagged';
     }
   }
-  // P-c6f5e8b3 — harness grounding cross-check (Stage 2). Cross-check the
-  // agent's self-reported `harnessUsed` against the spawn-time
-  // `_harnessPropagated` manifest and annotate each entry `grounded:true|false`.
-  // The grounded result replaces `structuredCompletion.harnessUsed` IN PLACE, so
-  // it rides the existing `structuredCompletion` storage onto the completed
-  // dispatch record (completeDispatch persists `item.structuredCompletion`) for
-  // the Stage-3 surfaces (PR comment / final agent note / WI modal) to read.
-  // Pure, non-destructive (grounded:false entries are kept + flagged, never
-  // dropped), and best-effort: any failure here must never block completion.
-  //
-  // #308 — the grounded footprint is no longer routed to its own
-  // `harness-usage-*` inbox note (that produced one duplicate-looking note chip
-  // per attempt). For clean completions the structured `_harnessUsed` WI-modal
-  // UI surfaces it; for non-clean outcomes writeNonCleanAgentReport folds the
-  // same buildHarnessUsedSection block into the single final agent note.
-  if (structuredCompletion && structuredCompletion.harnessUsed) {
-    try {
-      const propagated = resolveHarnessPropagated(dispatchItem);
-      const grounded = shared.groundHarnessUsed(structuredCompletion.harnessUsed, propagated);
-      structuredCompletion.harnessUsed = grounded; // canonical grounded shape, or null when nothing survived
-    } catch (err) {
-      log('warn', `Harness grounding cross-check failed for ${dispatchItem.id} (non-fatal): ${err.message}`);
-    }
-  }
-
   const completionGateSummary = resultSummary || (typeof stdout === 'string' && !stdout.includes('"type":') ? stdout : '');
 
   // Save session for potential resume on next dispatch
@@ -5577,6 +5551,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
   }
   const effectiveSuccess = !nonceMismatch && ((isSuccess && !agentReportedFailure) || autoRecovered);
+  if (!nonceMismatch) {
+    const episodeOutcome = effectiveSuccess
+      ? (autoRecovered || completionStatus.startsWith('partial') ? 'partial' : 'success')
+      : 'failed';
+    captureTaskMemoryEpisode(dispatchItem, agentId, episodeOutcome, structuredCompletion, completionGateSummary, config);
+  }
 
   let nonCleanReportWritten = false;
   if (completionStatus.startsWith('partial') || autoRecovered || (agentReportedFailure && isSuccess)) {
@@ -5682,59 +5662,49 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
-  // Verify plan-to-prd actually created the PRD file before marking done (#893)
+  // Import the plan-to-prd result sidecar into the authoritative SQL store
+  // before marking the work item done.
   // Must run BEFORE updateWorkItemStatus(DONE) — otherwise _retryCount is deleted and retries never advance
   if (effectiveSuccess && type === WORK_TYPE.PLAN_TO_PRD && meta?.item?.id) {
     let prdFound = false;
     let resolvedPrdFilename = null;
     const expectedFile = meta.item._prdFilename;
-    if (expectedFile) {
-      // Inline `fs.existsSync(path.join(PRD_DIR, expectedFile))` is the literal
-      // substring pinned by source-text regression test (test/unit.test.js#893).
-      // Do not refactor into a temp variable without updating that assertion.
-      if (fs.existsSync(path.join(PRD_DIR, expectedFile))) {
-        // Defense-in-depth (W-mozkn1bb001j66fd): a near-simultaneous plan-to-prd
-        // dispatch for a different plan may have clobbered our pinned filename.
-        // Verify the file's source_plan matches our planFile before accepting it.
-        // Without this check we'd mark the WI done against ANOTHER plan's PRD.
-        if (meta.item.planFile) {
-          try {
-            const prd = safeJson(path.join(PRD_DIR, expectedFile));
-            if (prd && shared.prdMatchesSourcePlan(prd.source_plan, meta.item.planFile)) {
-              prdFound = true;
-              resolvedPrdFilename = expectedFile;
-            } else {
-              log('warn', `plan-to-prd ${meta.item.id}: file "${expectedFile}" exists but source_plan="${prd?.source_plan ?? '(unknown)'}" doesn't match expected planFile="${meta.item.planFile}" — possible collision, scanning by source_plan`);
-            }
-          } catch (e) {
-            // Unparseable PRD file — log and accept (legacy behavior). A real
-            // collision could hide behind a parse error, so the warn keeps the
-            // anomaly visible for follow-up rather than failing silently.
-            log('warn', `plan-to-prd ${meta.item.id}: file "${expectedFile}" exists but failed to parse (${e.message}) — accepting as legacy behavior; manual inspection recommended if this recurs`);
-            prdFound = true;
-            resolvedPrdFilename = expectedFile;
-          }
-        } else {
-          // No planFile to verify against — fall back to legacy existence check.
-          prdFound = true;
-          resolvedPrdFilename = expectedFile;
+    const prdStore = require('./prd-store');
+    const agentId = meta._agentId || meta.item.dispatched_to;
+    const resultPath = agentId ? path.join(AGENTS_DIR, agentId, 'prd-result.json') : null;
+    if (expectedFile && resultPath && fs.existsSync(resultPath)) {
+      try {
+        const envelope = shared.safeJsonNoRestore(resultPath);
+        const filename = envelope?.filename || expectedFile;
+        const prd = envelope?.prd || envelope;
+        if (filename !== expectedFile) {
+          throw new Error(`sidecar filename "${filename}" does not match expected "${expectedFile}"`);
+        }
+        if (!prd || !shared.prdMatchesSourcePlan(prd.source_plan, meta.item.planFile)) {
+          throw new Error(`sidecar source_plan "${prd?.source_plan ?? '(unknown)'}" does not match "${meta.item.planFile}"`);
         }
+        prdStore.writePrd(path.join(PRD_DIR, expectedFile), prd);
+        fs.unlinkSync(resultPath);
+      } catch (e) {
+        log('warn', `plan-to-prd ${meta.item.id}: could not import result sidecar: ${e.message}`);
+      }
+    }
+    for (const { filename, archived, plan } of prdStore.listPrdRows()) {
+      if (!archived && filename === expectedFile
+        && (!meta.item.planFile || shared.prdMatchesSourcePlan(plan.source_plan, meta.item.planFile))) {
+        prdFound = true;
+        resolvedPrdFilename = filename;
+        break;
       }
     }
     if (!prdFound && meta.item.planFile) {
-      try {
-        for (const f of fs.readdirSync(PRD_DIR)) {
-          if (!f.endsWith('.json')) continue;
-          try {
-            const prd = safeJson(path.join(PRD_DIR, f));
-            if (prd && !shared.isPrdArchived(prd) && shared.prdMatchesSourcePlan(prd.source_plan, meta.item.planFile)) {
-              prdFound = true;
-              resolvedPrdFilename = f;
-              break;
-            }
-          } catch {}
+      for (const { filename, archived, plan } of prdStore.listPrdRows()) {
+        if (!archived && shared.prdMatchesSourcePlan(plan.source_plan, meta.item.planFile)) {
+          prdFound = true;
+          resolvedPrdFilename = filename;
+          break;
         }
-      } catch {}
+      }
     }
     // Migrate _prdFilename when the source_plan scan found our PRD under a
     // different on-disk filename (e.g. agent bumped past a clobbered name, or
@@ -5773,7 +5743,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
             // buildWorkItemDispatchVars()'s retry_context var (W-mrbq53ra000lf2e5) so the
             // retried agent knows the PRD file was never found instead of silently
             // repeating the same mistake.
-            const gateReason = `Validation gate (#893): no PRD JSON file was found on disk for planFile "${meta.item.planFile || w.planFile || '(unknown)'}" (expected "${expectedFile || '(unset)'}") after the previous attempt completed. Write the PRD JSON to the exact path specified in the playbook before finishing.`;
+            const gateReason = `Validation gate (#893): no PRD result sidecar was imported for planFile "${meta.item.planFile || w.planFile || '(unknown)'}" (expected filename "${expectedFile || '(unset)'}") after the previous attempt completed. Write agents/<agent-id>/prd-result.json exactly as specified in the playbook before finishing.`;
             if (retries < ENGINE_DEFAULTS.maxRetries) {
               w.status = WI_STATUS.PENDING;
               w._retryCount = retries + 1;
@@ -5785,13 +5755,13 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               if (failedAgent) shared.bumpAgentRetryCount(w, failedAgent);
               delete w.dispatched_at;
               delete w.completedAt;
-              log('warn', `plan-to-prd ${meta.item.id} completed without PRD file — auto-retry ${retries + 1}/${ENGINE_DEFAULTS.maxRetries}`);
+              log('warn', `plan-to-prd ${meta.item.id} completed without PRD result — auto-retry ${retries + 1}/${ENGINE_DEFAULTS.maxRetries}`);
             } else {
               w.status = WI_STATUS.FAILED;
-              w.failReason = 'PRD file not written after ' + ENGINE_DEFAULTS.maxRetries + ' attempts';
+              w.failReason = 'PRD result not written after ' + ENGINE_DEFAULTS.maxRetries + ' attempts';
               w.failedAt = ts();
               w._lastRetryReason = gateReason;
-              log('warn', `plan-to-prd ${meta.item.id} failed — no PRD file after ${ENGINE_DEFAULTS.maxRetries} retries`);
+              log('warn', `plan-to-prd ${meta.item.id} failed — no PRD result after ${ENGINE_DEFAULTS.maxRetries} retries`);
             }
             return data;
           }, { skipWriteIfUnchanged: true });
@@ -6391,9 +6361,7 @@ function syncPrdFromPrs(config) {
 // Paused, rejected, awaiting-approval, completed, and archived PRDs are
 // skipped via _PRD_FROZEN_STATUSES. The locked write is idempotent.
 function advancePrdStatusOnAllItemsDone(config) {
-  if (!fs.existsSync(PRD_DIR)) return;
-  let prdFiles;
-  try { prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json')); } catch { return; }
+  const prdFiles = require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
   if (!prdFiles.length) return;
 
   const allWorkItems = queries.getWorkItems(config);
@@ -6513,7 +6481,6 @@ function _verifyPrsNeedUpdate(existing, refMap) {
 function persistVerifyPrsToPrd(config) {
   try {
     config = config || queries.getConfig();
-    if (!fs.existsSync(PRD_DIR)) return;
     const projects = shared.getProjects(config);
     if (!projects.length) return;
 
@@ -6538,7 +6505,7 @@ function persistVerifyPrsToPrd(config) {
     for (const [planFile, refMap] of refsByPlan) {
       // Resolve the PRD file (active or archived). sourcePlan is a bare filename.
       const candidates = [path.join(PRD_DIR, planFile), path.join(PRD_DIR, 'archive', planFile)];
-      const fpath = candidates.find(p => { try { return fs.existsSync(p); } catch { return false; } });
+      const fpath = candidates.find(p => safeJsonNoRestore(p));
       if (!fpath) continue;
 
       // Lock-free peek (mirrors syncPrdItemStatus): only take the write lock
@@ -7101,11 +7068,12 @@ module.exports = {
   enforceVerifyPrContract,
   markMissingPrAttachment,
   parseCompletionReportFile,
-  resolveHarnessPropagated,
   // #308 — exported for unit testing: the final non-clean agent note now folds
   // the grounded harness footprint in as a section instead of emitting a
   // standalone harness-usage-* inbox note.
   writeNonCleanAgentReport,
+  // exported for testing
+  captureTaskMemoryEpisode,
   normalizeCompletionArtifacts,
   completionArtifactToNoteEntry,
   mergeArtifactNotes,

package/engine/llm.js

@@ -345,7 +345,7 @@ function _runtimeUnavailableResult(callOpts = {}) {
  * Capability gating (matches engine.js _buildAgentSpawnFlags from P-2a6d9c4f):
  *   - effort/sessionId/maxBudget/bare/fallbackModel are dropped when the
  *     runtime's matching capability is false.
- *   - Copilot-specific opts (stream, disableBuiltinMcps, suppressAgentsMd,
+ *   - Copilot-specific opts (stream, disableBuiltinMcps,
  *     reasoningSummaries) are emitted unconditionally; the Claude adapter
  *     ignores them via the "tolerate unknown opts" rule.
  */
@@ -365,7 +365,6 @@ function _buildSpawnAgentFlags(runtime, opts = {}) {
 
   if (opts.stream === 'on' || opts.stream === 'off') flags.push('--stream', opts.stream);
   if (opts.disableBuiltinMcps === true) flags.push('--disable-builtin-mcps');
-  if (opts.suppressAgentsMd === true) flags.push('--no-custom-instructions');
   if (opts.reasoningSummaries === true) flags.push('--enable-reasoning-summaries');
 
   return flags;
@@ -387,7 +386,7 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
   const {
     direct, label, runtime, model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel,
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    stream, disableBuiltinMcps, reasoningSummaries,
     images,
   } = callOpts;
 
@@ -403,7 +402,7 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
   const adapterOpts = {
     model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel,
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    stream, disableBuiltinMcps, reasoningSummaries,
     images,
     tmpDir: llmTmpDir,
   };
@@ -477,7 +476,7 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
   const adapterFlags = _buildSpawnAgentFlags(runtime, {
     model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel,
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    stream, disableBuiltinMcps, reasoningSummaries,
   });
   const args = [spawnScript, promptPath, sysPath, ...adapterFlags];
 
@@ -690,13 +689,12 @@ function _resolveModelForRuntime(runtime, callOpts) {
 }
 
 function _resolveRuntimeFeatureOpts({
-  stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries, engineConfig,
+  stream, disableBuiltinMcps, reasoningSummaries, engineConfig,
 } = {}) {
   const engine = engineConfig || {};
   return {
     stream: stream ?? engine.copilotStreamMode,
     disableBuiltinMcps: disableBuiltinMcps ?? engine.copilotDisableBuiltinMcps,
-    suppressAgentsMd: suppressAgentsMd ?? engine.copilotSuppressAgentsMd,
     reasoningSummaries: reasoningSummaries ?? engine.copilotReasoningSummaries,
   };
 }
@@ -759,7 +757,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     engineConfig,
     // Cross-runtime + Copilot opts:
     maxBudget, bare, fallbackModel,
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    stream, disableBuiltinMcps, reasoningSummaries,
     // P-7b2e4d01 — optional image attachments: [{ mimeType, dataBase64, filename? }]
     images,
   } = opts;
@@ -772,7 +770,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
   const imageGate = _resolveImageOpts(images, runtime && runtime.capabilities);
   if (imageGate.error) return _resolvedCallResult(_imageUnsupportedResult(runtime, imageGate.error));
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries, engineConfig,
+    stream, disableBuiltinMcps, reasoningSummaries, engineConfig,
   });
 
   let _abort = null;
@@ -884,7 +882,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     effort = null, direct = false,
     model: modelOverride, cli: cliOverride, engineConfig,
     maxBudget, bare, fallbackModel,
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    stream, disableBuiltinMcps, reasoningSummaries,
     // P-7b2e4d01 — optional image attachments: [{ mimeType, dataBase64, filename? }]
     images,
   } = opts;
@@ -897,7 +895,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
   const imageGate = _resolveImageOpts(images, runtime && runtime.capabilities);
   if (imageGate.error) return _resolvedCallResult(_imageUnsupportedResult(runtime, imageGate.error));
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({
-    stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries, engineConfig,
+    stream, disableBuiltinMcps, reasoningSummaries, engineConfig,
   });
 
   let _abort = null;

package/engine/managed-spawn.js

@@ -969,12 +969,7 @@ function removeManagedSpec(name) {
 function listManagedSpecs(opts) {
   opts = opts || {};
   const statePath = _getStatePath();
-  let raw;
-  try { raw = fs.readFileSync(statePath, 'utf8'); }
-  catch (_e) { return []; }
-  let parsed;
-  try { parsed = JSON.parse(raw); }
-  catch (_e) { return []; }
+  const parsed = shared.safeJsonObj(statePath);
   const specs = (parsed && Array.isArray(parsed.specs)) ? parsed.specs : [];
   if (opts.project) return specs.filter(s => s && s.owner_project === opts.project);
   return specs.slice();