@yemi33/minions 0.1.2121 → 0.1.2123

package/engine/lifecycle.js

@@ -14,6 +14,7 @@ const { trackEngineUsage } = require('./llm');
 const { resolveRuntime } = require('./runtimes');
 const adoGitAuth = require('./ado-git-auth');
 const queries = require('./queries');
+const harness = require('./harness');
 const { isBranchActive } = require('./cooldown');
 const { worktreeMatchesBranch, getWorktreeBranch, cleanupMergedPrLocalBranch } = require('./cleanup');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
@@ -4040,6 +4041,82 @@ function handleDecompositionResult(stdout, meta, config, runtimeName) {
   return 0;
 }
 
+/**
+ * Tri-agent harness mode (W-mq07a9gf000jbc2b): when an evaluator completes,
+ * parse its verdict against the configured rubric/threshold and — if the
+ * artifact didn't pass and the iteration cap hasn't been hit — append a
+ * fresh Generator+Evaluator pair so the harness can iterate on its own
+ * artifact. Returns the number of work items appended (0 = terminal stop,
+ * either pass or cap reached).
+ *
+ * Called from runPostCompletionHooks after a successful run when the
+ * dispatched item carries _harness.role === 'evaluator'.
+ */
+function handleHarnessIterationResult(stdout, structuredCompletion, meta, config) {
+  const evaluatorItem = meta?.item;
+  if (!evaluatorItem?._harness || evaluatorItem._harness.role !== harness.HARNESS_ROLE.EVALUATOR) return 0;
+
+  let verdict;
+  try {
+    verdict = harness.parseEvaluatorVerdict(stdout || '', structuredCompletion || null);
+  } catch (err) {
+    log('warn', `Harness ${evaluatorItem._harness.missionId}: verdict parse failed — ${err.message}; treating as terminal stop`);
+    return 0;
+  }
+
+  if (!harness.shouldIterateAgain(evaluatorItem._harness, verdict)) {
+    const reason = verdict.pass === true ? 'passed' :
+      (evaluatorItem._harness.iteration >= evaluatorItem._harness.maxIterations ? 'max iterations reached' :
+      'inconclusive verdict');
+    log('info', `Harness mission ${evaluatorItem._harness.missionId} terminal stop (iteration ${evaluatorItem._harness.iteration}, ${reason}, score=${verdict.score ?? 'n/a'})`);
+    return 0;
+  }
+
+  let nextItems;
+  try {
+    nextItems = harness.createIterationWorkItems(evaluatorItem, verdict, {});
+  } catch (err) {
+    log('warn', `Harness ${evaluatorItem._harness.missionId}: iteration build failed — ${err.message}`);
+    return 0;
+  }
+  if (!Array.isArray(nextItems) || nextItems.length === 0) return 0;
+
+  // Mirror handleDecompositionResult: scan central + per-project work-items.json
+  // and append into the file that owns the evaluator (the trio always lands in
+  // the central file in practice — scheduler.discoverScheduledWork writes
+  // directly to engine/work-items.json via engine.js — but iterate defensively).
+  const projects = shared.getProjects(config);
+  const allPaths = [path.join(MINIONS_DIR, 'work-items.json')];
+  for (const p of projects) allPaths.push(shared.projectWorkItemsPath(p));
+
+  let appendedTo = null;
+  for (const wiPath of allPaths) {
+    let found = false;
+    mutateJsonFileLocked(wiPath, data => {
+      if (!Array.isArray(data)) return data;
+      const evaluator = data.find(i => i.id === evaluatorItem.id);
+      if (!evaluator) return data;
+      found = true;
+      // De-dupe by id in case a previous tick already appended the next pair.
+      const existingIds = new Set(data.map(i => i.id));
+      for (const it of nextItems) {
+        if (existingIds.has(it.id)) continue;
+        data.push(it);
+      }
+      return data;
+    }, { defaultValue: [] });
+    if (found) { appendedTo = wiPath; break; }
+  }
+
+  if (!appendedTo) {
+    log('warn', `Harness ${evaluatorItem._harness.missionId}: evaluator ${evaluatorItem.id} not found in any work-items.json — iteration skipped`);
+    return 0;
+  }
+
+  log('info', `Harness mission ${evaluatorItem._harness.missionId} iterating: appended ${nextItems.length} work items (next iteration: ${nextItems[0]._harness.iteration}, score=${verdict.score ?? 'n/a'})`);
+  return nextItems.length;
+}
+
 /**
  * W-mpg58wv3 — auto-dispatch a re-review WI when a fix-WI born from a minion
  * REQUEST_CHANGES marks done. Closure-loop for the shared Yemi reviewer slot:
@@ -4386,6 +4463,19 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
+  // Tri-agent harness iteration (W-mq07a9gf000jbc2b): if the evaluator just
+  // completed successfully and verdict says retry, append the next Gen+Eval
+  // pair into the same work-items.json. Engine will dispatch them on the
+  // next tick. No interaction with skipDoneStatus — the evaluator itself
+  // still marks DONE; iteration is a sibling write, not a parent decomp.
+  if (effectiveSuccess && meta?.item?._harness?.role === harness.HARNESS_ROLE.EVALUATOR) {
+    try {
+      handleHarnessIterationResult(stdout, structuredCompletion, meta, config);
+    } catch (err) {
+      log('warn', `Harness iteration hook failed for ${meta.item.id}: ${err.message}`);
+    }
+  }
+
   // Verify review work items include a verdict — must run BEFORE updateWorkItemStatus(DONE),
   // same pattern as plan-to-prd (#893): updateWorkItemStatus deletes _retryCount, so the check
   // must read/increment it before that happens. Also sets skipDoneStatus so completedAt isn't
@@ -5204,6 +5294,7 @@ module.exports = {
   isPrAttachmentRequired,
   extractDecompositionJson,
   handleDecompositionResult,
+  handleHarnessIterationResult,
   processCompletionFollowups,
   // W-mpg58wv3 — closure-loop dispatch helpers (exported for testing).
   dispatchReReviewForFix,

package/engine/scheduler.js

@@ -25,7 +25,8 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const routing = require('./routing');
-const { safeJson, safeWrite, mutateJsonFileLocked, mutateScheduleRuns, ts, dateStamp, WI_STATUS, WORK_TYPE } = shared;
+const harness = require('./harness');
+const { safeJson, safeWrite, mutateJsonFileLocked, mutateScheduleRuns, ts, dateStamp, log, WI_STATUS, WORK_TYPE } = shared;
 
 const SCHEDULE_RUNS_PATH = path.join(shared.MINIONS_DIR, 'engine', 'schedule-runs.json');
 
@@ -186,9 +187,9 @@ function createScheduledWorkItem(sched) {
   };
 }
 
-function writeScheduleRunEntry(runs, scheduleId, workItemId) {
+function writeScheduleRunEntry(runs, scheduleId, workItemId, extra) {
   const existing = typeof runs[scheduleId] === 'object' && runs[scheduleId] ? runs[scheduleId] : {};
-  runs[scheduleId] = { ...existing, lastRun: ts(), lastWorkItemId: workItemId };
+  runs[scheduleId] = { ...existing, lastRun: ts(), lastWorkItemId: workItemId, ...(extra || {}) };
   return runs[scheduleId];
 }
 
@@ -222,6 +223,42 @@ function discoverScheduledWork(config) {
       const lastRun = typeof runEntry === 'string' ? runEntry : (runEntry?.lastRun || null);
       if (!shouldRunNow(sched, lastRun)) continue;
 
+      // Tri-agent harness mode (W-mq07a9gf000jbc2b): a single schedule firing
+      // produces a coordinated Planner → Generator → Evaluator trio rather than
+      // a single work item. Validate config first — on bad config, skip this
+      // tick WITHOUT recording a schedule run so the operator can fix the
+      // config and the next tick will pick it up.
+      if (sched.harness_mode === harness.HARNESS_MODE.TRI_AGENT) {
+        const validation = harness.validateHarnessConfig(sched);
+        if (!validation.valid) {
+          log('warn', `Scheduler: harness config invalid for ${sched.id} — skipping (errors: ${validation.errors.join('; ')})`);
+          continue;
+        }
+        try {
+          // Resolve schedule-time template variables on the title/description
+          // BEFORE handing the schedule to the harness builder so subtask
+          // prompts inherit the same substitutions as regular schedules.
+          const resolvedSched = {
+            ...sched,
+            title: resolveScheduleTemplateVars(sched.title),
+            description: resolveScheduleTemplateVars(sched.description || sched.title),
+            harness_rubric: resolveScheduleTemplateVars(sched.harness_rubric),
+          };
+          const mission = harness.createTriAgentMission(resolvedSched);
+          for (const it of mission.items) work.push(it);
+          // Record the mission's planner id as lastWorkItemId for compatibility
+          // with the existing schedule-runs shape, plus lastMissionId so the
+          // dashboard and consolidation tooling can join across the trio.
+          writeScheduleRunEntry(runs, sched.id, mission.items[0].id, {
+            lastMissionId: mission.missionId,
+            harnessMode: harness.HARNESS_MODE.TRI_AGENT,
+          });
+        } catch (err) {
+          log('warn', `Scheduler: tri-agent mission build failed for ${sched.id}: ${err.message}`);
+        }
+        continue;
+      }
+
       // Substitute schedule-time template vars (e.g. {{date}}) before the work
       // item is written — single-pass playbook rendering can't reach placeholders
       // embedded inside task_description, so they must be resolved up front.

package/engine/shared.js

@@ -2255,6 +2255,22 @@ const ENGINE_DEFAULTS = {
   allowedDashboardOrigins: [],
   meetingRoundTimeout: 900000, // 15min per meeting round — soft signal; logs a "still waiting" warning each tick
   meetingRoundHardTimeout: 3600000, // 60min hard backstop — non-terminal participants are marked failed and the round advances. Prevents permanent stalls if an agent's dispatch never spawns or its completion gets dropped.
+  // W-mq066js7000fff1f-c (steering Gap B): max wall-clock a steering message may
+  // sit deferred (runtime hasn't emitted a resumable checkpoint yet — Copilot
+  // pre-first-checkpoint, etc.). Past this window the message is flagged
+  // stranded: `[steering-warn]` line on live-output, `_steeringStranded=true` on
+  // the active dispatch row, and the steering store (when present) marked
+  // `status='stranded'`. Default 15min; clamp 60_000..14_400_000 (1 min..4 h).
+  steeringDeferredMaxMs: 900000,
+  // W-mq066js7000fff1f-c (steering Gap C): cap on graceful+escalation kill
+  // attempts after a steering kill is issued. Ladder (between attempts): 30s →
+  // 60s → 120s, last interval reused. attempt 1 = killGracefully; attempts 2..cap
+  // = platform-specific hard kill (taskkill /F /T on Windows, descendant tree +
+  // pkill on Unix); after cap is reached and the process is still alive, the
+  // engine gives up with a `[steering-stuck]` log + non-actionable inbox notice
+  // so the agent surfaces in the dashboard for operator intervention. Default 3;
+  // clamp 1..5.
+  steeringMaxKillRetries: 3,
   evalLoop: true, // enable review→fix loop after implementation completes
   evalMaxCost: null, // USD ceiling per work item across all eval iterations; null = no limit (gather baseline data first)
   maxRetries: 3, // max dispatch retries before marking work item as failed

package/engine/timeout.js

@@ -54,8 +54,87 @@ function checkIdleThreshold(config) {
 
 // ─── Steering Checker ────────────────────────────────────────────────────────
 
-// How long to wait for a steered agent to exit before retrying the kill
-const STEERING_KILL_RETRY_MS = 30000;
+// W-mq066js7000fff1f-c (Gap C): kill-retry escalation ladder. Intervals between
+// successive kill attempts after a steering kill issues. Attempt i (1-indexed)
+// uses STEERING_KILL_INTERVALS_MS[min(i-1, len-1)]; last value repeats so cap=5
+// keeps stepping every 120s. cap=1 = one graceful retry only (then give-up).
+const STEERING_KILL_INTERVALS_MS = [30000, 60000, 120000];
+// Set of steering-store statuses still "in flight" — Gap G ignores entries that
+// have already terminated (delivered/dropped/etc).
+const STEERING_ACTIVE_STATUSES = new Set(['queued', 'live_kill', 'deferred', 're_spawning']);
+
+// W-mq066js7000fff1f-c (Gap G): lazy require for engine/steering-store.js.
+// Sibling branch -d ships the store; my branch ships independently and no-ops
+// when the module is absent. Only swallows MODULE_NOT_FOUND for the exact
+// resolution — real syntax/runtime errors propagate so a broken store fails
+// visibly instead of silently degrading.
+let _steeringStoreLoaded = false;
+let _steeringStore = null;
+function getSteeringStore() {
+  if (_steeringStoreLoaded) return _steeringStore;
+  _steeringStoreLoaded = true;
+  try {
+    _steeringStore = require('./steering-store');
+  } catch (err) {
+    const isMissing = err && err.code === 'MODULE_NOT_FOUND' && /steering-store/.test(String(err.message || ''));
+    if (!isMissing) {
+      try { log('warn', `Steering: failed to load engine/steering-store.js: ${err.message}`); } catch {}
+    }
+    _steeringStore = null;
+  }
+  return _steeringStore;
+}
+// Test-only reset.
+function _resetSteeringStoreCacheForTest() { _steeringStoreLoaded = false; _steeringStore = null; }
+// Test-only direct injection — bypasses the lazy require entirely. Pass `null`
+// to simulate the module-absent case without touching require.cache.
+function _setSteeringStoreForTest(store) {
+  _steeringStoreLoaded = true;
+  _steeringStore = store;
+}
+
+function _steeringIdForEntry(entry) {
+  if (!entry) return null;
+  if (entry.id) return String(entry.id);
+  const filePath = entry.path || entry;
+  if (typeof filePath !== 'string') return null;
+  const m = path.basename(filePath).match(/^steering-(\d+)/);
+  return m ? m[1] : null;
+}
+
+function _safeStoreCall(fn, ...args) {
+  const store = getSteeringStore();
+  if (!store || typeof store[fn] !== 'function') return null;
+  try { return store[fn](...args); }
+  catch (err) {
+    try { log('warn', `Steering store ${fn} failed: ${err.message}`); } catch {}
+    return null;
+  }
+}
+
+function _clampSteeringDeferredMaxMs(config) {
+  const raw = Number(config?.engine?.steeringDeferredMaxMs ?? ENGINE_DEFAULTS.steeringDeferredMaxMs);
+  if (!Number.isFinite(raw)) return ENGINE_DEFAULTS.steeringDeferredMaxMs;
+  return Math.max(60000, Math.min(14400000, raw));
+}
+
+function _clampSteeringMaxKillRetries(config) {
+  const raw = Number(config?.engine?.steeringMaxKillRetries ?? ENGINE_DEFAULTS.steeringMaxKillRetries);
+  if (!Number.isFinite(raw)) return ENGINE_DEFAULTS.steeringMaxKillRetries;
+  return Math.max(1, Math.min(5, Math.round(raw)));
+}
+
+function _steeringKillIntervalMs(attemptIdx) {
+  const i = Math.max(0, Math.min(STEERING_KILL_INTERVALS_MS.length - 1, attemptIdx));
+  return STEERING_KILL_INTERVALS_MS[i];
+}
+
+function _appendLiveOutputLine(agentId, line) {
+  try {
+    const liveLogPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
+    fs.appendFileSync(liveLogPath, line.endsWith('\n') ? line : `${line}\n`);
+  } catch { /* optional */ }
+}
 
 function runtimeSupportsMidRunSessionId(info) {
   if (typeof info?.midRunSessionId === 'boolean') return info.midRunSessionId;
@@ -76,6 +155,16 @@ function rememberDeferredSteering(info, steerEntry) {
   const existing = new Set(Array.isArray(info._deferredSteeringFiles) ? info._deferredSteeringFiles : []);
   if (steerEntry?.path) existing.add(steerEntry.path);
   info._deferredSteeringFiles = Array.from(existing);
+  // Stamp per-entry deferred timestamp for the Gap B stranded-sweep. Map keyed
+  // by file path so multiple deferred messages each track their own clock.
+  if (steerEntry?.path) {
+    if (!info._deferredSteeringQueuedAt || typeof info._deferredSteeringQueuedAt !== 'object') {
+      info._deferredSteeringQueuedAt = {};
+    }
+    if (!info._deferredSteeringQueuedAt[steerEntry.path]) {
+      info._deferredSteeringQueuedAt[steerEntry.path] = Date.now();
+    }
+  }
 }
 
 function deferSteeringUntilCheckpoint(id, info, steerEntry) {
@@ -97,14 +186,157 @@ function deferSteeringUntilCheckpoint(id, info, steerEntry) {
   } catch { /* optional */ }
 }
 
+// W-mq066js7000fff1f-c (Gap B): per-tick sweep over `_deferredSteeringQueuedAt`
+// entries that are still in `_deferredSteeringFiles` (source-of-truth) and have
+// no sessionId after `engine.steeringDeferredMaxMs`. Each match: append
+// `[steering-warn]` to live-output, mark `_steeringStranded: true` on the matching
+// dispatch active row, and `store.updateStatus(id, 'stranded')` (no-op if store
+// absent). `info._deferredSteeringStrandedFiles` (Set) guards against re-firing
+// the same warning every tick while the file remains stranded.
+function checkDeferredStranded(activeProcesses, config) {
+  const maxMs = _clampSteeringDeferredMaxMs(config);
+  const now = Date.now();
+  for (const [dispatchId, info] of activeProcesses) {
+    if (!info || info.sessionId) continue;
+    const queuedAt = info._deferredSteeringQueuedAt;
+    if (!queuedAt || typeof queuedAt !== 'object') continue;
+    const deferredSet = new Set(Array.isArray(info._deferredSteeringFiles) ? info._deferredSteeringFiles : []);
+    if (deferredSet.size === 0) continue;
+    if (!info._deferredSteeringStrandedFiles) info._deferredSteeringStrandedFiles = new Set();
+    const stranded = info._deferredSteeringStrandedFiles;
+    for (const filePath of deferredSet) {
+      if (stranded.has(filePath)) continue;
+      const ts = Number(queuedAt[filePath]);
+      if (!Number.isFinite(ts) || now - ts <= maxMs) continue;
+      const entryId = _steeringIdForEntry({ path: filePath });
+      const ageMin = Math.round((now - ts) / 60000);
+      _appendLiveOutputLine(info.agentId,
+        `\n[steering-warn] Steering message ${entryId || path.basename(filePath)} has been queued for ${ageMin}m without a resumable checkpoint (no sessionId emitted). It will be delivered on the next dispatch.`);
+      log('warn', `Steering: ${info.agentId} (${dispatchId}) deferred steering ${entryId || filePath} stranded after ${ageMin}m — no sessionId`);
+      stranded.add(filePath);
+      try {
+        dispatch().mutateDispatch((data) => {
+          for (const row of data.active || []) {
+            if (row && row.id === dispatchId) row._steeringStranded = true;
+          }
+          return data;
+        });
+      } catch (err) {
+        try { log('warn', `Steering: mutateDispatch _steeringStranded failed for ${dispatchId}: ${err.message}`); } catch {}
+      }
+      if (entryId) _safeStoreCall('updateStatus', entryId, 'stranded', { last_error: 'no-session-after-max-defer' });
+    }
+  }
+}
+
+// W-mq066js7000fff1f-c (Gap C): runs the kill-retry escalation ladder for an
+// already-steered process whose `_steeringAt` is set but which hasn't exited.
+// Caller is `checkSteering` per-tick loop; `info` is the `activeProcesses`
+// record. Returns true if any rung fired (caller should `continue` and not
+// scan for new steering messages for this dispatch).
+function _runSteeringKillLadder(id, info, config) {
+  if (!info._steeringAt || info._steeringGaveUp) return false;
+  const cap = _clampSteeringMaxKillRetries(config);
+  const attempts = Number(info._steeringKillAttempts) || 0;
+  // Reference time: anchor on `_steeringAt` for attempt 0 (the bookkeeping
+  // sequence), then on `_steeringLastRetryAt` for subsequent rungs.
+  const refTime = attempts === 0 ? info._steeringAt : (info._steeringLastRetryAt || info._steeringAt);
+  const wait = _steeringKillIntervalMs(attempts);
+  if (Date.now() - refTime <= wait) return false;
+
+  // attempts < cap → run kill attempt (i=0 graceful, else platform escalation).
+  if (attempts < cap) {
+    if (attempts === 0) {
+      log('warn', `Steering: ${info.agentId} (${id}) didn't exit ${Math.round(wait / 1000)}s after kill — retrying gracefully`);
+      try { shared.killGracefully(info.proc, 5000); }
+      catch (err) { try { log('warn', `Steering kill retry (graceful) failed for ${info.agentId}: ${err.message}`); } catch {} }
+    } else {
+      log('warn', `Steering: ${info.agentId} (${id}) survived attempt ${attempts} — escalating (attempt ${attempts + 1}/${cap})`);
+      _escalatePlatformKill(info);
+    }
+    info._steeringKillAttempts = attempts + 1;
+    info._steeringLastRetryAt = Date.now();
+    return true;
+  }
+
+  // attempts === cap → give up: log + non-actionable inbox notice.
+  const minutes = Math.round((Date.now() - info._steeringAt) / 60000);
+  log('error', `Steering: ${info.agentId} (${id}) did not exit after ${cap} kill attempts (${minutes}m since kill) — giving up`);
+  _appendLiveOutputLine(info.agentId,
+    `\n[steering-stuck] Process did not exit after ${cap} kill attempts over ~${minutes}m. The engine is giving up automatic escalation; operator intervention may be required.`);
+  try {
+    // System notification body is framed as non-actionable: prefix `[engine-system]`
+    // so an agent that re-consumes it from the inbox treats it as metadata. The
+    // primary signal is the live-output line above (operator-facing) and the
+    // give-up log; this inbox write is a belt-and-suspenders notification.
+    steering.writeSteeringMessage(info.agentId,
+      `[engine-system] Steering kill escalation gave up after ${cap} attempts (~${minutes}m). This is an automated notification — do not act on it; the engine has surfaced this dispatch for operator attention.`,
+      { source: 'engine' });
+  } catch (err) {
+    try { log('warn', `Steering: writeSteeringMessage for give-up failed: ${err.message}`); } catch {}
+  }
+  info._steeringGaveUp = true;
+  info._steeringKillAttempts = attempts + 1;
+  info._steeringLastRetryAt = Date.now();
+  return true;
+}
+
+function _escalatePlatformKill(info) {
+  const pid = info?.proc?.pid;
+  if (!pid) return;
+  if (process.platform === 'win32') {
+    try { shared.exec(`taskkill /F /T /PID ${pid}`, { timeout: 3000 }); }
+    catch { /* may already be dead */ }
+    return;
+  }
+  // Unix: collect descendant PIDs (deepest first), SIGKILL each, then a final
+  // `pkill -KILL -P <pid>` sweep for anything pgrep missed.
+  const descendants = _collectDescendantPids(pid);
+  for (const child of descendants) {
+    try { process.kill(child, 'SIGKILL'); } catch { /* gone */ }
+  }
+  try { shared.exec(`pkill -KILL -P ${pid}`, { timeout: 3000 }); }
+  catch { /* children may already be dead */ }
+  try { process.kill(pid, 'SIGKILL'); } catch { /* parent may already be dead */ }
+}
+
+function _collectDescendantPids(rootPid) {
+  // Returns descendant PIDs ordered deepest-first so leaves die before parents
+  // (otherwise grandchildren get re-parented to init and disappear from pgrep -P
+  // <pid>). BFS the tree, then reverse.
+  const visited = new Set();
+  const queue = [rootPid];
+  const order = [];
+  while (queue.length) {
+    const current = queue.shift();
+    if (visited.has(current)) continue;
+    visited.add(current);
+    let out = '';
+    try { out = String(shared.exec(`pgrep -P ${current}`, { timeout: 2000 }) || ''); }
+    catch { /* no children or pgrep missing */ continue; }
+    const children = out.split(/\s+/).map(s => Number(s)).filter(n => Number.isFinite(n) && n > 0);
+    for (const child of children) {
+      if (visited.has(child)) continue;
+      order.push(child);
+      queue.push(child);
+    }
+  }
+  return order.reverse();
+}
+
 function checkSteering(config) {
   const activeProcesses = engine().activeProcesses;
+  // Gap B: stranded-deferred sweep runs BEFORE the per-dispatch scan so a
+  // stranded info still records its warning even if it has no new inbox file.
+  try { checkDeferredStranded(activeProcesses, config); }
+  catch (err) { try { log('warn', `Steering: checkDeferredStranded failed: ${err.message}`); } catch {} }
+
   for (const [id, info] of activeProcesses) {
-    // Gap A (W-mq066js7000fff1f-b): scan agents/<id>/steering-ack/ for any
-    // ack files the agent has dropped since the last tick. Each <id>.ack
-    // removes its matching inbox file (lookup via frontmatter steerId), so
-    // unread/pending iteration below naturally skips messages already
-    // acknowledged via the explicit contract.
+    // Gap A (W-mq066js7000fff1f-b, master): scan agents/<id>/steering-ack/
+    // for any ack files the agent has dropped since the last tick. Each
+    // <id>.ack removes its matching inbox file (lookup via frontmatter
+    // steerId), so unread/pending iteration below naturally skips messages
+    // already acknowledged via the explicit contract.
     let ackedFromDir = [];
     try {
       ackedFromDir = steering.ackSteeringFromAckDir(info.agentId);
@@ -140,20 +372,12 @@ function checkSteering(config) {
       }
     }
 
-    // Recovery: if steering kill hasn't resulted in process exit within 30s, force-retry.
-    // This catches cases where killImmediate silently failed (e.g., orphaned subprocess
-    // on Unix where SIGKILL only hit spawn-agent.js, not the Claude CLI tree).
-    if (info._steeringAt && Date.now() - info._steeringAt > STEERING_KILL_RETRY_MS) {
-      if (!info._steeringRetried) {
-        log('warn', `Steering: ${info.agentId} (${id}) didn't exit ${STEERING_KILL_RETRY_MS / 1000}s after kill — retrying`);
-        shared.killImmediate(info.proc);
-        // On Unix, also try to kill children that may have been orphaned
-        if (process.platform !== 'win32' && info.proc?.pid) {
-          try { shared.exec(`pkill -KILL -P ${info.proc.pid}`, { timeout: 3000 }); } catch { /* children may already be dead */ }
-        }
-        info._steeringRetried = true;
-      }
-      continue;
+    // Gap C (this PR): if a steering kill is in-flight, run the escalation
+    // ladder. The ladder owns all retry side effects and the give-up exit,
+    // and replaces the old one-shot STEERING_KILL_RETRY_MS retry path.
+    if (info._steeringAt && !info._steeringGaveUp) {
+      const fired = _runSteeringKillLadder(id, info, config);
+      if (fired) continue;
     }
 
     // Skip if already being steered (prevents double-kill race)
@@ -217,6 +441,43 @@ function checkSteering(config) {
   }
 }
 
+// W-mq066js7000fff1f-c (Gap G): when engine.js#onAgentClose's "No conversation
+// found" branch is about to unlink the session.json, any steering-store entries
+// still in flight against that purged sessionId would silently strand. This
+// helper drops them with `status='dropped'` + a `[steering-failed]` live-output
+// line so the human knows to re-send. Caller MUST invoke this BEFORE the unlink.
+// No-ops cleanly when the steering-store module is absent (-d branch unmerged).
+function dropSteeringForPurgedSession(agentId, sessionId, liveOutputPath) {
+  if (!agentId || !sessionId) return { dropped: [], skipped: true };
+  const store = getSteeringStore();
+  if (!store || typeof store.listForAgent !== 'function') return { dropped: [], skipped: true };
+  let entries = [];
+  try { entries = store.listForAgent(agentId) || []; }
+  catch (err) {
+    try { log('warn', `Steering: listForAgent for ${agentId} failed: ${err.message}`); } catch {}
+    return { dropped: [], skipped: true };
+  }
+  const dropped = [];
+  for (const entry of entries) {
+    if (!entry || !STEERING_ACTIVE_STATUSES.has(String(entry.status || ''))) continue;
+    const entrySessionId = entry._steeringSessionId || entry.sessionId || entry.session_id;
+    if (entrySessionId !== sessionId) continue;
+    const entryId = entry.id || _steeringIdForEntry(entry);
+    if (!entryId) continue;
+    _safeStoreCall('updateStatus', entryId, 'dropped', { last_error: 'session-purged' });
+    const line = `\n[steering-failed] Session ${sessionId} was purged by runtime; message ${entryId} dropped, please re-send.\n`;
+    if (liveOutputPath) {
+      try { fs.appendFileSync(liveOutputPath, line); }
+      catch { /* optional */ }
+    } else {
+      _appendLiveOutputLine(agentId, line);
+    }
+    log('warn', `Steering: dropped message ${entryId} for ${agentId} (session ${sessionId} purged)`);
+    dropped.push(entryId);
+  }
+  return { dropped, skipped: false };
+}
+
 // ─── Timeout Checker ─────────────────────────────────────────────────────────
 
 function trackedProcessPid(procInfo) {
@@ -676,7 +937,11 @@ module.exports = {
   checkTimeouts,
   checkSteering,
   checkIdleThreshold,
+  dropSteeringForPurgedSession,
   isOsPidAliveForDispatch,
   parseProcessExitCode, terminalResultIndicatesError, parseTerminalResultFallbackExitCode, // exported for testing
   readFileTail, runtimeSupportsMidRunSessionId, // exported for testing
+  // exported for testing
+  rememberDeferredSteering, checkDeferredStranded, _runSteeringKillLadder, _collectDescendantPids,
+  _resetSteeringStoreCacheForTest, _setSteeringStoreForTest,
 };