@awak-app/simy-cli 0.7.14 → 0.7.16

package/src/delivery-hooks/local-runtime.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { acquireDesktopProcessLock } from '../desktop-process-lock.js';
 import { compareVersions } from '../backend-executable.js';
 import { stableHookRuntime } from '../hook-runtime.js';
+import { acquireSupervisorOwner, readSupervisorState, supervisorProcessAlive, supervisorProcessIdentity } from './supervisor-owner.js';
 
 const exec = promisify(execFile);
 const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
@@ -96,6 +97,7 @@ export async function adoptInstalledRuntime({ root, source = packageRoot, codexH
       await cp(join(source, 'node_modules'), join(target, 'node_modules'), { recursive: true, dereference: true });
     },
   });
+  if (installation.activation === 'deferred') return { adopted: false, installation };
   // A locally activated candidate is a separate explicit activation contract.
   // Retain its receipt, but prevent watchdog replay of the superseded source.
   const activeFile = join(root, 'desktop-runtime/active.json');
@@ -110,7 +112,7 @@ export async function adoptInstalledRuntime({ root, source = packageRoot, codexH
 // Install a frozen candidate alongside the released app, without replacing a
 // signed application, changing provider trust, or starting any registered task.
 export async function installLocalRuntime({ root, source = packageRoot, allowMissingLock = false, includeDependencies = false,
-  expectedInstallationDigest, verifyBeforeActivate = async () => {},
+  expectedInstallationDigest, verifyBeforeActivate = async () => {}, handoverId,
   installDependencies = async target => exec(process.platform === 'win32' ? 'npm.cmd' : 'npm',
     ['ci', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: target, timeout: 120_000, maxBuffer: 1024 * 1024 }),
 } = {}) {
@@ -148,6 +150,30 @@ export async function installLocalRuntime({ root, source = packageRoot, allowMis
       const saved = JSON.parse(await readFile(join(release, 'runtime-build.json'), 'utf8'));
       if (saved.schema !== 1 || saved.digest !== digest || await fingerprint(release, { allowMissingLock, includeDependencies }) !== digest) throw new Error('Existing candidate failed integrity verification.');
     }
+    const activationLock = await acquireDesktopProcessLock(join(root, 'supervisor-runtime', 'control-lock'), {
+      alive: supervisorProcessAlive, identity: supervisorProcessIdentity });
+    let handoverOwner, handover;
+    try {
+    let control;
+    try { control = JSON.parse(await readFile(join(root, 'supervisor-runtime/control.json'), 'utf8')); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    // Preparing a release must not disable the existing watchdog's recovery
+    // contract. Keep its pin and launchers until a coordinated handover.
+    if (handoverId) {
+      handover = await readSupervisorState(join(root, 'supervisor-runtime/handover.json'));
+      if (!control?.enabled || handover?.version !== 1 || handover.id !== handoverId || handover.status !== 'drained' ||
+          handover.epoch !== control.epoch || handover.target?.digest !== digest || handover.target.release !== release ||
+          ![handover.fromDigest, digest].includes(control.digest) ||
+          ![handover.fromDigest, digest].includes(before.installation?.digest)) throw new Error('Supervisor handover changed or was stopped.');
+      // Fence every replacement until the previous owner has actually released
+      // its singleton, including the acknowledgement/release crash gap.
+      handoverOwner = await acquireSupervisorOwner(root);
+    }
+    if (!handover && control?.enabled === true && control.digest !== digest) {
+      return { schema: 1, version: before.version, digest, release,
+        activation: 'deferred', reason: 'supervisor_handover_required',
+        activeInstallation: before.installation };
+    }
     await verifyBeforeActivate();
     const bin = join(root, 'bin');
     await mkdir(bin, { recursive: true, mode: 0o700 });
@@ -169,6 +195,11 @@ export async function installLocalRuntime({ root, source = packageRoot, allowMis
       previous: before.installation?.digest === digest ? before.installation.previous
         : before.installation ? { version: before.installation.version, digest: before.installation.digest, release: before.installation.release } : null };
     await atomicJson(join(storage, 'current.json'), current);
+    if (handover) {
+      await atomicJson(join(root, 'supervisor-runtime/control.json'), { ...control, digest, release, updatedAt: Date.now() });
+      await atomicJson(join(root, 'supervisor-runtime/handover.json'), { ...handover, status: 'activated', activatedAt: Date.now() });
+    }
     return current;
+    } finally { await handoverOwner?.release(); await activationLock.release(); }
   } finally { await rm(staged, { recursive: true, force: true }); await rm(lock, { recursive: true, force: true }); }
 }

package/src/delivery-hooks/local-supervisor.js

@@ -3,23 +3,32 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { assertNoDesktopHostForOrigin } from '../desktop-process-lock.js';
 import { createManagedSupervisor } from './supervisor.js';
 import { acquireSupervisorOwner } from './supervisor-owner.js';
+import { pendingSupervisorHandover, acknowledgeSupervisorDrain } from './supervisor-handover.js';
 
 export async function superviseLocalDelivery({ root, webOrigin, once = false, signal,
   createSupervisor = createManagedSupervisor, checkOwner = assertNoDesktopHostForOrigin, wait = delay,
-  acquireOwner = acquireSupervisorOwner } = {}) {
+  acquireOwner = acquireSupervisorOwner, pendingHandover = pendingSupervisorHandover,
+  acknowledgeDrain = acknowledgeSupervisorDrain } = {}) {
   // Delivery records share this local root across origins. A staging desktop
   // can own the same provider session, so fence every live owner in this root.
   const check = () => checkOwner(dirname(root), null);
   await check();
-  const owner = await acquireOwner(dirname(root));
+  const owner = await acquireOwner(dirname(root), { handoverVersion: 1 });
   try {
   await check();
-  const supervisor = createSupervisor({ root, webOrigin });
+  const supervisor = createSupervisor({ root, webOrigin,
+    shouldYield: async () => Boolean(await pendingHandover(dirname(root), owner.nonce)) });
   const stop = () => { void supervisor.close(); };
   signal?.addEventListener('abort', stop, { once: true });
   try {
     do {
       if (signal?.aborted) break;
+      const handover = await pendingHandover(dirname(root), owner.nonce);
+      if (handover) {
+        await supervisor.drain();
+        await acknowledgeDrain(dirname(root), handover, signal);
+        break;
+      }
       await check();
       await supervisor.tick();
       if (once) break;

package/src/delivery-hooks/supervisor-handover.js

@@ -0,0 +1,84 @@
+import { join, resolve } from 'node:path';
+import { lstat, realpath } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { acquireDesktopProcessLock } from '../desktop-process-lock.js';
+import { localRuntimeStatus, installLocalRuntime } from './local-runtime.js';
+import { observeSupervisorOwner, readSupervisorState, saveSupervisorState, supervisorProcessIdentity, supervisorProcessAlive } from './supervisor-owner.js';
+
+export const handoverPath = root => join(root, 'supervisor-runtime/handover.json');
+const controlPath = root => join(root, 'supervisor-runtime/control.json');
+const lockControl = root => acquireDesktopProcessLock(join(root, 'supervisor-runtime/control-lock'), {
+  alive: supervisorProcessAlive, identity: supervisorProcessIdentity });
+
+export async function requestSupervisorHandover({ root, release, observeOwner = observeSupervisorOwner } = {}) {
+  const target = resolve(release);
+  if ((await lstat(target)).isSymbolicLink() || await realpath(target) !== target) throw new Error('Use a canonical immutable release.');
+  const candidate = await localRuntimeStatus({ root, source: target });
+  if (target !== join(resolve(root), 'delivery-runtime/releases', candidate.sourceDigest)) throw new Error('Handover target is not a verified installed release.');
+  const lock = await lockControl(root);
+  try {
+    const control = await readSupervisorState(controlPath(root));
+    if (!control?.enabled) return { status: 'not_requested', reason: 'supervisor_disabled' };
+    const owner = await observeOwner(root);
+    const watcher = await readSupervisorState(join(root, 'supervisor-runtime/watchdog.json'));
+    // Never signal old/unknown owners, or mistake process liveness for support.
+    if (owner.state !== 'running' || owner.handoverVersion !== 1 || !Number.isFinite(owner.lastHeartbeatAt) || owner.heartbeatStale) return {
+      status: 'not_requested', reason: 'owner_handover_unavailable', owner };
+    if (watcher?.handoverVersion !== 1 || watcher.epoch !== control.epoch || !Number.isFinite(watcher.at) ||
+        Date.now() - watcher.at > 30_000) return { status: 'not_requested', reason: 'watcher_handover_unavailable' };
+    const watcherOwner = await readSupervisorState(join(root, 'supervisor-runtime/watcher/desktop-app.lock/owner.json'));
+    if (!watcherOwner?.nonce || watcherOwner.nonce !== watcher.watcherNonce ||
+        await supervisorProcessIdentity(watcherOwner.pid).catch(() => null) !== watcherOwner.startedAt) return {
+      status: 'not_requested', reason: 'watcher_identity_unconfirmed' };
+    if (control.digest === candidate.sourceDigest) return { status: 'already_selected' };
+    const previous = await readSupervisorState(handoverPath(root));
+    if (previous && ['requested', 'drained'].includes(previous.status) && previous.epoch === control.epoch) {
+      if (previous.target.digest === candidate.sourceDigest) {
+        if (previous.status === 'drained' || previous.ownerNonce === owner.nonce) return previous;
+        // The original owner died before acknowledging. Rebind only after a
+        // fresh explicit retry, retaining the original identity and request.
+        const rebound = { ...previous, ownerNonce: owner.nonce, previousOwnerNonce: previous.ownerNonce, reboundAt: Date.now() };
+        await saveSupervisorState(handoverPath(root), rebound); return rebound;
+      }
+      throw new Error('Another supervisor handover is pending.');
+    }
+    const request = { version: 1, id: randomUUID(), status: 'requested', epoch: control.epoch,
+      ownerNonce: owner.nonce, fromDigest: control.digest, requestedAt: Date.now(),
+      target: { digest: candidate.sourceDigest, release: target, version: candidate.version } };
+    await saveSupervisorState(handoverPath(root), request);
+    return request;
+  } finally { await lock.release(); }
+}
+
+export async function pendingSupervisorHandover(root, nonce) {
+  const request = await readSupervisorState(handoverPath(root));
+  if (request?.version !== 1 || request.status !== 'requested' || request.ownerNonce !== nonce) return null;
+  const control = await readSupervisorState(controlPath(root));
+  return control?.enabled && control.epoch === request.epoch && control.digest === request.fromDigest ? request : null;
+}
+
+export async function acknowledgeSupervisorDrain(root, request, signal) {
+  const lock = await lockControl(root);
+  try {
+    const current = await pendingSupervisorHandover(root, request.ownerNonce);
+    if (signal?.aborted || current?.id !== request.id) return false;
+    await saveSupervisorState(handoverPath(root), { ...current, status: 'drained', drainedAt: Date.now() });
+    return true;
+  } finally { await lock.release(); }
+}
+
+// A watcher can finish an interrupted activation from the same durable request.
+// installLocalRuntime revalidates epoch, owner absence and release under locks.
+export async function completeSupervisorHandover(root) {
+  const request = await readSupervisorState(handoverPath(root));
+  if (request?.version !== 1 || request.status !== 'drained') return null;
+  const control = await readSupervisorState(controlPath(root));
+  if (!control?.enabled || control.epoch !== request.epoch) return null;
+  // Installed bundles may omit the lockfile and include dependencies in their
+  // fingerprint. Keep that format when activating the already-frozen release.
+  const build = await readSupervisorState(join(request.target.release, 'runtime-build.json'));
+  const includeDependencies = build?.fingerprintVersion === 2;
+  const candidate = await localRuntimeStatus({ root, source: request.target.release, allowMissingLock: true, includeDependencies });
+  if (candidate.sourceDigest !== request.target.digest) throw new Error('Supervisor handover runtime changed before activation.');
+  return installLocalRuntime({ root, source: request.target.release, handoverId: request.id, allowMissingLock: true, includeDependencies });
+}

package/src/delivery-hooks/supervisor-owner.js

@@ -47,6 +47,7 @@ export async function observeSupervisorOwner(root, { now = Date.now(), alive = s
   try { heartbeat = await readSupervisorState(join(supervisorOwnerRoot(root), 'heartbeat.json')); } catch {}
   const lastHeartbeatAt = heartbeat?.nonce === owner.nonce && Number.isFinite(heartbeat.at) ? heartbeat.at : null;
   return { state: 'running', pid: owner.pid, nonce: owner.nonce, lastHeartbeatAt,
+    ...(heartbeat?.nonce === owner.nonce && heartbeat.handoverVersion === 1 ? { handoverVersion: 1 } : {}),
     heartbeatStale: lastHeartbeatAt !== null && now - lastHeartbeatAt > 60_000 };
 }
 
@@ -54,14 +55,14 @@ export async function observeSupervisorOwner(root, { now = Date.now(), alive = s
 // than letting a missing identity probe reclaim a live owner. Task leases and
 // desktop ownership remain separate, and keep their existing authority checks.
 export async function acquireSupervisorOwner(root, { alive = supervisorProcessAlive,
-  identity = supervisorProcessIdentity, heartbeatMs = 15_000 } = {}) {
+  identity = supervisorProcessIdentity, heartbeatMs = 15_000, handoverVersion } = {}) {
   const directory = supervisorOwnerRoot(root);
   const lock = await acquireDesktopProcessLock(directory, { alive, identity });
   const file = join(directory, 'heartbeat.json');
   let pending = Promise.resolve(), closed = false;
   const beat = () => {
     pending = pending.catch(() => {}).then(async () => {
-      if (!closed) await saveSupervisorState(file, { version: 1, pid: process.pid, nonce: lock.nonce, at: Date.now() });
+      if (!closed) await saveSupervisorState(file, { version: 1, pid: process.pid, nonce: lock.nonce, at: Date.now(), ...(handoverVersion === 1 ? { handoverVersion } : {}) });
     });
     return pending;
   };

package/src/delivery-hooks/supervisor-service.js

@@ -2,8 +2,10 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { mkdir, lstat, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, isAbsolute, delimiter } from 'node:path';
 import { pinnedWorkflowSource } from './local-runtime.js';
+import { inspectBackendExecutable, backendCandidates, CODEX_WRITER_LOCK_MINIMUM_VERSION } from '../backend-executable.js';
+import { runSceneReasoning } from '../codex-plugins/simy/hooks/scene-reasoning.mjs';
 import { readSupervisorState } from './supervisor-owner.js';
 
 const exec = promisify(execFile);
@@ -12,9 +14,12 @@ const xml = text => String(text).replaceAll('&', '&amp;').replaceAll('<', '&lt;'
 const systemdArgument = text => `"${String(text).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('$', () => '$$')}"`;
 const windowsArgument = text => `"${String(text).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1')}"`;
 
-export function supervisorServiceDefinition({ root, entry, node = process.execPath, platform = process.platform, home = homedir() }) {
+export function supervisorServiceDefinition({ root, entry, node = process.execPath, platform = process.platform, home = homedir(), providerEnvironment = {} }) {
   if ([root, entry, node].some(value => typeof value !== 'string' || /[\r\n\0]/.test(value))) throw new Error('Invalid supervisor service path.');
-  const args = [entry, 'delivery', 'runtime', 'supervisor-watch', '--root', root, '--no-auto-update'];
+  const environment = Object.fromEntries(Object.entries(providerEnvironment).filter(([key]) => ['PATH', 'SIMY_CODEX_BIN', 'SIMY_CODEX_EXPECTED_VERSION'].includes(key)));
+  if (Object.values(environment).some(value => typeof value !== 'string' || /[\r\n\0]/.test(value))) throw new Error('Invalid provider environment.');
+  const bootstrap = Object.keys(environment).length ? ['--import', `data:text/javascript,${encodeURIComponent(`Object.assign(process.env,${JSON.stringify(environment)})`)}`] : [];
+  const args = [...bootstrap, entry, 'delivery', 'runtime', 'supervisor-watch', '--root', root, '--no-auto-update'];
   if (platform === 'linux') {
     const name = 'simy-delivery-supervisor.service';
     return { name, file: join(home, '.config/systemd/user', name),
@@ -37,13 +42,14 @@ export function supervisorServiceDefinition({ root, entry, node = process.execPa
 // Explicit service installation only. Installing/updating a runtime alone
 // never enables this service or enrolls a conversation.
 export async function installSupervisorService({ root, home = homedir(), platform = process.platform,
-  run = exec, inspectPin = pinnedWorkflowSource } = {}) {
+  run = exec, inspectPin = pinnedWorkflowSource, inspectBackend = inspectBackendExecutable, environment = process.env } = {}) {
   const control = await readSupervisorState(join(root, 'supervisor-runtime/control.json'));
   if (control?.version !== 1 || control.enabled !== true) throw new Error('Enable supervisor recovery explicitly before installing its OS service.');
   await inspectPin({ root });
   const pin = await readSupervisorState(join(root, 'delivery-runtime/current.json'));
   if (!pin || pin.digest !== control.digest || pin.release !== control.release) throw new Error('Supervisor activation no longer matches the fixed runtime.');
-  const definition = supervisorServiceDefinition({ root, home, platform, entry: join(pin.release, 'src/index.js') });
+  const provider = await supervisorProviderEnvironment({ home, platform, environment, inspectBackend });
+  const definition = supervisorServiceDefinition({ root, home, platform, entry: join(pin.release, 'src/index.js'), providerEnvironment: provider.environment });
   try {
     const info = await lstat(definition.file);
     if (!info.isFile() || info.isSymbolicLink() || !(await readFile(definition.file, 'utf8')).includes(marker)) throw new Error('Supervisor service path is not managed by SIMY.');
@@ -61,5 +67,29 @@ export async function installSupervisorService({ root, home = homedir(), platfor
     await run(scheduler, ['/Create', '/TN', definition.name, '/XML', definition.file, '/F']);
     await run(scheduler, ['/Run', '/TN', definition.name]);
   }
-  return { ...definition, content: undefined, status: 'registered', scope: 'previously_enrolled_tasks_only' };
+  return { ...definition, content: undefined, status: 'registered', execution: 'awaiting_service_observation', provider: provider.inspection, scope: 'previously_enrolled_tasks_only' };
+}
+
+
+// Resolve and re-probe under exactly the environment passed to the service.
+// This is a prerequisite observation, never proof of task execution/acceptance.
+export async function supervisorProviderEnvironment({ home = homedir(), platform = process.platform, environment = process.env,
+  inspectBackend = inspectBackendExecutable, onStep } = {}) {
+  return runSceneReasoning({ home, platform, environment }, {
+    understand_scene: scene => ({ ...scene, candidates: backendCandidates('codex', { home, platform, environment }).filter(value => typeof value === 'string' && isAbsolute(value)) }),
+    derive_perspectives: async scene => ({ ...scene, inspection: await inspectBackend('codex', {
+      candidates: scene.candidates, minimumVersion: CODEX_WRITER_LOCK_MINIMUM_VERSION, discoveryOptions: { home, platform, environment },
+    }) }),
+    prioritize_options: scene => {
+      if (!scene.inspection.compatible || !isAbsolute(scene.inspection.executable || '')) throw new Error('No compatible absolute Codex executable for the supervisor service.');
+      const selected = scene.inspection.executable;
+      return { ...scene, selected, environment: { PATH: [dirname(process.execPath), dirname(selected), environment.PATH || environment.Path || ''].join(delimiter), SIMY_CODEX_BIN: selected, SIMY_CODEX_EXPECTED_VERSION: scene.inspection.installed_version } };
+    },
+    connect_to_next_check: async scene => {
+      const verified = await inspectBackend('codex', { candidates: [scene.selected], minimumVersion: CODEX_WRITER_LOCK_MINIMUM_VERSION,
+        discoveryOptions: { home, platform, environment: scene.environment }, executionEnvironment: scene.environment });
+      if (!verified.compatible || verified.executable !== scene.selected || verified.installed_version !== scene.inspection.installed_version) throw new Error('Supervisor provider changed during service-environment verification.');
+      return { environment: scene.environment, inspection: verified };
+    },
+  }, { onStep });
 }

package/src/delivery-hooks/supervisor-watchdog.js

@@ -5,6 +5,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { acquireDesktopProcessLock, assertNoDesktopHostForOrigin } from '../desktop-process-lock.js';
 import { pinnedWorkflowSource } from './local-runtime.js';
 import { resolveWebOrigin } from '../web-origin.js';
+import { completeSupervisorHandover } from './supervisor-handover.js';
 import { observeSupervisorOwner, supervisorProcessAlive, supervisorProcessIdentity,
   readSupervisorState, saveSupervisorState } from './supervisor-owner.js';
 
@@ -39,17 +40,18 @@ export async function supervisorWatchdogStatus({ root, now = Date.now(), observe
 export function createSupervisorWatchdog({ root, inspectPin = verifiedPin, readControl = () => readSupervisorState(controlPath(root)),
   observeOwner = observeSupervisorOwner, checkDesktop = assertNoDesktopHostForOrigin,
   launch = (bin, args, options) => spawn(bin, args, options), now = Date.now,
+  completeHandover = completeSupervisorHandover, watcherNonce,
   identity = supervisorProcessIdentity, save = state => saveSupervisorState(statePath(root), state) } = {}) {
   let child = null, childIdentity = null, launchTime = null, closed = false, running = null, lastExit = null;
-  let pendingPin = null, lastWall = null, controlEpoch;
+  let pendingPin = null, lastWall = null, controlEpoch, handoverRetryAt = 0;
   const clock = () => Math.max(0, now());
   const tick = async () => {
     if (closed) return;
     const at = clock(), control = await readControl();
     controlEpoch = control?.epoch;
     const previous = pendingPin || await readSupervisorState(statePath(root));
-    const state = { version: 1, at, action: 'observe', supervisor: null, lastExit,
-      lastLaunchAt: launchTime ?? previous?.lastLaunchAt ?? null, epoch: previous?.epoch || null };
+    const state = { version: 1, handoverVersion: 1, watcherNonce, at, action: 'observe', supervisor: null, lastExit,
+      lastLaunchAt: launchTime ?? previous?.lastLaunchAt ?? null, epoch: control?.epoch || null };
     if (!control || control.version !== 1 || control.enabled !== true) { state.action = 'disabled'; await save(state); return state; }
     state.supervisor = await observeOwner(root, { now: at });
     if (state.supervisor.state === 'running') {
@@ -57,6 +59,15 @@ export function createSupervisorWatchdog({ root, inspectPin = verifiedPin, readC
       await save(state); return state;
     }
     if (!['missing', 'dead'].includes(state.supervisor.state)) { state.action = 'owner_unknown'; await save(state); return state; }
+    const retryAt = Math.max(handoverRetryAt, previous?.handoverRetryAt || 0);
+    if (retryAt > at) { state.action = 'handover_backoff'; state.handoverRetryAt = retryAt; await save(state); return state; }
+    try {
+      if (await completeHandover(root)) { state.action = 'handover_activated'; await save(state); return state; }
+    } catch (error) {
+      state.action = 'handover_wait'; state.reason = error.code === 'process_conflict' ? 'owner_not_released' : 'activation_failed';
+      handoverRetryAt = state.handoverRetryAt = at + 30_000;
+      await save(state); return state;
+    }
     if (child && child.exitCode === null && child.signalCode === null) { state.action = 'child_starting'; await save(state); return state; }
     // Persist the launch intent before spawn. On watchdog crash/restart this
     // gives the previous child time to publish its singleton owner receipt.
@@ -125,7 +136,7 @@ export async function watchSupervisor({ root, signal, once = false, wait = delay
   let watchdog, initialEpoch;
   try {
     initialEpoch = (await readSupervisorState(controlPath(root)))?.epoch;
-    watchdog = createWatchdog({ root });
+    watchdog = createWatchdog({ root, watcherNonce: lock.nonce });
     do {
       if (signal?.aborted) break;
       await watchdog.tick();

package/src/delivery-hooks/supervisor.js

@@ -1,6 +1,8 @@
 import { captureDispatchProvenance } from '../update-detachment/provenance.js';
 import { captureDispatchOwner, assertTaskAdmission, dispatchWithFence, queueDispatchReceipt, rootFromDelivery, observeDispatchEvent } from '../update-detachment/dispatch-gate.js';
 import { safeCheckpointDiagnostic } from './checkpoint-diagnostic.js';
+import { continueResultCycle, resultEvent, executeResultCycle, acceptResultEvent } from '../codex-plugins/simy/hooks/result-cycle.mjs';
+import { finalResponseRecoveryInstruction } from '../session-supervision/final-response-recovery.js';
 import { recordHandoffStage } from '../codex-plugins/simy/hooks/consistency-handoff.mjs';
 import { retainControllerEvidence } from '../codex-plugins/simy/hooks/purpose-evidence.mjs';
 import { workspaceIdentity, reviewWorkspaceIdentity } from '../session-supervision/purpose-verification.js';
@@ -15,9 +17,10 @@ import { requireProviderLink } from '../provider-links.js';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
-import { hasPendingUserStop, recordPath, canExecuteAutonomousExternal, automaticContinuationAllowed, settlePurposeVerification, assessedCheckpointContract, checkpointDelivery, decideStop, deliveryProgressContext, deliveryStop, listRecords, readRecord, managedBudgetReason, notifyState, processIdentity, sharesTaskWorkspace, taskDirectory, reconcileRecords, updateRecord, verifyAutomaticCriteria } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { hasPendingUserStop, recordPath, canExecuteAutonomousExternal, automaticContinuationAllowed, queuePurposeDiagnosis, settlePurposeVerification, assessedCheckpointContract, checkpointDelivery, decideStop, deliveryProgressContext, deliveryStop, listRecords, readRecord, managedBudgetReason, notifyState, processIdentity, sharesTaskWorkspace, taskDirectory, reconcileRecords, updateRecord, verifyAutomaticCriteria } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
 import { resolveBackendExecutable } from '../backend-executable.js';
-import { executeCodexAppServer } from '../session-supervision/codex-app-server.js';
+import { safeProviderFailure, providerEnvironmentIdentity, checkProviderRetry } from '../session-supervision/provider-failure.js';
+import { executeCodexAppServer, inspectCodexAppServer } from '../session-supervision/codex-app-server.js';
 import { acquireWorkspaceLease, leaseOwnerDead } from '../session-supervision/workspace-lease.js';
 
 const MAX_OUTPUT = 64 * 1024;
@@ -150,7 +153,7 @@ export async function executeCodexResume(record, { signal, root, leaseId, execut
   });
 }
 
-export async function tickManagedTasks({ root, webOrigin, now = Date.now(), execute, inspectProcess = processIdentity, signal, beforeClaim, authorizeDispatch, readRecords, observeTurn, observeAuthentication } = {}) {
+export async function tickManagedTasks({ root, webOrigin, now = Date.now(), execute, inspectProcess = processIdentity, signal, beforeClaim, authorizeDispatch, readRecords, observeTurn, observeAuthentication, inspectProvider = inspectCodexAppServer, shouldYield } = {}) {
   const tickWallStart = Date.now();
   const currentTime = () => now + Math.max(0, Date.now() - tickWallStart);
   if (signal?.aborted) return;
@@ -160,7 +163,7 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
   if (signal?.aborted) return;
   const records = await readCandidates();
   for (let record of records) {
-    if (signal?.aborted) break;
+    if (signal?.aborted || await shouldYield?.()) break;
     const claimNow = currentTime();
     if (!record.run?.managed) continue;
     record = await recoverOutcomeAuditLease(record, { root, inspectProcess });
@@ -198,6 +201,24 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
     }
     if (!automaticContinuationAllowed(record)) continue;
     try { await requireProviderLink({ root, provider: record.provider }); } catch { continue; }
+    if (run.managed.providerCapabilityWait) {
+      if (run.state !== 'recovery_required' || run.managed.resumeLease || managedBudgetReason(run, claimNow)) continue;
+      const expected = run.managed.providerCapabilityWait;
+      let check;
+      try { check = await checkProviderRetry(expected, inspectProvider, { now: claimNow, signal }); } catch { continue; }
+      record = await updateRecord(root, record.provider, record.session, current => {
+        if (current?.run?.id !== run.id || !automaticContinuationAllowed(current) || current.run.state !== 'recovery_required' ||
+            current.run.managed.resumeLease || JSON.stringify(current.run.managed.providerCapabilityWait) !== JSON.stringify(expected)) return current;
+        if (check.retry) {
+          delete current.run.managed.providerCapabilityWait;
+          current.run.managed.autoRecovery = true; current.run.recoveryCause = 'session_supervision';
+          current.run.managed.nextAttemptAt = claimNow;
+        } else current.run.managed.providerCapabilityWait = check.wait;
+        return current;
+      });
+      run = record.run;
+      if (run.managed.providerCapabilityWait) continue;
+    }
     const appServer = run.managed.resumeChannel === 'codex_app_server';
     const causeAllowed = run.recoveryCause === 'process_exit' || appServer && ['session_supervision', 'approved_action'].includes(run.recoveryCause);
     const approvedWait = run.managed.decision?.outcome === 'wait' && ['read', 'local_edit', 'local_test', 'external'].includes(run.managed.decision.action?.kind) &&
@@ -228,6 +249,7 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
     let claimed;
     try { claimed = await updateRecord(root, record.provider, record.session, current => {
       const live = current?.run;
+      if (live?.id !== run.id || live.revision !== run.revision || live.managed?.decision?.id !== run.managed?.decision?.id || live.managed?.providerCapabilityWait) return current;
       if (!automaticContinuationAllowed(current)) return current;
       if (live?.managed?.outcomeAudit?.lease) return current;
       const appChannel = live?.managed?.resumeChannel === 'codex_app_server';
@@ -245,6 +267,12 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
         action: live.managed.decision?.action || live.managed.proposedAction,
         budgetReservation: { rootTaskId: live.managed.taskId, tokens: live.managed.maxTokens ? Math.max(0, live.managed.maxTokens - (live.managed.tokensUsed || 0)) : null, state: 'reserved', epoch: leaseId }, phase: 'claimed', claimedAt: currentTime(), lastActivityAt: currentTime() };
       live.managed.executionAttempt.recoveryIncidentId = live.managed.recovery?.currentId || null;
+      const pendingResult = live.resultCycle?.events.find(row => row.id === live.resultCycle.pendingId);
+      // Carry the actual preceding result into its dispatch receipt. A synthetic
+      // initial/condition event is needed only when no unconsumed result exists.
+      if (!pendingResult || pendingResult.dispatchAttemptId) acceptResultEvent(current, resultEvent(current, {
+        kind: 'condition_changed', origin: 'supervisor_claim',
+        sourceId: `dispatch:${live.managed.decision?.id}:${live.revision}`, now: currentTime() }));
       // Retain the repair action identity during independent verification.
       // Older receipts can still be executing after a verifier; bind those to
       // the next actual diagnosis/repair only after all lease/authority fences.
@@ -318,7 +346,8 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
         if (!result) {
         await authorizeClaim();
         const runner = execute || (appServer ? executeCodexAppServer : executeCodexResume);
-        result = await runner(claimed, { signal: controller.signal, root, webOrigin, leaseId, currentTime, leaseMonitored: true,
+        result = await executeResultCycle({ record: claimed, attemptId: leaseId, execute: runner, persist: persistReceipt,
+          options: { signal: controller.signal, root, webOrigin, leaseId, currentTime, leaseMonitored: true,
           onStarted: async observation => {
             await persistReceipt(current => {
               const attempt = current?.run?.managed?.executionAttempt;
@@ -376,7 +405,7 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
               return current;
             });
             await authorizeClaim();
-          } });
+          } } });
         }
       }
     } catch (error) { result = error?.code === 'provider_link_disconnected'
@@ -384,8 +413,13 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
       : error?.code === 'desktop_access_required'
       ? { code: -3, busy: true, accessDenied: true }
       : { code: controller.signal.aborted ? -2 : -1, cancelled: controller.signal.aborted,
-        providerTurnId: error?.providerTurnId, providerSessionId:error?.providerSessionId, question: error?.question, errorCode: error?.code || 'provider_error', restorationUnverified: error?.restorationUnverified === true }; }
+        providerTurnId: error?.providerTurnId, providerSessionId:error?.providerSessionId, question: error?.question,
+        finalResponseWithoutCheckpoint: error?.finalResponseWithoutCheckpoint,
+        errorCode: error?.code || 'provider_error', diagnostic: safeProviderFailure(error?.diagnostic), restorationUnverified: error?.restorationUnverified === true }; }
     try {
+    if (!dispatched && ['unsupported', 'unavailable'].includes(result.errorCode) && ['writer_lock', 'provider_available', 'service_identity', 'bounded_history', 'connector_inventory', 'connector_pagination', 'review_configuration', 'review_isolation'].includes(result.diagnostic?.capability)) {
+      try { result.providerEnvironment = await providerEnvironmentIdentity(inspectProvider); } catch { /* No guessed identity: normal bounded failure path remains. */ }
+    }
     await usageQueue;
     if (usageError) result = { ...result, code: -1, errorCode: 'usage_unavailable' };
     usage ||= result?.usage || null;
@@ -435,6 +469,10 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
       }
       if (result.errorCode === 'checkpoint_rejected') live.managed.lastCheckpointRejection = { at: Date.now(), decisionId: claimed.run.managed.decision?.id, diagnostic: result.diagnostic };
       else if (result.code === 0) delete live.managed.lastCheckpointRejection;
+      if (result.errorCode === 'checkpoint' && result.finalResponseWithoutCheckpoint) {
+        live.managed.finalResponseWithoutCheckpoint = { ...result.finalResponseWithoutCheckpoint,
+          providerTurnId: result.providerTurnId, providerSessionId: result.providerSessionId || record.session };
+      } else if (result.code === 0) delete live.managed.finalResponseWithoutCheckpoint;
       const attempt = live.managed.executionAttempt;
       if (!result.busy && attempt?.phase === 'dispatching' && attempt.action?.kind !== 'read') live.managed.executionUncertain = {
         attemptId: leaseId, decisionId: attempt.decisionId, action: attempt.action, at: Date.now() };
@@ -445,8 +483,9 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
         checkpointRevision: live.revision, outcome: result.busy ? 'busy' : result.cancelled ? 'cancelled' : result.code === 0 ? 'checkpoint' : 'failed',
         errorCode: result.code === 0 || result.busy || result.cancelled ? null : safeProviderCode(result.errorCode),
         ...(result.providerSessionId ? {providerSessionId:result.providerSessionId} : {}),
+        ...(safeProviderFailure(result.diagnostic) ? { diagnostic: safeProviderFailure(result.diagnostic) } : {}),
         restorationUnverified: result.restorationUnverified === true,
-        reason: result.accessDenied ? 'Desktop organization access is required before another provider turn.' : result.busy ? 'Exact provider session currently has another writer.' : result.cancelled ? 'Managed recovery cancelled before completion.' : result.code === 0 ? 'Structured checkpoint recorded.' : 'Provider failed or returned an invalid checkpoint.',
+        reason: result.accessDenied ? 'Desktop organization access is required before another provider turn.' : result.busy ? 'Exact provider session currently has another writer.' : result.cancelled ? 'Managed recovery cancelled before completion.' : result.code === 0 ? 'Structured checkpoint recorded.' : result.diagnostic ? `Provider capability unavailable: ${safeProviderFailure(result.diagnostic)?.capability || 'unknown'}. Retry after its environment changes.` : 'Provider failed or returned an invalid checkpoint.',
         nextStep: live.nextStep });
       live.managed.attempts = live.managed.attempts.slice(-20);
       if (result.code !== 0) recordRecoveryStage(live, result.busy ? 'waiting' : 'interrupted', {
@@ -486,6 +525,10 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
       } else if (result.cancelled) {
         live.managed.autoRecovery = false; live.state = 'recovery_required'; live.recoveryCause = 'shutdown_cancelled';
         live.reason = 'Managed recovery was cancelled; inspect the original session before the next bounded recovery.';
+      } else if (result.providerEnvironment && !dispatched) {
+        live.managed.providerCapabilityWait = { diagnostic: safeProviderFailure(result.diagnostic), environmentIdentity: result.providerEnvironment.identity, nextCheckAt: currentTime() + 60000, checks: 0 };
+        live.managed.autoRecovery = true; live.state = 'recovery_required'; live.recoveryCause = 'session_supervision';
+        live.reason = 'Provider capability needs an environment change; bounded read-only checks continue without spending another provider turn.';
       } else if (result.code !== 0) {
         live.failures += 1; live.managed.autoRecovery = false;
         live.state = failureLimitReached(live) ? 'failed' : 'recovery_required';
@@ -493,6 +536,16 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
         live.reason = appServer ? providerFailureReason(safeProviderCode(result.errorCode)) +
           (result.restorationUnverified ? ' Original provider permissions also require inspection.' : '') :
           'Codex recovery process failed; inspect its checkpoint and original session before the next bounded recovery.';
+        // Recover the missing handoff with a read diagnosis, never by replaying
+        // the last action. The existing dispatcher rechecks leases and rights.
+        if (appServer && live.state !== 'failed' && automaticContinuationAllowed(current) &&
+            !live.managed.pendingApproval && !live.managed.nativeWait && !live.managed.purpose?.nativeBoundary &&
+            (result.errorCode === 'checkpoint' && result.finalResponseWithoutCheckpoint || result.errorCode === 'checkpoint_rejected')) {
+          await continueResultCycle(current, resultEvent(current, { kind: 'final_response', origin: 'executor_result',
+            sourceId: result.providerTurnId || leaseId, attemptId: leaseId, resultRef: `attempt:${leaseId}` }), {
+            selectNext: () => queuePurposeDiagnosis(live, finalResponseRecoveryInstruction,
+              `missing-handoff:${result.providerTurnId || leaseId}`, Date.now(), 'checkpoint') });
+        }
       } else if (live.revision <= run.revision) {
         live.failures += 1;
         live.reason = result.code === 0 ? 'Codex recovery returned without a checkpoint.' : 'Codex recovery failed; inspect the original session.';
@@ -514,6 +567,9 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
           current.run.reason = 'Verified checkpoint recorded; next bounded exact-session attempt is pending.';
         }
       }
+      if (result.code !== 0) await continueResultCycle(current, resultEvent(current, {
+        kind: 'failure', origin: 'executor_result', sourceId: result.providerTurnId || leaseId,
+        attemptId: leaseId, resultRef: `attempt:${leaseId}` }));
       current.run.updatedAt = Date.now(); notifyState(current.run, current.run.updatedAt); return current;
     });
     // Settling uncertainty must precede unlocking: otherwise another session
@@ -532,12 +588,13 @@ export function createManagedSupervisor(options) {
       if (!auditing) auditing = (async () => {
         const runtime = await desktopRuntimeStatus({ root: dirname(options.root) }).catch(() => ({ state: 'runtime_observation_failed' }));
         await runConsistencyMonitor({ root: options.root, runtime, readRecords: options.readRecords || (() => listRecords(options.root)),
-          onAudit: (record, findings, request) => auditConsistencyTask(record, findings, request, {
+          onAudit: async (record, findings, request) => closed || await options.shouldYield?.() ? undefined : auditConsistencyTask(record, findings, request, {
             root: options.root, signal: controller.signal, authorize: options.authorizeDispatch || (async () => {}) }) });
       })().catch(() => {}).finally(() => { auditing = null; });
       if (!running) running = tickManagedTasks({ ...options, signal: controller.signal }).finally(() => { running = null; });
       return running;
     },
+    async drain() { closed = true; await Promise.allSettled([running, auditing]); },
     async close() { closed = true; controller.abort(); await Promise.allSettled([running, auditing]); },
   };
 }