@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{dispatch.js → orchestration/dispatch.js}

@@ -1,5 +1,5 @@
 /**
- * engine/dispatch.js — Dispatch queue management: add, complete, mutate, alerts.
+ * engine/orchestration/dispatch.js — Dispatch queue management: add, complete, mutate, alerts.
  * Extracted from engine.js for modularity. No logic changes.
  *
  * ## Dispatch meta schema — optional fields (M006)
@@ -13,14 +13,14 @@
  *                                   completing agent concluded before handing off.
  *
  * These fields are optional and additive. Dispatches without them are unaffected.
- * When present, engine/playbook.js injects a "Handoff Context" section into the
+ * When present, engine/agents/playbook.js injects a "Handoff Context" section into the
  * rendered prompt so the receiving agent has explicit orientation.
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
 const { setCooldown, setCooldownFailure } = require('./cooldown');
 const dispatchEvents = require('./dispatch-events');
 
@@ -32,6 +32,11 @@ const { getConfig, INBOX_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 
+// W-ms9tcs3o01y03383 — closed vocabulary for the `completionPath` observability
+// field written by completeDispatch. Sourced from the shared constant so the
+// engine, timeout watchdog, and any future finalizer cannot invent new values.
+const COMPLETION_PATH_VALUES = new Set(Object.values(shared.DISPATCH_COMPLETION_PATH || {}));
+
 // Dispatch types that do not push code to a PR branch. These remain dispatchable
 // against context-only PRs because casting a review vote, posting a
 // comment, asking a question, or running a read-only explore never mutates the
@@ -110,7 +115,7 @@ function _sidecarChangedPrompts(dispatch, prevSnap) {
 // they round-trip automatically. SQLite failures propagate; the CLI
 // shim in bin/minions.js guarantees node:sqlite is loadable.
 function mutateDispatch(mutator) {
-  const store = require('./dispatch-store');
+  const store = require('../persistence/dispatch-store');
   const { wrote, result } = store.applyDispatchMutation((dispatch) => {
     dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
     dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
@@ -124,8 +129,9 @@ function mutateDispatch(mutator) {
     return next;
   });
   if (wrote) {
-    try { require('./queries').invalidateDispatchCache(); } catch {}
-    try { require('./db-events').emitStateEvent('dispatch'); } catch { /* optional */ }
+    try { require('../core/queries').invalidateDispatchCache(); } catch {}
+    try { require('../core/queries').invalidateWorkItemsCache(); } catch {}
+    try { require('../persistence/db-events').emitStateEvent('dispatch'); } catch { /* optional */ }
   }
   return result;
 }
