@aiwg/cli 2026.10.6 → 2026.10.8

package/tools/ralph-external/lib/consecutive-failure-circuit-breaker.mjs

@@ -308,6 +308,9 @@ const HOST_CODES = new Set(['RESOURCE', 'NOT_FOUND', 'SANDBOX']);
 const PROVIDER_CODES = new Set(['NETWORK']);
 const INSTALLATION_CODES = new Set(['AUTH']);
 const MODEL_CODES = new Set(['MODEL']);
+const STATUS_REASON_CODES = new Set(['NOT_FOUND', 'SPAWN_REFUSED', 'RATE_LIMIT', 'RESOURCE', 'SANDBOX',
+  'NETWORK', 'AUTH', 'MODEL', 'UNKNOWN']);
+export const RECOVERY_STATUS_LIMIT = 32;
 
 export const scopeKeyFor = Object.freeze({
   invocation: (id) => `invocation:${id ?? 'unknown'}`,
@@ -511,6 +514,7 @@ export class ScopedFailureBreaker extends EventEmitter {
     this._scopes = new Map();
     this._outstanding = new Map();
     this._hostFailureFacts = [];
+    this._transitions = [];
     this._canarySeq = 0;
     this._observedInvocations = new Set();
     this.canariesObserved = 0;
@@ -1022,6 +1026,10 @@ export class ScopedFailureBreaker extends EventEmitter {
     const from = rec.status;
     if (from === to) return;
     rec.status = to;
+    if (rec.scopeKey.length <= 256) this._transitions.push({ scopeKey: rec.scopeKey, scope: rec.scope, from, to,
+      reasons: [...rec.evidence.keys()].filter(code => STATUS_REASON_CODES.has(code)).slice(0, 8),
+      atMs: this.nowMs(), nextEligibleAtMs: to === 'closed' ? null : rec.nextProbeAtMs });
+    if (this._transitions.length > RECOVERY_STATUS_LIMIT) this._transitions.shift();
     this.emit('transition', { scopeKey: rec.scopeKey, from, to, action,
       distinctFailures: new Set(rec.failures.map(failure => failure.invocationId)).size, reasons: [...rec.evidence.keys()],
       nextEligibleAtMs: rec.nextProbeAtMs, resetAtMs: rec.resetAtMs,
@@ -1454,6 +1462,23 @@ export class ScopedFailureBreaker extends EventEmitter {
     };
   }
 
+  /** Pure status projection: never sweep reservations, probe, or advance state. */
+  recoveryStatus() {
+    const recentKeys = [...new Set(this._transitions.map(event => event.scopeKey).reverse())];
+    const active = [...this._scopes.values()].filter(rec => rec.status !== 'closed');
+    const keys = [...new Set([...active.map(rec => rec.scopeKey), ...recentKeys])];
+    const scopes = keys.filter(key => key.length <= 256).slice(0, RECOVERY_STATUS_LIMIT).map(scopeKey => {
+      const rec = this._scopes.get(scopeKey);
+      const last = this._transitions.findLast(event => event.scopeKey === scopeKey);
+      return { scopeKey, scope: rec?.scope ?? last.scope, state: rec?.status ?? last.to,
+        reasons: rec ? [...rec.evidence.keys()].filter(code => STATUS_REASON_CODES.has(code)).slice(0, 8) : [...last.reasons],
+        nextEligibleAtMs: !rec || rec.status === 'closed' ? null : rec.nextProbeAtMs,
+        canaryInFlight: rec?.activeCanary != null };
+    });
+    return { observedAtMs: this.nowMs(), scopes, omittedScopeCount: Math.max(0, keys.length - scopes.length),
+      transitions: this._transitions.map(event => ({ ...event, reasons: [...event.reasons] })) };
+  }
+
   /** Correlate launcher-observed host faults across resolved inference backends.
    * Replay the first fault once corroborated, preserving the three-distinct
    * threshold even when the first backend alone could not establish scope.
@@ -1550,6 +1575,7 @@ export class ScopedFailureBreaker extends EventEmitter {
 
   destroy() {
     this._hostFailureFacts = [];
+    this._transitions = [];
     for (const rec of this._scopes.values()) rec.breaker.destroy();
     this._scopes.clear();
     this._outstanding.clear();

package/tools/ralph-external/lib/launcher-recovery-evidence.mjs

@@ -3,6 +3,7 @@ import { runRecoveryProbe } from './recovery-probe.mjs';
 /** Recovery evidence observed outside worker output by the launch owner. */
 const observations = new WeakMap();
 const failureHints = new WeakMap();
+const assessed = new WeakSet();
 
 export function recordLauncherRecoveryHint(result, reasonCode) {
   failureHints.set(result, reasonCode);
@@ -23,9 +24,10 @@ export function launcherRecoveryEvidence(result) {
  */
 export async function observeLauncherRecoveryOutcome({ invocation, result, installation, breaker,
   failureHint = '', beforeRequest, onDispatch, fetchImpl = globalThis.fetch, wallNowMs = Date.now, timeoutMs = 10_000 } = {}) {
-  if (!result || result.attemptOutcome !== 'failed' || result.cancelled) return;
+  if (!result || result.attemptOutcome !== 'failed' || result.cancelled || assessed.has(result)) return;
   const backend = invocation?.selected?.inferenceProvider;
   if (HOST_ERRORS.has(result.errorCode) || HOST_RESULTS.has(result.nativeResult)) {
+    assessed.add(result);
     const corroboratedBackends = breaker?.observeHostFailure({ invocationId: result.invocationId,
       inferenceProvider: backend, reasonCode: 'RESOURCE' }) ?? [];
     if (corroboratedBackends.length >= 2) observations.set(result, {
@@ -43,6 +45,10 @@ export async function observeLauncherRecoveryOutcome({ invocation, result, insta
     if (!await beforeRequest()) return;
     const requestTimeoutMs = remaining();
     if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) return;
+    // One diagnostic request per attempt, including unsuccessful diagnostics.
+    // Re-reading a result cannot consume allowance or create fresh evidence.
+    if (assessed.has(result)) return;
+    assessed.add(result);
     const observed = await runRecoveryProbe({ driver: { qualification: { installation } }, invocation: invocation ?? { transport: 'shell' },
       timeoutMs: Math.min(10_000, requestTimeoutMs), maxOutputBytes: 65_536, onDispatch, fetchImpl, wallNowMs });
     if (observed.reason === 'probe-rate-limited') {

package/tools/ralph-external/lib/recovery-probe.mjs

@@ -1,6 +1,8 @@
+import { RecoveryPolicy } from './consecutive-failure-circuit-breaker.mjs';
+
 /** A recovery probe is a conductor-owned request, never an uncontained worker. */
 export async function runRecoveryProbe({ driver, invocation, timeoutMs = 10_000, maxOutputBytes = 65_536,
-  onDispatch, fetchImpl = globalThis.fetch, wallNowMs = Date.now }) {
+  onDispatch, fetchImpl = globalThis.fetch, wallNowMs = Date.now, nowMs = () => performance.now() }) {
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 10_000
     || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 65_536) {
     throw new RangeError('Recovery probe exceeds the 10s/64KiB bounds');
@@ -19,6 +21,7 @@ export async function runRecoveryProbe({ driver, invocation, timeoutMs = 10_000,
     return failed('probe-endpoint-unavailable', { operatorIntervention: true });
   }
   const controller = new AbortController();
+  const deadlineMs = nowMs() + timeoutMs;
   const timer = setTimeout(() => controller.abort(), Math.max(1, Math.floor(timeoutMs)));
   let aborted;
   const timeout = new Promise((_, reject) => {
@@ -30,14 +33,19 @@ export async function runRecoveryProbe({ driver, invocation, timeoutMs = 10_000,
   timeout.catch(() => {});
   try {
     await onDispatch?.();
+    if (nowMs() >= deadlineMs) controller.abort();
     if (controller.signal.aborted) return failed('probe-timeout');
     try {
       // HEAD has no task, credentials, inference body or worker filesystem.
       // A successful endpoint check permits only one subsequent task canary.
       const response = await Promise.race([fetchImpl(endpoint, { method: 'HEAD', redirect: 'error', signal: controller.signal }), timeout]);
       let headerBytes = 16 + Buffer.byteLength(response.statusText ?? '');
-      for (const [name, value] of response.headers) headerBytes += Buffer.byteLength(name) + Buffer.byteLength(value) + 4;
       try {
+        if (nowMs() >= deadlineMs) { controller.abort(); return failed('probe-timeout'); }
+        for (const [name, value] of response.headers) {
+          headerBytes += Buffer.byteLength(name) + Buffer.byteLength(value) + 4;
+          if (headerBytes > maxOutputBytes) return failed('probe-output-limit');
+        }
         if (headerBytes > maxOutputBytes) return failed('probe-output-limit');
         if (response.body) return failed('probe-body-unexpected');
         const success = response.status >= 200 && response.status <= 299;
@@ -45,7 +53,8 @@ export async function runRecoveryProbe({ driver, invocation, timeoutMs = 10_000,
         if (response.status === 429) {
           const after = response.headers.get('retry-after');
           const seconds = after != null && /^\d+(?:\.\d+)?$/.test(after.trim()) ? Number(after) : null;
-          const date = seconds === null && after ? Date.parse(after) : NaN;
+          const date = seconds === null && /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(after ?? '')
+            ? Date.parse(after) : NaN;
           const reset = response.headers.get('x-ratelimit-reset');
           const resetEpoch = reset != null && /^\d+(?:\.\d+)?$/.test(reset.trim()) ? Number(reset) * 1000 : NaN;
           const resetDelay = response.headers.get('ratelimit-reset');
@@ -53,7 +62,8 @@ export async function runRecoveryProbe({ driver, invocation, timeoutMs = 10_000,
             Number.isFinite(resetEpoch) ? (resetEpoch - wallNowMs()) / 1000 : null,
             resetDelay != null && /^\d+(?:\.\d+)?$/.test(resetDelay.trim()) ? Number(resetDelay) : null]
             .filter(value => Number.isFinite(value) && value >= 0);
-          return failed('probe-rate-limited', { retryAfterSeconds: delays.length ? Math.max(...delays) : null });
+          return failed('probe-rate-limited', { retryAfterSeconds: delays.length
+            ? Math.min(RecoveryPolicy.maxRetryAfterSeconds, Math.max(...delays)) : null });
         }
         return failed('probe-failed', { status: response.status });
       } finally {

package/tools/ralph-external/process-monitor.mjs

@@ -15,7 +15,7 @@ import { hostname } from 'node:os';
 import { join, dirname } from 'path';
 import { constants } from 'node:fs';
 import { open, opendir, rename, unlink } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { createWorkerHealthObserver } from './lib/worker-health.mjs';
 
@@ -38,6 +38,9 @@ import { createWorkerHealthObserver } from './lib/worker-health.mjs';
 // error, a thrown assertion, ...) and silently report every live-process
 // health query as unavailable instead of surfacing the actual failure.
 let boundedExecFileSync = null;
+let projectRecoveryStatus = null;
+let mergeRecoveryStatuses = null;
+let projectStartupCorrection = null;
 let processHealthUnavailableReason = null;
 let importImpl;
 try {
@@ -58,6 +61,11 @@ if (importImpl) {
     if (!['AIWG_IMPLEMENTATION_MISSING', 'AIWG_PACKAGE_ROOT_MISSING'].includes(error?.code)) throw error;
     processHealthUnavailableReason = `bounded-child-process helper unavailable: implementation missing: ${error.message}`;
   }
+  try {
+    ({ projectRecoveryStatus, mergeRecoveryStatuses, projectStartupCorrection } = await importImpl(import.meta.url, 'mission-protocol/worker-status.js'));
+  } catch (error) {
+    if (!['AIWG_IMPLEMENTATION_MISSING', 'AIWG_PACKAGE_ROOT_MISSING'].includes(error?.code)) throw error;
+  }
 }
 
 /** Side-effect-free Linux sample. Unknown identity never grants signal authority. */
@@ -848,8 +856,10 @@ export async function sampleWorkerStatus(options, memory = new Map()) {
   const monotonicNow = options.monotonicNow ?? monotonicMs;
   const began = monotonicNow();
   const report = { version: 1, sampledAt, scope: 'direct-conductor', observerCoverage: 'unobserved',
-    workers: [], breakers: [], nextCheckAt: null, complete: true, findings: [], exitCode: 0 };
+    workers: [], breakers: [], recovery: { source: 'unavailable', observedAt: null, observedAtMs: null,
+      scopes: [], transitions: [], omittedScopeCount: 0, truncated: false }, nextCheckAt: null, complete: true, findings: [], exitCode: 0 };
   let root;
+  const recoveryOwners = new Map();
   try {
     root = await openStatusDirectory(options.runDir ?? options.runsRoot);
     const listing = options.runDir ? { entries: [{ name: null }], complete: true }
@@ -870,6 +880,11 @@ export async function sampleWorkerStatus(options, memory = new Map()) {
           process: await statusRecord(directory, 'process.json', true), health: await statusRecord(directory, 'health.json'),
           exit: await statusRecord(directory, 'exit.json'), scratch: await statusRecord(directory, 'last-observed.json') };
         const ownerRecord = await statusRecord(directory, '.status-observer');
+        const supervisor = records.process.supervisor;
+        const ownerHost = safeLabel(supervisor?.host), ownerBoot = safeLabel(supervisor?.bootId), ownerStart = safeLabel(supervisor?.startTicks);
+        const launcherOwnerRecorded = records.process.origin === 'launcher'
+          && supervisor?.uid === process.getuid() && Number.isSafeInteger(supervisor.pid) && supervisor.pid > 0
+          && ownerHost && ownerBoot && ownerStart;
         const expected = records.process.worker;
         // classifyWorkerStatus() also ignores an unverified worker for this
         // comparison; skip the resample too so this never samples an
@@ -884,6 +899,22 @@ export async function sampleWorkerStatus(options, memory = new Map()) {
           ? (options.sampleIdentity ?? sampleWorkerIdentity)(ownerIdentity.pid) : null;
         const row = classifyWorkerStatus(records, { now, monotonicNow: sampleTime, bootId, actual, counters,
           previous: memory.get(key), ownerRecord, actualObserver });
+        if (projectRecoveryStatus && launcherOwnerRecorded && records.process.recovery) {
+          const recovery = projectRecoveryStatus(records.process.recovery, 'recorded');
+          const ownerKey = JSON.stringify([ownerHost, ownerBoot, supervisor.pid, ownerStart]);
+          const previous = recoveryOwners.get(ownerKey);
+          if (recovery.observedAt && (!previous || Date.parse(recovery.observedAt) > Date.parse(previous.observedAt)
+            || recovery.observedAt === previous.observedAt && recovery.transitions.length >= previous.transitions.length)) {
+            const digest = createHash('sha256').update(ownerKey).digest('hex').slice(0, 12);
+            const owner = `${supervisor.pid}@${ownerHost.slice(0, 80)}:${ownerStart.slice(0, 32)}:${digest}`;
+            for (const scope of recovery.scopes) scope.owner = owner;
+            for (const transition of recovery.transitions) transition.owner = owner;
+            recoveryOwners.set(ownerKey, recovery);
+            report.recovery = mergeRecoveryStatuses([...recoveryOwners.values()]);
+          }
+        }
+        const correction = launcherOwnerRecorded && projectStartupCorrection?.(records.process.startupCorrection);
+        if (correction) row.startupCorrection = correction;
         report.findings.push(...row.findings.map(finding => `${row.invocationId}: ${finding}`));
         if (row.observerOwnership === 'unavailable') report.findings.push('OBSERVER_OWNER_UNAVAILABLE: reconcile reservation before observing');
         memory.set(key, { cpuTicks: actual?.cpuTicks ?? null, counters, health: row.health });
@@ -975,12 +1006,19 @@ export function createStatusObservationOwner() {
 export function formatWorkerStatus(report) {
   const label = value => value == null ? '?' : String(value);
   const seconds = value => value == null ? '?' : `${Math.round(value * 1000) / 1000}s`;
+  const recovery = report.recovery;
+  const recoveryLines = !recovery || recovery.source === 'unavailable'
+    ? ['Recovery scope status unavailable: no recorded recovery owner observation']
+    : [`Recovery scopes (${recovery.source}) observed=${label(recovery.observedAt)} omitted=${recovery.omittedScopeCount} truncated=${recovery.truncated}`,
+      ...recovery.scopes.map(scope => `  ${scope.scopeKey} state=${scope.state} reasons=${scope.reasons.join(',') || 'UNKNOWN'} next eligible=${label(scope.nextEligibleAt ?? scope.nextEligibleAtMs)} canary in flight=${scope.canaryInFlight}${scope.owner ? ` owner=${scope.owner}` : ''}`),
+      ...recovery.transitions.map(transition => `  ${transition.scopeKey}: ${transition.from} -> ${transition.to} at=${label(transition.at ?? transition.atMs)} reasons=${transition.reasons.join(',') || 'UNKNOWN'} next eligible=${label(transition.nextEligibleAt ?? transition.nextEligibleAtMs)}${transition.owner ? ` owner=${transition.owner}` : ''}`)];
   return [`Workers (${report.scope}) coverage=${report.observerCoverage} complete=${report.complete} breakers=${report.breakers.length} (no shared Tier 0 breaker authority)`,
     'invocation | member | state | coverage | age | last progress | remaining | cause | next action',
     ...report.workers.map(row => row.error ? `? | ? | unreadable | ? | ? | ? | ? | ${row.error.code} | ${row.nextAction}`
       : `${row.invocationId} | ${label(row.member)} | ${row.health.state} | ${row.health.coverage} | ${seconds(row.elapsedSeconds)} | ${seconds(row.ages.progressSeconds)} | ${seconds(row.remainingSeconds)} | ${row.health.reasonCode} | ${row.nextAction}\n`
-        + `  thresholds=${JSON.stringify(row.thresholds)} termination=${row.termination} verification=${label(row.verification)} observer-gap=${row.health.maxCheckGapSeconds}s`),
-    ...report.findings, `next check=${label(report.nextCheckAt)}`].join('\n');
+        + `  thresholds=${JSON.stringify(row.thresholds)} termination=${row.termination} verification=${label(row.verification)} observer-gap=${row.health.maxCheckGapSeconds}s`
+        + (row.startupCorrection ? `\n  startup correction=${row.startupCorrection.action} state=${row.startupCorrection.state} reason=${row.startupCorrection.reasonCode} stop=${label(row.startupCorrection.stopCode)}` : '')),
+    ...recoveryLines, ...report.findings, `next check=${label(report.nextCheckAt)}`].join('\n');
 }
 
 /** One bounded foreground loop. Timeout only stops watching, never the worker. */

package/tools/ralph-external/session-launcher.mjs

@@ -487,6 +487,10 @@ function workerLaunchRefusal(outcome) {
     : 'Worker launch did not return an attached child');
 }
 
+// Only the admitted direct owner can supply inputs for an automatic correction.
+// Neither worker output nor a caller-supplied result can populate this context.
+const directStartupCorrectionContext = new WeakMap();
+
 async function launchOneWorker(owner, options) {
   const { inspectWorkerPath: inspect, revalidateWorkerInvocationPlan: validate } = await importImpl(import.meta.url, 'serve/worker-invocation.js');
   const { qualificationDigest } = await importImpl(import.meta.url, 'models/qualification-digest.mjs');
@@ -664,6 +668,7 @@ async function launchOneWorker(owner, options) {
   // worker-writable captureRoot fell back to the in-process ledger) is
   // folded in up front so every exit path reports it.
   const ledgerDiagnostics = admission.ledgerDiagnostic ? [admission.ledgerDiagnostic] : [];
+  const startupQualification = structuredClone(inputs.drivers[invocation.selected.cli].qualification);
   const settleLedger = async (outcome) => {
     const diagnostic = await settleDirectWorker(admission, outcome);
     if (diagnostic) ledgerDiagnostics.push(diagnostic);
@@ -747,11 +752,22 @@ async function launchOneWorker(owner, options) {
   // writes; `.catch(() => {})` keeps a prior failure from poisoning it, and
   // the per-call promise returned to the caller still reflects this write's
   // own outcome.
+  let latestProcessRecord = null;
   const publish = (name, value) => {
+    if (name === 'process.json') {
+      value = { ...value, recovery: { ...admission.breaker.recoveryStatus(), observedAt: new Date().toISOString() } };
+      if (options.startupCorrectionRecord) value.startupCorrection = options.startupCorrectionRecord;
+      latestProcessRecord = value;
+    }
     const write = publishing.catch(() => {}).then(() => writeRecord(runDir, name, value, inspect));
     publishing = write.catch(error => { publishFailures.push({ name, error: error?.message ?? String(error) }); });
     return write;
   };
+  const publishRecovery = () => {
+    if (latestProcessRecord) return publish('process.json', latestProcessRecord);
+  };
+  const onScopeTransition = () => { publishRecovery()?.catch(() => {}); };
+  admission.breaker.on('transition', onScopeTransition);
   const handles = [];
   let outcome;
   let artifacts;
@@ -914,6 +930,8 @@ async function launchOneWorker(owner, options) {
     // accumulated across this attempt's lifecycle on the returned result,
     // mirroring `publishFailures` — never silently discarded.
     if (ledgerDiagnostics.length && result) result.ledgerDiagnostics = ledgerDiagnostics.slice();
+    directStartupCorrectionContext.set(owner, { saved, invocation, loadInputs, clock, dispatchGuard,
+      ledger: admission.ledger, inspect, qualification: startupQualification });
     return result;
   } catch (error) {
     if (!outcome?.child) {
@@ -985,6 +1003,8 @@ async function launchOneWorker(owner, options) {
     if (ledgerDiagnostics.length) error.ledgerDiagnostics = ledgerDiagnostics;
     throw error;
   } finally {
+    admission.breaker.removeListener('transition', onScopeTransition);
+    await publishing;
     try { await artifacts?.cleanup(); } finally {
       // Never chmod a worker-replaced pathname; only the inodes we opened.
       for (const handle of handles) { await handle.chmod(0o600).catch(() => {}); await handle.close().catch(() => {}); }
@@ -3916,6 +3936,102 @@ export function classifyAttemptForSettlement(invocation, result, { quotaAccount
     inferenceProvider: selected.inferenceProvider ?? null, quotaAccount, installationQualifier };
 }
 
+/** Refresh only a demonstrated stale executable binding. Installation, login,
+ * permissions, models, working directories and policy are never repaired here.
+ * One retry shares the original task clock and the existing atomic ledgers. */
+async function correctDirectWorkerStartup(owner, options, previous) {
+  const context = directStartupCorrectionContext.get(owner);
+  if (!context || options.correctStartup !== undefined || previous?.errorCode !== 'ENOENT'
+    || previous.termination !== 'confirmed' || previous.exitCode != null || previous.signal != null
+    || previous.cancelled || previous.timedOut || previous.publishFailures?.length
+    || classifyLaunchOutcomeForRecovery(previous).reasonCode !== 'NOT_FOUND') return previous;
+  const { saved, invocation, loadInputs, clock, dispatchGuard, ledger, inspect, qualification } = context;
+  const record = { action: 'refresh-executable-binding', reasonCode: 'NOT_FOUND', state: 'stopped',
+    previousInvocationId: previous.invocationId };
+  const recordAt = async (runDir, invocationId) => {
+    const processRecord = JSON.parse((await boundedPrivateRead(join(runDir, 'process.json'), 65536, inspect)).toString('utf8'));
+    if (processRecord.origin !== 'launcher' || processRecord.invocationId !== invocationId) throw new Error('Correction record identity changed');
+    await (options.publishRecord ?? publishWorkerRecord)(runDir, 'process.json', { ...processRecord, startupCorrection: { ...record } }, inspect);
+  };
+  const stop = async code => {
+    record.stopCode = code;
+    previous.startupCorrection = { ...record };
+    await recordAt(options.runDir, previous.invocationId);
+    return previous;
+  };
+  const guardStop = () => dispatchGuard?.isCancelled?.() === true ? 'CANCELLED'
+    : dispatchGuard?.deadlineAtMs != null && (dispatchGuard.nowMs?.() ?? Date.now()) >= dispatchGuard.deadlineAtMs ? 'DEADLINE' : null;
+  if (ledger?.n >= ledger?.maxAttempts) return stop('ATTEMPT_LIMIT');
+  if (guardStop()) return stop(guardStop());
+  let inputs;
+  let plan;
+  const retryId = randomUUID();
+  const finalPath = `${invocation.finalPath}.recovery-${retryId}`;
+  try {
+    inputs = await loadInputs();
+    const { resolveWorkerInvocation } = await importImpl(import.meta.url, 'serve/worker-invocation.js');
+    plan = await resolveWorkerInvocation(inputs.snapshot, { ...saved.request, final_output: finalPath }, inputs.drivers, clock());
+  } catch { return stop('QUALIFICATION_REFUSED'); }
+  if (guardStop()) return stop(guardStop());
+  if (plan?.status !== 'eligible' || plan.mode !== 'direct' || plan.invocation?.readiness !== 'launchable') return stop('QUALIFICATION_REFUSED');
+  if (plan.invocation.argv[0] === invocation.argv[0]) return stop('UNCHANGED_EXECUTABLE');
+  // A freshly requalified installation may have new binary/proof digests.
+  // Preserve every effective adapter declaration and installation boundary.
+  const effectiveQualification = value => {
+    const copy = structuredClone(value);
+    const stripEvidence = evidence => {
+      if (evidence) for (const key of ['scopeDigest', 'fixtureDigest', 'verifiedAt', 'evidenceRef']) delete evidence[key];
+    };
+    stripEvidence(copy.adapter?.qualification);
+    for (const profile of Object.values(copy.adapter?.invocationProfiles ?? {})) stripEvidence(profile.installationQualification);
+    if (copy.installation) {
+      delete copy.installation.executable;
+      delete copy.installation.evidence;
+    }
+    if (copy.stdinFramerBinding) delete copy.stdinFramerBinding.storeDigest;
+    return JSON.stringify(copy);
+  };
+  if (effectiveQualification(qualification) !== effectiveQualification(inputs.drivers[invocation.selected.cli]?.qualification)) return stop('BINDING_CHANGED');
+  // The resolver is authoritative for the replacement executable. Everything
+  // else must remain identical, including qualified selection, policy, limits,
+  // framing, environment, controls, prompt digest and workspace. Only fresh
+  // output names and expiration are expected to differ between attempts.
+  const binding = value => {
+    const copy = structuredClone(value);
+    const replacements = ['stderrPath', 'stdoutPath', 'finalPath'].map(key => [copy[key], `<${key}>`]);
+    const normalize = value => replacements.find(([path]) => path === value)?.[1] ?? value;
+    copy.argv = copy.argv.map((value, index) => index === 0 ? '<executable>' : normalize(value));
+    delete copy.selected.qualificationDigest;
+    for (const key of ['stdoutPath', 'stderrPath', 'finalPath', 'expiresAt', 'shellCommand', 'profileDigest']) delete copy[key];
+    return JSON.stringify(copy);
+  };
+  if (binding(plan.invocation) !== binding(invocation)) return stop('BINDING_CHANGED');
+  const invocationPath = join(options.runDir, `recovery-plan-${retryId}.json`);
+  const runDir = `${options.runDir}.recovery-${retryId}`;
+  if (guardStop()) return stop(guardStop());
+  let retry;
+  try {
+    const planHandle = await withWorkerPath(invocationPath, target => open(target,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600));
+    try { await planHandle.writeFile(JSON.stringify(plan)); await planHandle.sync(); } finally { await planHandle.close(); }
+    // Publication happens before any retry launch. A record failure stops work.
+    record.state = 'applied';
+    await recordAt(options.runDir, previous.invocationId);
+    retry = await launchOneWorker(owner, { ...options, invocationPath, runDir, dispatchGuard,
+      inputs: undefined, loadInputs, retryOf: { invocationId: previous.invocationId, runDir: options.runDir },
+      correctStartup: { reasonCode: 'NOT_FOUND' }, startupCorrectionRecord: { ...record } });
+  } catch {
+    record.state = 'stopped';
+    return stop(guardStop() ?? 'RETRY_REFUSED');
+  }
+  record.retryInvocationId = retry.invocationId;
+  if (retry.attemptOutcome !== 'succeeded') { record.state = 'stopped'; record.stopCode = 'RETRY_FAILED'; }
+  retry.startupCorrection = { ...record };
+  await recordAt(options.runDir, previous.invocationId);
+  await recordAt(runDir, retry.invocationId);
+  return retry;
+}
+
 // #2915 round 8 (D6, "lazy public fields still differ after mixed use"):
 // `lastAttemptResult`/`lastAttemptInvocationId` are informational
 // bookkeeping only (#2915 step 4 — the retry gate no longer reads them;
@@ -3987,8 +4103,9 @@ export class SessionLauncher extends EventEmitter {
    * `options.correctStartup: { reasonCode, correctionsUsed }` enforces the
    * one-qualified-startup-correction budget on a conductor-declared
    * correction retry (startupCorrectionGate): unqualified causes and second
-   * corrections are refused, within the task's existing allowance. There is
-   * no automatic correction loop.
+   * corrections are refused, within the task's existing allowance. The only
+   * automatic correction refreshes a changed qualified executable binding
+   * after a launcher-observed ENOENT with confirmed stop, once per task chain.
    *
    * Both checks are gated recovery behavior, not a general launch
    * precondition: enforcement happens entirely INSIDE `launchOneWorker`,
@@ -4015,8 +4132,13 @@ export class SessionLauncher extends EventEmitter {
     // `options.retryOf`-driven and disk-verified every time) is set inside
     // `launchOneWorker` itself, gated on whether recovery actually admitted
     // this attempt (#2915 review 6, finding 6) — never here unconditionally.
-    try { return await launchOneWorker(this, options); }
+    directStartupCorrectionContext.delete(this);
+    try {
+      const result = await launchOneWorker(this, options);
+      return await correctDirectWorkerStartup(this, options, result);
+    }
     finally {
+      directStartupCorrectionContext.delete(this);
       _workerRecoverySubscriptions.get(this)?.();
       _workerRecoverySubscriptions.delete(this);
       this.workerLaunchPending = false;