@@ -445,7 +451,7 @@ function _isPrdSourcedAndVetted(wi) {
   const sourcePlan = wi && wi.sourcePlan;
   if (!sourcePlan || typeof sourcePlan !== 'string') return false;
   try {
-    const plan = require('./prd-store').readPrd(sourcePlan);
+    const plan = require('../planning/prd-store').readPrd(sourcePlan);
     if (!plan || !plan.missing_features) return false;
     const status = plan.status || shared.PLAN_STATUS.ACTIVE;
     return status === shared.PLAN_STATUS.APPROVED || status === shared.PLAN_STATUS.ACTIVE;
@@ -697,13 +703,13 @@ async function _fetchChangedFilesForPrunedEntry(entry, project) {
   const host = String(project.repoHost || '').toLowerCase();
   try {
     if (host === 'github') {
-      const github = require('./github');
+      const github = require('../providers/github');
       const slug = github.getRepoSlug(project);
       if (!slug) return null;
       return await github.getPrChangedFiles(slug, prNumber);
     }
     if (host === 'ado' || !host) {
-      const ado = require('./ado');
+      const ado = require('../ado');
       return await ado.getPrChangedFiles(project, prNumber);
     }
   } catch (e) {
@@ -847,7 +853,9 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE, // W-mr98op8w000ma4ad — live-checkout STALE-BASE GUARD refused to fork a new branch off a local mainRef that has diverged from origin/<mainRef> with unpushed commits; contaminated local base does not change on retry (operator must reconcile the local base branch — the engine never resets it — then re-dispatch)
       FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE, // W-mr3lunnq000o9f41 — live-checkout refused to fork a new branch because the operator HEAD is on an unrelated branch (not the project base) and no local base ref was usable; forking off it would bake that branch's commits into the new PR (scope contamination). Deterministic — mechanical retry reproduces it (operator must `git checkout <mainRef>`, then re-dispatch)
       FAILURE_CLASS.OUTPUT_TRUNCATED, // P-8e4c2a17 — agent stdout exceeded the hard capture cap before the terminal result event; mechanical retry just reproduces the overflow (agent must reduce output volume or the task must be split)
-      FAILURE_CLASS.PRE_DISPATCH_EVAL_STUCK, // W-mrcrh5hj0017d22f — pre-dispatch-eval rejected the SAME unchanged description ENGINE_DEFAULTS.preDispatchEvalMaxRejections times in a row; non-retryable until the description changes (engine/shared.js:4986)
+      FAILURE_CLASS.PRE_DISPATCH_EVAL_STUCK, // W-mrcrh5hj0017d22f — pre-dispatch-eval rejected the SAME unchanged description ENGINE_DEFAULTS.preDispatchEvalMaxRejections times in a row; non-retryable until the description changes (engine/core/shared.js:4986)
+      FAILURE_CLASS.INVALID_EXECUTION_SURFACE, // W-ms5tb6ha016fda10 — the WI declared a meta.executionSurface that failed fail-closed validation (unknown value, `control-plane` on a repo-reading/mutating type, or `cloud` on a type whose deliverable is not a PR); re-running with the same declaration reproduces it (operator must fix or remove the field)
+      FAILURE_CLASS.CLOUD_PROVIDER_UNAVAILABLE, // Cloud dispatch surface — the WI validly declared `cloud` but no registered+configured provider resolved (or provider resolution threw). Structural: the same dispatch reproduces it identically until an operator configures a provider or drops the surface declaration. Deliberately NOT retryable so a misconfiguration cannot silently burn the item's retry budget — and note the engine never downgrades the refusal to a local dispatch.
     ]);
     if (neverRetry.has(failureClass)) return false;
   }
@@ -979,6 +987,7 @@ function markCompletedSourceWorkItem(item) {
     delete wi.failReason;
     delete wi.failedAt;
     delete wi._retryCount;
+    delete wi._infrastructureRetryCount;
     if (!wi.completedAt) wi.completedAt = ts();
     if (item.agent && !wi.dispatched_to) wi.dispatched_to = item.agent;
     terminal = true;
@@ -1021,6 +1030,47 @@ function deferDispatchForWorktreeProtection(id, protection = {}, terminal = {})
   return deferred;
 }
 
+// W-mrzqfozm00035365 — Return an active (or pending) dispatch to a RECOVERABLE
+// pending gate without recording a failure or consuming a retry. Used when a
+// dependency-branch merge conflict is detected in engine.js#spawnAgent BEFORE
+// the agent starts: the downstream work item is not at fault, so it must not
+// burn its retry budget or go terminal-`failed` while its deterministic
+// conflict-repair WI is worked. This ONLY tears down the dispatch record
+// cleanly (drop prompt sidecar, clear the completed dedupe key so the item can
+// re-dispatch once the gate clears); the caller stamps the work item's
+// status/_pendingReason/_dependencyConflict marker.
+function deferDispatchToPending(id, reason = '') {
+  let item = null;
+  mutateDispatch((dispatch) => {
+    let idx = (dispatch.active || []).findIndex(d => d.id === id);
+    if (idx >= 0) {
+      item = dispatch.active.splice(idx, 1)[0];
+    } else {
+      idx = (dispatch.pending || []).findIndex(d => d.id === id);
+      if (idx >= 0) item = dispatch.pending.splice(idx, 1)[0];
+    }
+    if (!item) return dispatch;
+    try { deleteDispatchPromptSidecar(item); } catch { /* best-effort */ }
+    delete item.prompt;
+    delete item._promptFile;
+    delete item._promptBytes;
+    delete item._worktreeProtectionDeferred;
+    // Clear the dedupe key so the item is free to re-dispatch on a later tick
+    // once the conflict-repair WI clears the gate. No `completed` record is
+    // pushed — this is not a completion, it is a deferral.
+    if (item.meta?.dispatchKey) {
+      dispatch.completed = Array.isArray(dispatch.completed)
+        ? dispatch.completed.filter(d => d.meta?.dispatchKey !== item.meta.dispatchKey)
+        : [];
+    }
+    return dispatch;
+  });
+  if (item) {
+    log('info', `Deferred dispatch ${id} back to pending (recoverable gate)${reason ? ': ' + reason : ''}`);
+  }
+  return !!item;
+}
+
 function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', resultSummary = '', opts = {}) {
   const {
     processWorkItemFailure = true,
@@ -1028,6 +1078,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     countAgentRetryFailure = true,
     failureClass,
   } = opts;
+  const infrastructureRetry = opts.retryBudget === 'infrastructure';
   const agentRetryable = normalizeRetryableDecision(opts.agentRetryable ?? opts.retryable);
   let item = null;
   let completedSourceWorkItem = false;
@@ -1057,6 +1108,14 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     if (reason) item.reason = reason;
     if (resultSummary) item.resultSummary = resultSummary;
     if (failureClass && result === DISPATCH_RESULT.ERROR) item.failureClass = failureClass;
+    // W-ms9tcs3o01y03383 — record HOW the dispatch reached its terminal state so
+    // a normal close, an immediate report recovery, and a genuinely stalled live
+    // resume stay distinguishable on the completed record. Values come from
+    // shared.DISPATCH_COMPLETION_PATH; unknown strings are ignored rather than
+    // persisted so the field stays a closed vocabulary.
+    if (opts.completionPath && COMPLETION_PATH_VALUES.has(opts.completionPath)) {
+      item.completionPath = opts.completionPath;
+    }
     item.meta = item.meta && typeof item.meta === 'object' ? item.meta : {};
     if (opts.completionReportPath && !item.meta.completionReportPath) {
       item.meta.completionReportPath = opts.completionReportPath;
@@ -1195,14 +1254,17 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
         }
       } else {
         let retries = (item.meta.item._retryCount || 0);
+        if (infrastructureRetry) retries = item.meta.item._infrastructureRetryCount || 0;
         try {
           const wi = liveWi || readLiveWorkItem(item.meta);
           if (wi) retries = wi._retryCount || 0;
+          if (wi && infrastructureRetry) retries = wi._infrastructureRetryCount || 0;
         } catch (e) { log('warn', 'read retry count: ' + e.message); }
         const maxRetries = ENGINE_DEFAULTS.maxRetries;
         const withinSafetyCap = retries < maxRetries;
         if (retryableFailure && withinSafetyCap) {
-          log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/${maxRetries}${failureClass ? ' [' + failureClass + ']' : ''}`);
+          const retryLabel = infrastructureRetry ? 'infrastructure recovery' : 'auto-retry';
+          log('info', `Dispatch error for ${item.meta.item.id} — ${retryLabel} ${retries + 1}/${maxRetries}${failureClass ? ' [' + failureClass + ']' : ''}`);
           lifecycle().updateWorkItemStatus(item.meta, WI_STATUS.PENDING, '');
           // Remove this dispatch key from completed so dedupe doesn't block immediate redispatch.
           if (item.meta?.dispatchKey) {
@@ -1220,7 +1282,8 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
               mutateWorkItems(wiScope, items => {
                 const wi = items.find(i => i.id === item.meta.item.id);
                 if (wi && wi.status !== WI_STATUS.PAUSED && wi.status !== WI_STATUS.DONE && !wi.completedAt) {
-                  wi._retryCount = retries + 1;
+                  if (infrastructureRetry) wi._infrastructureRetryCount = retries + 1;
+                  else wi._retryCount = retries + 1;
                   wi.status = WI_STATUS.PENDING;
                   wi._lastRetryReason = reason || '';
                   wi._lastRetryAt = ts();
@@ -1229,13 +1292,19 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
                   // when the previous attempt was bounced for MODEL_UNAVAILABLE
                   // (overloaded_error / 503). Empty string clears any stale
                   // value from an earlier failure cycle.
-                  wi._lastFailureClass = failureClass || '';
+                  if (infrastructureRetry) {
+                    wi._lastInfrastructureFailureClass = failureClass || '';
+                  } else {
+                    wi._lastFailureClass = failureClass || '';
+                  }
                   // W-mpmwxn1j — Bump per-agent retry count so the next dispatch
                   // can reassign to a different eligible agent once the same
                   // agent hits the threshold. Skip when no agent is resolvable
                   // (anonymous failures shouldn't corrupt the map shape).
                   const failedAgent = item.agent || wi.dispatched_to;
-                  if (failedAgent && countAgentRetryFailure) shared.bumpAgentRetryCount(wi, failedAgent);
+                  if (!infrastructureRetry && failedAgent && countAgentRetryFailure) {
+                    shared.bumpAgentRetryCount(wi, failedAgent);
+                  }
                   delete wi.failReason;
                   delete wi.failedAt;
                   delete wi.dispatched_at;
@@ -1260,6 +1329,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.DEPENDENCY_MERGE_SETUP]: 'dependency merge setup failed',
             [FAILURE_CLASS.MAX_TURNS]: 'reached max turn limit',
             [FAILURE_CLASS.TIMEOUT]: 'timed out waiting for agent',
+            [FAILURE_CLASS.ENGINE_RESTART]: 'engine restart lost dispatch process ownership',
             [FAILURE_CLASS.SPAWN_ERROR]: 'agent process failed to start',
             [FAILURE_CLASS.NETWORK_ERROR]: 'network or API error',
             [FAILURE_CLASS.OUT_OF_CONTEXT]: 'context window exhausted',
@@ -1283,7 +1353,9 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
           const classSuffix = failureClass ? ` [${failureClass.toUpperCase().replace(/-/g, '_')}]` : '';
           const finalReason = !retryableFailure
             ? `Non-retryable failure: ${effectiveReason}${classSuffix}`
-            : (reason || `Failed after ${maxRetries} retries${classSuffix}`);
+            : (infrastructureRetry
+              ? `Failed after ${maxRetries} infrastructure recovery attempts: ${effectiveReason}${classSuffix}`
+              : (reason || `Failed after ${maxRetries} retries${classSuffix}`));
           lifecycle().updateWorkItemStatus(item.meta, WI_STATUS.FAILED, finalReason);
           // Surface blocked dependents in logs without creating failure inbox noise.
           try {
@@ -1471,6 +1543,42 @@ function cancelPendingDispatchesForPr(prId) {
   return cancelled;
 }
 
+/**
+ * Stop runtime processes owned by active dispatch entries. Pooled entries are
+ * cancelled by the engine's tracked-process reconciliation on the next tick;
+ * their PID belongs to a shared worker and must never be killed here.
+ */
+function stopDispatchProcesses(entries) {
+  const processesToKill = [];
+  for (const entry of entries || []) {
+    if (!entry || entry.pooled) continue;
+    const pidPath = shared.findDispatchPidFile(entry);
+    if (!pidPath) continue;
+    try {
+      processesToKill.push({
+        pid: shared.validatePid(fs.readFileSync(pidPath, 'utf8').trim()),
+        observedAt: fs.statSync(pidPath).mtimeMs,
+      });
+    } catch { /* PID file may not exist */ }
+  }
+
+  const processSnapshot = processesToKill.length > 0 ? shared.listAllProcesses() : [];
+  let stopped = 0;
+  for (const processToKill of processesToKill) {
+    try {
+      const safePid = shared.validatePid(processToKill.pid);
+      if (!shared.terminateProcess('engine.dispatch.cancel', { pid: safePid }, {
+        graceMs: 5000,
+        recordedAtMs: processToKill.observedAt,
+        processes: processSnapshot,
+        skewMs: 2000,
+      })) continue;
+      stopped++;
+    } catch { /* may already be dead */ }
+  }
+  return stopped;
+}
+
 /**
  * Remove dispatch entries matching a predicate from pending/active/completed.
  * For matched active entries, kills the agent process and deletes its
@@ -1483,7 +1591,7 @@ function cancelPendingDispatchesForPr(prId) {
 function cleanDispatchEntries(matchFn) {
   const tmpDir = path.join(MINIONS_DIR, 'engine', 'tmp');
   let removed = 0;
-  const pidsToKill = [];
+  const activeEntriesToStop = [];
   const filesToDelete = [];
   const dispatchDirsToRemove = [];
   try {
@@ -1499,13 +1607,7 @@ function cleanDispatchEntries(matchFn) {
             // back to legacy flat layout for active dispatches that pre-date
             // the per-dispatch-dir layout. shared.findDispatchPidFile honors
             // the same resolution order so we agree on which PID to kill.
-            const pidPath = shared.findDispatchPidFile(d);
-            if (pidPath) {
-              try {
-                const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim());
-                if (pid) pidsToKill.push(pid);
-              } catch { /* PID file may not exist */ }
-            }
+            activeEntriesToStop.push(d);
             if (d.tmpDir && shared.validateDispatchTmpDir(d.tmpDir)) {
               dispatchDirsToRemove.push(d.tmpDir);
             } else {
@@ -1523,18 +1625,7 @@ function cleanDispatchEntries(matchFn) {
       return dispatch;
     });
   } catch { return 0; }
-  // Kill processes outside the lock — taskkill on Windows can take hundreds of ms
-  for (const pid of pidsToKill) {
-    try {
-      const safePid = shared.validatePid(pid);
-      if (process.platform === 'win32') {
-        const { execFileSync } = require('child_process');
-        execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
-      } else {
-        shared.killGracefully({ pid: safePid }, 5000);
-      }
-    } catch { /* may already be dead */ }
-  }
+  stopDispatchProcesses(activeEntriesToStop);
   for (const fp of filesToDelete) {
     try { fs.unlinkSync(fp); } catch { /* may not exist */ }
   }
@@ -1573,6 +1664,7 @@ module.exports = {
   getPrDispatchDedupeKey,
   isRetryableFailureReason,
   deferDispatchForWorktreeProtection,
+  deferDispatchToPending,
   completeDispatch,
   writeInboxAlert,
   updateAgentStatus,
@@ -1580,6 +1672,7 @@ module.exports = {
   pruneStalePrDispatches,
   pruneStalePrDispatchesAsync, // W-mr9jo2n2000667ad — scope-overlap-verified variant; engine.js tick should await this
   cancelPendingDispatchesForPr,
+  stopDispatchProcesses,
   cleanDispatchEntries,
   cancelPendingWorkItems,
   // exported for testing

package/engine/orchestration/failed-scheduled-cleanup.js

@@ -0,0 +1,274 @@
+// engine/orchestration/failed-scheduled-cleanup.js — W-msckn1lp002xdf6b
+//
+// Conservative, low-frequency (daily) retention for FAILED scheduled work
+// items so machine-generated scheduled-run failures (hourly review/fetch
+// sweeps, etc.) do not accumulate indefinitely in the work-item store.
+//
+// Contract (see docs/auto-discovery.md → "Scheduled-failure retention"):
+//   - Targets ONLY provably machine-generated scheduled runs, identified by
+//     structured provenance (`createdBy === 'scheduler'` + `_scheduleId`) or the
+//     canonical legacy `sched-<scheduleId>-<ts>` id prefix. Never by title/prose.
+//   - Groups failures by their originating schedule. The NEWEST failed
+//     occurrence per schedule is retained long enough to diagnose the current
+//     failure; older SUPERSEDED failures are pruned once they age past the
+//     diagnostic window (24h). A later successful run lets the newest failure be
+//     pruned too, once that window has elapsed. An absolute threshold prunes
+//     stale failures regardless.
+//   - Non-scheduled / human-authored failed items are NEVER touched.
+//   - Fails open: ambiguous provenance, lineage links, or an active dispatch
+//     reference cause the item to be skipped, not deleted.
+//
+// The policy is intentionally a documented shared default rather than an
+// `engine.*` knob — there is nothing an operator needs to tune, and adding a
+// config flag would require Settings UI + CLAUDE.md parity for no benefit.
+
+const shared = require('../core/shared');
+const { WI_STATUS, DONE_STATUSES, log } = shared;
+
+// Retain the newest failure and any failure younger than this so the current
+// failure stays diagnosable; superseded failures older than this are pruned.
+const DIAGNOSTIC_RETENTION_MS = 24 * 60 * 60 * 1000; // 24h
+// Absolute stale threshold — even the newest failure is pruned past this so a
+// long-abandoned schedule does not pin a failure forever.
+const ABSOLUTE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000; // 7d
+// Low-frequency cadence: the sweep itself runs at most once per this window,
+// even though runCleanup fires every ~10 minutes.
+const PRUNE_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily
+// Persisted last-run marker key in the engine small-state store.
+const LAST_RUN_KEY = 'lastFailedScheduledPruneAt';
+
+// ─── Provenance ─────────────────────────────────────────────────────────────
+
+// True iff the item is a provably machine-generated scheduled run. Structured
+// provenance wins; the `sched-` id prefix is the documented legacy fallback for
+// items created before `createdBy`/`_scheduleId` were consistently stamped.
+function isScheduledProvenance(item) {
+  if (!item || typeof item !== 'object') return false;
+  if (item.createdBy === 'scheduler' && item._scheduleId) return true;
+  if (typeof item.id === 'string' && /^sched-.+-\d+$/.test(item.id)) return true;
+  return false;
+}
+
+// The originating schedule id for grouping. Prefers structured `_scheduleId`;
+// falls back to parsing the canonical `sched-<scheduleId>-<timestamp>` id.
+function scheduleKey(item) {
+  if (item && item._scheduleId) return String(item._scheduleId);
+  const m = /^sched-(.+)-\d+$/.exec(String(item && item.id || ''));
+  return m ? m[1] : null;
+}
+
+// An item wired into a plan/PRD/decomposition/followup lineage must not be
+// pruned here — its lifecycle is owned elsewhere. Scheduled sweep items carry
+// none of these, so a scheduled-provenance item that DOES is treated as
+// ambiguous and skipped (fail-safe).
+function hasLineage(item) {
+  return !!(item && (item.parent_id || item.parentId || item._prdItemId || item.prdItemId));
+}
+
+function _parseMs(v) {
+  if (v == null) return NaN;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : NaN;
+  const ms = Date.parse(v);
+  return Number.isFinite(ms) ? ms : NaN;
+}
+
+// Best-effort failure timestamp — `failedAt` is stamped when a WI fails.
+function failureTimestampMs(item) {
+  for (const cand of [item.failedAt, item.updatedAt, item.completedAt, item.dispatched_at, item.created]) {
+    const ms = _parseMs(cand);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return 0;
+}
+
+// Best-effort success timestamp — `completedAt` is stamped when a WI completes.
+function successTimestampMs(item) {
+  for (const cand of [item.completedAt, item.completed_at, item.updatedAt, item.dispatched_at, item.created]) {
+    const ms = _parseMs(cand);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return 0;
+}
+
+// ─── Pure retention planner (unit-tested directly) ──────────────────────────
+
+/**
+ * Decide which failed scheduled work items to prune.
+ *
+ * @param {Array<object>} items  Flat list of work items across all scopes. Each
+ *   item may carry a `_scope` hint (defaults to 'central').
+ * @param {number} now           Epoch ms "now".
+ * @param {object} [opts]
+ * @param {Set<string>} [opts.protectedIds]  WI ids referenced by a live
+ *   dispatch — never pruned.
+ * @param {number} [opts.diagnosticRetentionMs]
+ * @param {number} [opts.absoluteRetentionMs]
+ * @returns {{ toPrune: Array<{id,scope,scheduleKey}>, groupCount: number }}
+ */
+function planFailedScheduledPrune(items, now = Date.now(), opts = {}) {
+  const diagnosticMs = Number.isFinite(opts.diagnosticRetentionMs) ? opts.diagnosticRetentionMs : DIAGNOSTIC_RETENTION_MS;
+  const absoluteMs = Number.isFinite(opts.absoluteRetentionMs) ? opts.absoluteRetentionMs : ABSOLUTE_RETENTION_MS;
+  const protectedIds = opts.protectedIds instanceof Set ? opts.protectedIds : new Set();
+
+  const groups = new Map(); // scheduleKey -> { failures: [], latestSuccessMs }
+  for (const item of Array.isArray(items) ? items : []) {
+    if (!isScheduledProvenance(item)) continue;
+    const key = scheduleKey(item);
+    if (!key) continue;
+    let g = groups.get(key);
+    if (!g) { g = { failures: [], latestSuccessMs: 0 }; groups.set(key, g); }
+    if (item.status === WI_STATUS.FAILED) {
+      g.failures.push(item);
+    } else if (DONE_STATUSES.has(item.status)) {
+      const ms = successTimestampMs(item);
+      if (ms > g.latestSuccessMs) g.latestSuccessMs = ms;
+    }
+  }
+
+  const toPrune = [];
+  for (const [key, g] of groups) {
+    if (g.failures.length === 0) continue;
+    // Newest failure first so index 0 is the diagnostic keeper.
+    const failures = g.failures.slice().sort((a, b) => failureTimestampMs(b) - failureTimestampMs(a));
+    for (let i = 0; i < failures.length; i++) {
+      const f = failures[i];
+      if (protectedIds.has(String(f.id))) continue; // live dispatch reference
+      if (hasLineage(f)) continue;                    // plan/PRD/followup lineage
+      const age = now - failureTimestampMs(f);
+      const isNewest = i === 0;
+      let prune = false;
+      if (isNewest) {
+        // Keep the current failure to diagnose it — unless a later success has
+        // superseded it (and the diagnostic window elapsed), or it is stale
+        // past the absolute threshold.
+        const supersededBySuccess = g.latestSuccessMs > failureTimestampMs(f);
+        if (age > absoluteMs) prune = true;
+        else if (supersededBySuccess && age > diagnosticMs) prune = true;
+      } else {
+        // Superseded by a newer failure — prune once past the diagnostic window.
+        if (age > diagnosticMs) prune = true;
+      }
+      if (prune) toPrune.push({ id: String(f.id), scope: f._scope || 'central', scheduleKey: key });
+    }
+  }
+  return { toPrune, groupCount: groups.size };
+}
+
+// ─── Orchestration entrypoint (wired into runCleanup) ───────────────────────
+
+// Collect WI ids referenced by a live (pending/active/review) dispatch so we
+// never delete a work item something is actively working. Fails open.
+function _collectProtectedWiIds() {
+  const ids = new Set();
+  try {
+    const dispatch = require('../core/queries').getDispatch();
+    for (const seg of [dispatch.pending, dispatch.active, dispatch.review]) {
+      for (const e of Array.isArray(seg) ? seg : []) {
+        const wi = e && e.meta && e.meta.item && e.meta.item.id;
+        if (wi) ids.add(String(wi));
+      }
+    }
+  } catch { /* fail open — no protections known */ }
+  return ids;
+}
+
+/**
+ * Daily sweep that prunes superseded failed scheduled work items. Safe to call
+ * every cleanup tick — the cadence gate (persisted last-run marker) skips work
+ * until PRUNE_INTERVAL_MS has elapsed. Concurrency-safe (the gate is claimed
+ * inside a single small-state transaction) and idempotent (the deletion mutator
+ * re-validates provenance/status against fresh SQL rows).
+ *
+ * @returns {{ skipped:boolean, reason?:string, pruned:number, bySchedule?:object }}
+ */
+function pruneSupersededFailedScheduledItems(config, opts = {}) {
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const force = opts.force === true;
+  const intervalMs = Number.isFinite(opts.intervalMs) ? opts.intervalMs : PRUNE_INTERVAL_MS;
+
+  // Cadence gate — claim the run atomically so overlapping ticks / a restart
+  // race cannot double-run the sweep in the same day.
+  if (!force) {
+    let claimed = false;
+    try {
+      shared.mutateEngineState((state) => {
+        const last = Number(state[LAST_RUN_KEY]) || 0;
+        if (last && (now - last) < intervalMs) return state; // not due yet
+        state[LAST_RUN_KEY] = now;
+        claimed = true;
+        return state;
+      });
+    } catch (e) {
+      log('warn', `failed-scheduled prune: cadence claim failed — ${e.message}`);
+      return { skipped: true, reason: 'cadence-claim-error', pruned: 0 };
+    }
+    if (!claimed) return { skipped: true, reason: 'cadence', pruned: 0 };
+  }
+
+  // Gather scheduled items across every scope (central + each project).
+  const scopes = ['central', ...shared.getProjects(config || {})];
+  const allItems = [];
+  for (const scope of scopes) {
+    let items;
+    try { items = shared.readWorkItems(scope); } catch { continue; }
+    for (const it of Array.isArray(items) ? items : []) {
+      if (it && typeof it === 'object') { it._scope = scope; allItems.push(it); }
+    }
+  }
+
+  const protectedIds = _collectProtectedWiIds();
+  const { toPrune } = planFailedScheduledPrune(allItems, now, { protectedIds });
+  if (toPrune.length === 0) return { skipped: false, pruned: 0, bySchedule: {} };
+
+  const idsByScope = new Map();
+  for (const p of toPrune) {
+    if (!idsByScope.has(p.scope)) idsByScope.set(p.scope, new Set());
+    idsByScope.get(p.scope).add(p.id);
+  }
+
+  let pruned = 0;
+  const bySchedule = {};
+  const idToSchedule = new Map(toPrune.map(p => [p.id, p.scheduleKey]));
+  for (const [scope, ids] of idsByScope) {
+    try {
+      shared.mutateWorkItems(scope, (items) => {
+        if (!Array.isArray(items)) return items;
+        return items.filter((w) => {
+          if (!w || !ids.has(String(w.id))) return true;
+          // Re-validate against the fresh row — status/provenance may have
+          // changed since planning (idempotency + race safety).
+          if (w.status !== WI_STATUS.FAILED) return true;
+          if (!isScheduledProvenance(w)) return true;
+          if (hasLineage(w)) return true;
+          const key = idToSchedule.get(String(w.id)) || scheduleKey(w) || 'unknown';
+          bySchedule[key] = (bySchedule[key] || 0) + 1;
+          pruned++;
+          return false; // delete
+        });
+      });
+    } catch (e) {
+      log('warn', `failed-scheduled prune (scope=${scope}): ${e.message}`);
+    }
+  }
+
+  if (pruned > 0) {
+    const summary = Object.entries(bySchedule).map(([k, n]) => `${k}:${n}`).join(', ');
+    log('info', `cleanup: pruned ${pruned} superseded failed scheduled work item(s) across ${Object.keys(bySchedule).length} schedule(s) — ${summary}`);
+  }
+  return { skipped: false, pruned, bySchedule };
+}
+
+module.exports = {
+  pruneSupersededFailedScheduledItems,
+  planFailedScheduledPrune,
+  // Exported for unit tests / reuse:
+  isScheduledProvenance,
+  scheduleKey,
+  hasLineage,
+  failureTimestampMs,
+  successTimestampMs,
+  DIAGNOSTIC_RETENTION_MS,
+  ABSOLUTE_RETENTION_MS,
+  PRUNE_INTERVAL_MS,
+  LAST_RUN_KEY,
+};