@awak-app/simy-cli 0.7.9 → 0.7.10

package/src/delivery-hooks/recovery.js

@@ -0,0 +1,33 @@
+import { listRecords, reconcileRecords, rootDirectory } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { recoveryObservation, recoveryReasons } from '../codex-plugins/simy/hooks/recovery-incident.mjs';
+import { reconcilePurposeTasks } from '../session-supervision/purpose-recovery.js';
+
+// Reuses the canonical controller; reconciliation itself never calls an
+// executor, approves an operation, restarts a stopped task or certifies SQM.
+export async function inspectDeliveryRecovery({ root = rootDirectory(), provider, session, taskId,
+  incidentId, reconcile = false, signal, now = Date.now(), observeTurn, observeAuthentication } = {}) {
+  if (session && !provider || provider && !['codex', 'claude'].includes(provider)) throw new Error('Specify exact --provider and --session.');
+  const select = async () => (await listRecords(root)).filter(record =>
+    (!provider || record.provider === provider) && (!session || record.session === session) &&
+    (!taskId || record.run?.managed?.taskId === taskId));
+  let records = await select();
+  if ((session || taskId) && records.length !== 1) throw new Error('Recovery target is missing or ambiguous. No task was changed.');
+  if (reconcile) {
+    if (!session && !taskId) throw new Error('Reconcile requires an exact session or task ID.');
+    signal?.throwIfAborted();
+    await reconcilePurposeTasks({ root, signal, now, readRecords: select, observeTurn, observeAuthentication });
+    signal?.throwIfAborted();
+    await reconcileRecords({ root, now, records: await select() });
+    records = await select();
+  }
+  const tasks = records.map(record => recoveryObservation(record, now)).filter(Boolean);
+  if (incidentId) {
+    const matches = records.flatMap(record => (Array.isArray(record.run?.managed?.recovery?.incidents) ? record.run.managed.recovery.incidents : [])
+      .filter(row => row?.id === incidentId).map(incident => ({ provider: record.provider, session: record.session,
+        taskId: record.run.managed.taskId, incident })));
+    if (matches.length !== 1) throw new Error('Incident is missing or ambiguous.');
+    return { version: 1, mode: 'inspection_only', ...matches[0] };
+  }
+  return { version: 1, mode: reconcile ? 'reconciled_without_dispatch' : 'inspection_only',
+    tasks, reasonCatalog: Object.values(recoveryReasons) };
+}

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

@@ -0,0 +1,74 @@
+import { readFile, stat, mkdir, rename, writeFile, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { acquireDesktopProcessLock } from '../desktop-process-lock.js';
+import { processIdentity } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { windowsProcessStart } from '../windows-processes.js';
+
+export function supervisorOwnerRoot(root) { return join(root, 'delivery-supervisor'); }
+export function supervisorProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+export async function supervisorProcessIdentity(pid) {
+  const identity = process.platform === 'win32' ? await windowsProcessStart(pid) : await processIdentity(pid);
+  if (!identity) throw new Error('Supervisor process identity is unavailable.');
+  return identity;
+}
+export async function saveSupervisorState(file, value) {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { await writeFile(temporary, JSON.stringify(value), { mode: 0o600 }); await rename(temporary, file); }
+  finally { await rm(temporary, { force: true }); }
+}
+export async function readSupervisorState(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export async function observeSupervisorOwner(root, { now = Date.now(), alive = supervisorProcessAlive,
+  identity = supervisorProcessIdentity } = {}) {
+  const directory = join(supervisorOwnerRoot(root), 'desktop-app.lock');
+  let owner;
+  try { owner = await readSupervisorState(join(directory, 'owner.json')); }
+  catch { return { state: 'unknown' }; }
+  if (!owner) {
+    try { await stat(directory); return { state: 'starting' }; }
+    catch (error) { return { state: error.code === 'ENOENT' ? 'missing' : 'unknown' }; }
+  }
+  if (!Number.isSafeInteger(owner.pid) || owner.pid < 2 || !owner.startedAt || !owner.nonce) return { state: 'unknown' };
+  let current;
+  try {
+    if (!alive(owner.pid)) return { state: 'dead', pid: owner.pid };
+    current = await identity(owner.pid);
+  } catch { return { state: 'unknown', pid: owner.pid }; }
+  if (!current) return { state: 'unknown', pid: owner.pid };
+  if (current !== owner.startedAt) return { state: 'dead', pid: owner.pid };
+  let heartbeat;
+  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,
+    heartbeatStale: lastHeartbeatAt !== null && now - lastHeartbeatAt > 60_000 };
+}
+
+// A separate singleton for the CLI supervisor. Unknown identities throw rather
+// 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 } = {}) {
+  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() });
+    });
+    return pending;
+  };
+  try { await beat(); } catch (error) { await lock.release(); throw error; }
+  const timer = setInterval(() => { void beat().catch(() => {}); }, heartbeatMs);
+  timer.unref();
+  return { nonce: lock.nonce, async release() {
+    closed = true; clearInterval(timer); await pending.catch(() => {}); await lock.release();
+  } };
+}

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

@@ -0,0 +1,65 @@
+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 { pinnedWorkflowSource } from './local-runtime.js';
+import { readSupervisorState } from './supervisor-owner.js';
+
+const exec = promisify(execFile);
+const marker = 'SIMY managed supervisor watchdog v1';
+const xml = text => String(text).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+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() }) {
+  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'];
+  if (platform === 'linux') {
+    const name = 'simy-delivery-supervisor.service';
+    return { name, file: join(home, '.config/systemd/user', name),
+      content: `# ${marker}\n[Unit]\nDescription=SIMY Delivery supervisor recovery\n\n[Service]\nType=simple\nExecStart=${[node, ...args].map(systemdArgument).join(' ')}\nRestart=on-failure\nRestartSec=15\nKillMode=process\n\n[Install]\nWantedBy=default.target\n` };
+  }
+  if (platform === 'darwin') {
+    const name = 'com.awak.simy.delivery-supervisor';
+    return { name, file: join(home, 'Library/LaunchAgents', `${name}.plist`), content:
+      `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><!-- ${marker} --><dict><key>Label</key><string>${name}</string><key>ProgramArguments</key><array>${[node, ...args].map(arg => `<string>${xml(arg)}</string>`).join('')}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict><key>ThrottleInterval</key><integer>15</integer></dict></plist>` };
+  }
+  if (platform === 'win32') {
+    const name = 'SIMYDeliverySupervisor';
+    const startAt = new Date(Date.now() + 60_000).toISOString();
+    return { name, file: join(root, 'supervisor-runtime', 'service.xml'), content:
+      `<?xml version="1.0" encoding="UTF-8"?><Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task"><!-- ${marker} --><Triggers><LogonTrigger><Enabled>true</Enabled></LogonTrigger><TimeTrigger><Repetition><Interval>PT1M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition><StartBoundary>${startAt}</StartBoundary><Enabled>true</Enabled></TimeTrigger></Triggers><Principals><Principal id="Author"><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals><Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><StartWhenAvailable>true</StartWhenAvailable><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><RestartOnFailure><Interval>PT1M</Interval><Count>3</Count></RestartOnFailure></Settings><Actions Context="Author"><Exec><Command>${xml(node)}</Command><Arguments>${xml(args.map(windowsArgument).join(' '))}</Arguments></Exec></Actions></Task>` };
+  }
+  throw new Error('Supervisor services support Linux, macOS and Windows.');
+}
+
+// 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 } = {}) {
+  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') });
+  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.');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await mkdir(dirname(definition.file), { recursive: true, mode: 0o700 });
+  await writeFile(definition.file, definition.content, { mode: 0o600 });
+  if (platform === 'linux') {
+    await run('systemctl', ['--user', 'daemon-reload']);
+    await run('systemctl', ['--user', 'enable', '--now', definition.name]);
+  } else if (platform === 'darwin') {
+    await run('/usr/bin/plutil', ['-lint', definition.file]);
+    await run('/bin/launchctl', ['bootstrap', `gui/${process.getuid()}`, definition.file]);
+  } else {
+    const scheduler = join(process.env.SystemRoot || 'C:\\Windows', 'System32/schtasks.exe');
+    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' };
+}

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

@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+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 { observeSupervisorOwner, supervisorProcessAlive, supervisorProcessIdentity,
+  readSupervisorState, saveSupervisorState } from './supervisor-owner.js';
+
+const folder = root => join(root, 'supervisor-runtime');
+const controlPath = root => join(folder(root), 'control.json');
+const statePath = root => join(folder(root), 'watchdog.json');
+async function verifiedPin(root) {
+  await pinnedWorkflowSource({ root });
+  const pin = await readSupervisorState(join(root, 'delivery-runtime/current.json'));
+  if (!pin) throw new Error('Install a fixed Delivery runtime before enabling supervisor recovery.');
+  return { digest: pin.digest, release: pin.release };
+}
+export async function setSupervisorWatchdog({ root, enabled, webOrigin,
+  inspectPin = verifiedPin, now = Date.now(), expectedEpoch } = {}) {
+  const pin = enabled ? await inspectPin(root) : null;
+  const lock = await acquireDesktopProcessLock(join(folder(root), 'control-lock'), {
+    alive: supervisorProcessAlive, identity: supervisorProcessIdentity });
+  try {
+  const previous = await readSupervisorState(controlPath(root));
+  if (expectedEpoch !== undefined && previous?.epoch !== expectedEpoch) return previous;
+  const control = { version: 1, enabled: enabled === true, epoch: randomUUID(), updatedAt: now,
+    ...(pin ? { ...pin, webOrigin: resolveWebOrigin(webOrigin) } : {}) };
+  await saveSupervisorState(controlPath(root), control);
+  return control;
+  } finally { await lock.release(); }
+}
+export async function supervisorWatchdogStatus({ root, now = Date.now(), observeOwner = observeSupervisorOwner } = {}) {
+  return { control: await readSupervisorState(controlPath(root)),
+    watchdog: await readSupervisorState(statePath(root)), supervisor: await observeOwner(root, { now }) };
+}
+
+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,
+  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;
+  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 };
+    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') {
+      state.action = state.supervisor.heartbeatStale ? 'live_owner_unhealthy' : 'live_owner_preserved';
+      await save(state); return state;
+    }
+    if (!['missing', 'dead'].includes(state.supervisor.state)) { state.action = 'owner_unknown'; 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.
+    const previousLaunch = launchTime ?? previous?.lastLaunchAt;
+    if (Number.isFinite(previousLaunch) && at - previousLaunch < 30_000) {
+      state.action = 'backoff'; state.lastLaunchAt = previousLaunch; await save(state); return state;
+    }
+    // Resume/sleep or clock regression is an observation boundary, never proof
+    // that a live provider stopped. Re-observe on the next tick first.
+    if (lastWall !== null && (at < lastWall || at - lastWall > 60_000)) {
+      lastWall = at; state.action = 'wake_reobserve'; await save(state); return state;
+    }
+    lastWall = at;
+    try { await checkDesktop(root, null); }
+    catch (error) {
+      if (error.code !== 'process_conflict') throw error;
+      state.action = 'desktop_owner_preserved'; await save(state); return state;
+    }
+    // Healthy/unknown owners and launch backoff cannot dispatch. Hash the
+    // complete immutable runtime only at an actual replacement boundary.
+    const pin = await inspectPin(root);
+    if (pin.digest !== control.digest || pin.release !== control.release) { state.action = 'pin_changed'; await save(state); return state; }
+    const fresh = await readControl();
+    if (closed || !fresh?.enabled || fresh.epoch !== control.epoch) { state.action = 'disabled_before_launch'; await save(state); return state; }
+    state.action = 'launch_prepared'; state.lastLaunchAt = at; state.epoch = control.epoch;
+    launchTime = at; pendingPin = { ...state }; await save(state);
+    // The child's independent singleton also fences the spawn/owner-publication
+    // crash gap. No task enrollment, scope, consent or budget is changed here.
+    const secondPin = await inspectPin(root);
+    const finalControl = await readControl();
+    if (closed || secondPin.digest !== pin.digest || secondPin.release !== pin.release ||
+        !finalControl?.enabled || finalControl.epoch !== control.epoch) {
+      state.action = 'launch_cancelled'; await save(state); return state;
+    }
+    const args = [join(pin.release, 'src/index.js'), 'delivery', 'supervise', '--host', control.webOrigin, '--no-auto-update'];
+    child = launch(process.execPath, args, { env: { ...process.env, SIMY_HOME: root, SIMY_AUTO_UPDATE: '0' },
+      detached: process.platform !== 'win32', stdio: 'ignore', windowsHide: true });
+    const launched = child;
+    const exited = (code, signal) => { if (child === launched) lastExit = { at: clock(), code, signal }; };
+    launched.once('error', () => exited(null, 'spawn_failed'));
+    launched.once('exit', exited);
+    try { childIdentity = launched.pid ? await identity(launched.pid) : null; } catch { childIdentity = null; }
+    launched.unref?.();
+    state.action = 'launch_requested'; state.childPid = launched.pid || null;
+    await save(state); return state;
+  };
+  return { tick() {
+    if (!running) running = tick().finally(() => { running = null; });
+    return running;
+  }, epoch: () => controlEpoch, async close({ stopChild = true } = {}) {
+    closed = true; await running?.catch(() => {});
+    // Only a child launched by this watcher can receive a graceful signal.
+    // Foreign/live/unknown owners are never killed or replaced for silence.
+    if (stopChild && child?.pid && child.exitCode === null && child.signalCode === null && childIdentity) {
+      let current; try { current = await identity(child.pid); } catch {}
+      if (current === childIdentity) child.kill('SIGTERM');
+    }
+  } };
+}
+
+export async function watchSupervisor({ root, signal, once = false, wait = delay,
+  acquireLock = () => acquireDesktopProcessLock(join(folder(root), 'watcher'), {
+    alive: supervisorProcessAlive, identity: supervisorProcessIdentity }),
+  createWatchdog = createSupervisorWatchdog } = {}) {
+  const lock = await acquireLock();
+  let watchdog, initialEpoch;
+  try {
+    initialEpoch = (await readSupervisorState(controlPath(root)))?.epoch;
+    watchdog = createWatchdog({ root });
+    do {
+      if (signal?.aborted) break;
+      await watchdog.tick();
+      if (once) break;
+      try { await wait(5_000, undefined, { signal }); }
+      catch (error) { if (!signal?.aborted) throw error; }
+    } while (!signal?.aborted);
+  } finally {
+    // An explicit watcher termination is durable across OS-service restarts.
+    try {
+      const epoch = watchdog?.epoch() ?? initialEpoch;
+      // SIGTERM is also used for OS service restarts/shutdown. An explicit
+      // disable command or foreground Ctrl-C records a durable user stop.
+      if (signal?.aborted && signal.reason === 'user_interrupt' && epoch !== undefined) {
+        await setSupervisorWatchdog({ root, enabled: false, expectedEpoch: epoch });
+      }
+    } finally {
+      // A service restart replaces the watcher, not its healthy supervisor.
+      // Foreground interruption still disables activation and stops our child.
+      try { await watchdog?.close({ stopChild: signal?.reason !== 'service_termination' && (signal?.aborted || !once) }); } finally { await lock.release(); }
+    }
+  }
+}

package/src/delivery-hooks/supervisor.js

@@ -4,6 +4,7 @@ import { retainControllerEvidence } from '../codex-plugins/simy/hooks/purpose-ev
 import { workspaceIdentity, reviewWorkspaceIdentity } from '../session-supervision/purpose-verification.js';
 import { searchEnabled, failureLimitReached } from '../codex-plugins/simy/hooks/purpose-search.mjs';
 import { reconcilePurposeTasks } from '../session-supervision/purpose-recovery.js';
+import { recordRecoveryIncident, recordRecoveryStage, settleRecoveryIncidents, resolveRecoveryReceipt } from '../codex-plugins/simy/hooks/recovery-incident.mjs';
 import { runConsistencyMonitor } from './consistency-monitor.js';
 import { desktopRuntimeStatus } from './desktop-runtime.js';
 import { auditConsistencyTask, recoverOutcomeAuditLease } from '../session-supervision/consistency-auditor.js';
@@ -170,6 +171,8 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
       await updateRecord(root, record.provider, record.session, current => {
         if (current?.run?.state !== 'auto_resuming' || current.run.managed.resumeLease?.id !== run.managed.resumeLease?.id) return current;
         current.run.state = 'recovery_required'; current.run.recoveryCause = 'interrupted_owner'; current.run.managed.autoRecovery = false;
+        recordRecoveryIncident(current.run, { code: 'interrupted_owner', subject: current.run.managed.executionAttempt?.id || '', now: claimNow });
+        recordRecoveryStage(current.run, 'interrupted', { now: claimNow, attemptId: current.run.managed.executionAttempt?.id });
         current.run.reason = 'Managed recovery was interrupted; inspect the original session before the next bounded recovery.';
         const attempt = current.run.managed.executionAttempt;
         if (attempt?.budgetReservation && attempt.phase === 'dispatching') { attempt.budgetReservation.state = 'unknown'; current.run.managed.unknownConsumption = true; if (current.run.managed.maxTokens) current.run.managed.usageBlocked = true; }
@@ -227,6 +230,7 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
       live.managed.executionAttempt = { id: leaseId, decisionId: live.managed.decision?.id || null,
         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;
       // 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.
@@ -301,6 +305,19 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
         await authorizeClaim();
         const runner = execute || (appServer ? executeCodexAppServer : executeCodexResume);
         result = await runner(claimed, { signal: controller.signal, root, webOrigin, leaseId, currentTime, leaseMonitored: true,
+          onStarted: async observation => {
+            await persistReceipt(current => {
+              const attempt = current?.run?.managed?.executionAttempt;
+              if (current?.run?.managed?.resumeLease?.id !== leaseId || attempt?.id !== leaseId) throw new Error('Recovery receipt lease changed.');
+              attempt.providerTurnId = observation.turnId;
+              attempt.providerSessionId = observation.session;
+              attempt.startedAt = currentTime();
+              recordRecoveryStage(current.run, 'started', { now: currentTime(), attemptId: leaseId,
+                decisionId: attempt.decisionId, incidentId: attempt.recoveryIncidentId,
+                providerSessionId: observation.session, providerTurnId: observation.turnId });
+              return current;
+            });
+          },
           onEvidence: async evidence => {
             await persistReceipt(current => {
               if (current?.run?.managed?.resumeLease?.id !== leaseId || current.run.managed.decision?.id !== evidence.actionId) throw new Error('Evidence capture lease changed.');
@@ -335,6 +352,8 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
               live.managed.executionAttempt.phase = 'dispatching';
               live.managed.executionAttempt.dispatchedAt = currentTime();
               live.managed.executionAttempt.lastActivityAt = currentTime();
+              recordRecoveryStage(live, 'dispatching', { now: currentTime(), attemptId: leaseId,
+                decisionId: live.managed.decision?.id, incidentId: live.managed.executionAttempt.recoveryIncidentId });
               dispatched = true;
               if (live.managed.decision?.outcome === 'wait') {
                 if (approved?.id !== live.managed.decision.id || approved.dispatchedAt) throw new Error('Selected action needs fresh approval.');
@@ -366,6 +385,10 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
           if (current?.run?.managed?.executionAttempt?.id !== leaseId) return current;
           current.run.managed.executionAttempt.phase = 'checkpointed';
           current.run.managed.executionAttempt.checkpointRevision = current.run.revision;
+          const receipt = current.run.managed.executionAttempt;
+          recordRecoveryStage(current.run, 'result_observed', { now: Date.now(), attemptId: leaseId,
+            decisionId: receipt.decisionId, incidentId: receipt.recoveryIncidentId });
+          settleRecoveryIncidents(current.run, Date.now(), leaseId);
           if (claimed.run.managed.recoveryDiagnosisDecisionId === claimed.run.managed.decision?.id &&
             current.run.managed.workHistory?.at(-1)?.result?.status === 'observed') {
             // This accepts a read-only observation, never grants a retry of the
@@ -373,6 +396,7 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
             current.run.managed.reconciledExecutions ||= [];
             current.run.managed.reconciledExecutions.push({ ...current.run.managed.executionUncertain, reconciledAt: Date.now(), revision: current.run.revision });
             current.run.managed.reconciledExecutions = current.run.managed.reconciledExecutions.slice(-10);
+            resolveRecoveryReceipt(current.run, current.run.managed.executionUncertain?.attemptId);
             delete current.run.managed.executionUncertain;
             delete current.run.managed.recoveryDiagnosisDecisionId;
           }
@@ -410,6 +434,8 @@ export async function tickManagedTasks({ root, webOrigin, now = Date.now(), exec
         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.',
         nextStep: live.nextStep });
       live.managed.attempts = live.managed.attempts.slice(-20);
+      if (result.code !== 0) recordRecoveryStage(live, result.busy ? 'waiting' : 'interrupted', {
+        now: currentTime(), attemptId: leaseId, decisionId: attempt?.decisionId, incidentId: attempt?.recoveryIncidentId });
       if (result.restorationUnverified) {
         live.managed.providerWarning = 'Original Codex permissions could not be verified after the interrupted turn; inspect that conversation.';
         if (live.state !== 'auto_resuming') live.reason = `${String(live.reason || '').slice(0, 400)} ${live.managed.providerWarning}`.trim();

package/src/direct-executor.js

@@ -1,5 +1,6 @@
 import { signalExecutorProcess } from "./runner.js";
 import { randomUUID } from "node:crypto";
+import { withSceneReasoning } from "./codex-plugins/simy/hooks/scene-reasoning.mjs";
 
 import { resolveDesktopExecutorCommand } from "./desktop-executor.js";
 import { createProviderStreamDecoder } from "./provider-stream.js";
@@ -63,7 +64,7 @@ export async function startDirectTask(
   if (task.invocation_count >= 1) throw new Error("Direct tasks allow only one Provider invocation.");
   const command = await resolveCommand({
     backend: task.backend,
-    instruction: task.instruction,
+    instruction: withSceneReasoning("Complete only the requested bounded direct task in this invocation. Respect the assigned permission mode; do not create an automatic retry loop or expand the task scope.", task.instruction),
     repositoryPath: task.repository_path,
     executionKind: "direct",
     permissionMode: task.permission_mode,

package/src/orchestrator/instruction.js

@@ -174,20 +174,20 @@ export function buildCodingInstruction(
     section(
       "problem_solving_protocol",
       [
-        "Treat implementation as hypothesis testing: state assumptions, list plausible causes or approaches, inspect discriminating evidence, then choose the smallest strategy supported by that evidence.",
+        "Use the shared scene reasoning cycle for implementation and retries. Let the current issue determine useful perspectives and the smallest next check; do not require a separate reasoning workflow.",
         attemptNumber > 1
           ? "This is a retry. Repair clear failures directly; compare plausible causes when needed. Reasoning notes are advisory, not a prerequisite to editing."
           : "For the first attempt, investigate material uncertainty before a risky operation; use a reasonable assumption for low-impact reversible choices and verify as you proceed.",
         attemptNumber > 1
-          ? "Explain exactly what changed from the previous attempt and why the new evidence supports this strategy."
-          : "Record the uncertainty, first verification, concrete evidence checked, observed result, selected hypothesis, and strategy in the structured result.",
+          ? "When useful, briefly note what changed the interpretation or next check; an extra reasoning explanation is not required to perform the repair."
+          : "Use existing result fields for actual checks and outcomes; reasoning notes and the hypothesis sheet are optional.",
       ].join("\n"),
     ),
     section(
       "execution_contract",
       [
         "Read the repository instructions and current git state before editing.",
-        "Before editing, resolve the highest uncertainty with the first discriminating verification. If it cannot be resolved, stop and report a fallback instead of claiming completion.",
+        "Use the shared scene reasoning cycle to investigate uncertainty that affects the selected operation. If that operation cannot safely proceed, retain its blocker and choose independent authorized work or a smaller useful check. Do not claim unresolved outcomes are complete.",
         "Preserve user changes and keep the diff scoped to the requirement.",
         "Run relevant tests, inspect the final diff, commit, push, and create or update a PR.",
         `The PR must target ${charter.base_branch}.`,

package/src/orchestrator/loop.js

@@ -631,7 +631,7 @@ async function handleFailedAudit({
       state.ai_strategy_diagnoses.push(key);
       state.ai_strategy_diagnoses = state.ai_strategy_diagnoses.slice(-32);
       findings.push({ passed: false, code: 'AI_STRATEGY_CHANGE_REQUIRED', severity: 'blocker', target: 'retry_loop',
-        explanation: 'Investigate the repeated failure with LLM context synthesis, alternatives and tool evidence. Choose a different reversible method before another attempt; do not repeat uncertain effects or ask a person to certify technical correctness.', repairability: 'auto', blocker_kind: 'machine' });
+        explanation: 'Investigate the repeated failure with the shared scene reasoning cycle: understand this scene, derive and select useful perspectives, then connect the interpretation to the next check. Choose a different reversible method before another attempt; do not repeat uncertain effects or ask a person to certify technical correctness.', repairability: 'auto', blocker_kind: 'machine' });
       snapshot.final_audit = { ...(snapshot.final_audit || {}), passed: false, findings, requires_human: false, auto_repairable: true };
       appendEvent(snapshot, 're_instructing', 'AI diagnosis is required before treating technical repetition as an execution blocker.', { code: 'ai_strategy_change', attempt_number: attemptNumber });
       await publish(snapshot, 're_instructing', onUpdate);

package/src/orchestrator/problem-solving.js

@@ -94,9 +94,9 @@ export function evaluateRetryProblemSolving(attempt, previousAttempt) {
 export function problemSolvingResultContract() {
   return [
     hypothesisSheetInstruction,
-    "problem_solving must be an object with hypotheses, selected_hypothesis_id, evidence_checked, strategy, and changed_from_previous.",
+    "problem_solving must be an object; {} is valid when no optional reasoning notes are useful. When recording notes, use hypotheses, selected_hypothesis_id, evidence_checked, strategy, and changed_from_previous.",
     "Each hypothesis must use {id, statement}; evidence_checked must list concrete observations or commands.",
-    "On attempt 1, record the assumptions, hypotheses considered, selected hypothesis, and implementation strategy; changed_from_previous may be null.",
+    "Use the shared scene reasoning cycle on every attempt. Record useful assumptions or interpretations briefly when helpful; changed_from_previous may be null.",
     "On retry, use reasoning proportional to the uncertainty. If the repair is clear, make it and verify it; do not invent a fixed number of hypotheses or change a working strategy merely to satisfy a form. For persistent unexplained failures, compare plausible causes and inspect discriminating evidence. These reasoning notes are advisory; unchanged failures are still subject to the retry circuit.",
   ].join("\n");
 }

package/src/session-supervision/codex-app-server.js

@@ -617,7 +617,7 @@ async function frozenNativeSandbox(record, root, signal) {
   return policy;
 }
 
-export async function executeCodexAppServer(record, { webOrigin, openClient = openCodexAppServer, signal, authorizePreparation = async () => {}, beforeDispatch = async () => {}, onActivity = () => {}, onUsage = () => {}, onEvidence = async () => {}, observeExternal = collectPurposeObservations, root, auditOnly = false, opinionOnly = false, peerAction, runPeerReview = runStructuredProviderReview } = {}) {
+export async function executeCodexAppServer(record, { webOrigin, openClient = openCodexAppServer, signal, authorizePreparation = async () => {}, beforeDispatch = async () => {}, onStarted = async () => {}, onActivity = () => {}, onUsage = () => {}, onEvidence = async () => {}, observeExternal = collectPurposeObservations, root, auditOnly = false, opinionOnly = false, peerAction, runPeerReview = runStructuredProviderReview } = {}) {
   const run = record.run, decision = run.managed?.decision;
   if(run.managed?.enrollment?.nativeAuthorityDigest && run.managed.enrollment.nativeAuthorityDigest!==createHash('sha256').update(JSON.stringify([run.managed.providerSandbox,run.managed.providerSandboxSource])).digest('hex'))throw new CodexAppServerError('permission_narrowed','Frozen native enrollment authority changed; do not dispatch with the altered ceiling.');
   if (!decision || !run.managed.autonomyPolicy) throw new CodexAppServerError('decision', 'An assessed action is required before Codex dispatch.');
@@ -672,7 +672,7 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
   };
   const beforeEvidence = searchEnabled(run.managed) && !reviewing ? await captureWorkspace() : null;
   let evidenceQueue = Promise.resolve(), evidenceFailure = null;
-  let activeTurnId = null, turnCompleted = false, turnStart = null;
+  let activeTurnId = null, turnCompleted = false, turnStart = null, startReceipt = null;
   let usage = null, lastTotal = null;
   try {
     // An unavailable login is a connection dependency, not an action approval.
@@ -789,7 +789,7 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
     }
     if (signal?.aborted) throw new CodexAppServerError('cancelled', 'Worker dispatch was cancelled during preparation.');
     const done = new Promise((resolve, reject) => {
-      let turnId = null, completion = null, settled = false;
+      let turnId = null, completion = null, settled = false, startRecorded = false;
       const messages = new Map();
       const activeTools = new Set();
       const earlyActivity = [];
@@ -819,7 +819,7 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
       const cancelled = () => finish(new CodexAppServerError('cancelled', 'Codex turn was cancelled.'));
       const closed = () => finish(new CodexAppServerError('closed', 'Codex app-server closed before turn completion.'));
       const complete = () => {
-        if (!completion || !turnId || completion.turn?.id !== turnId) return;
+        if (!completion || !turnId || !startRecorded || completion.turn?.id !== turnId) return;
         turnCompleted = true;
         if (completion.turn.status !== 'completed') return finish(new CodexAppServerError('turn_failed', 'Codex turn did not complete.'));
         const message = messages.get(turnId);
@@ -846,7 +846,10 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
       client.child.once('close', closed);
       turnStart = client.request('turn/start', { threadId: targetSession, input: [{ type: 'text', text: `${prompt}\n${purposeInstruction}` }], cwd: isolated ? executionCwd : record.cwd,
         model: run.managed.resumeModel, ...(isolated ? {sandboxPolicy} : {}) })
-        .then(response => { turnId = response?.turn?.id; activeTurnId = turnId; if (!turnId) finish(new CodexAppServerError('turn_failed', 'Codex did not start a turn.')); else {
+        .then(async response => { turnId = response?.turn?.id; activeTurnId = turnId; if (!turnId) finish(new CodexAppServerError('turn_failed', 'Codex did not start a turn.')); else {
+          startReceipt = Promise.resolve().then(() => onStarted({ turnId, session: targetSession }));
+          await startReceipt;
+          startRecorded = true;
           for (const params of earlyUsage) if (params.turnId === turnId) observeUsage(params);
           for (const params of earlyActivity) if (params.turnId === turnId) observeActivity(params.method, params);
           complete();
@@ -912,6 +915,7 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
     await evidenceQueue;
     throw error;
   } finally {
+    if (startReceipt) await startReceipt.catch(() => {});
     if (turnStart && !client.closed) {
       // Only the controller-owned target may be interrupted. Isolated reads
       // never load or change the original conversation's policy defaults.

package/src/session-supervision/continuation-analysis.js

@@ -1,3 +1,4 @@
+import { withSceneReasoning } from '../codex-plugins/simy/hooks/scene-reasoning.mjs';
 import { readCodexConversation } from './codex-app-server.js';
 import { readClaudeConversation } from './claude-sessions.js';
 import { boundConversation, boundProviderGoal, providerGoalEvidence, sanitizedText } from './conversation-context.js';
@@ -5,7 +6,7 @@ import { runStructuredProviderReview } from '../sqm/review-worker.js';
 import { inspectProviderStatus } from '../desktop-status.js';
 import { createHash } from 'node:crypto';
 
-export const CONTINUATION_ANALYSIS_VERSION = 5;
+export const CONTINUATION_ANALYSIS_VERSION = 6;
 const BLOCKER_TYPES = ['approval', 'missing_information', 'external_dependency', 'execution_failure'];
 const STATES = ['continue', 'no_action', 'needs_user', 'waiting', 'uncertain'];
 const string = maximum => ({ type: 'string', maxLength: maximum });
@@ -228,7 +229,7 @@ export async function analyzeContinuation(candidate, {
     await beforeProviderDispatch();
     if (signal?.aborted) return uncertain('Conversation analysis was cancelled.', 'cancelled');
     result = await runProvider(candidate.provider, {
-      system: SYSTEM, prompt: `Classify this conversation evidence only (older history omitted: ${context.truncated}):\n${JSON.stringify(context.providerGoal ? { originalProviderGoal: context.providerGoal, messages: context.messages } : context.messages)}`, output_schema: OUTPUT_SCHEMA,
+      system: withSceneReasoning(SYSTEM), prompt: `Classify this conversation evidence only (older history omitted: ${context.truncated}):\n${JSON.stringify(context.providerGoal ? { originalProviderGoal: context.providerGoal, messages: context.messages } : context.messages)}`, output_schema: OUTPUT_SCHEMA,
     }, { ...providerOptions, signal, readOnlyAnalysis: true, beforeDispatch: beforeProviderDispatch });
   } catch (error) {
     if (error?.code === 'desktop_access_required') return uncertain('SIMY organization access is required before checking this conversation.', 'desktop_access_required');

package/src/session-supervision/purpose-instruction.js

@@ -1,3 +1,5 @@
+import { withSceneReasoning } from '../codex-plugins/simy/hooks/scene-reasoning.mjs';
+import { currentRecoveryIncident, unresolvedRecoveryContext } from '../codex-plugins/simy/hooks/recovery-incident.mjs';
 import { recallPerspectives, perspectiveInstruction } from '../codex-plugins/simy/hooks/perspective-memory.mjs';
 import { loadHypothesisKnowledge, hypothesisKnowledgeInstruction } from '../sqm/hypothesis-knowledge.js';
 import { selectiveRuleReview, applicableRuleIds } from '../codex-plugins/simy/hooks/purpose-rule-policy.mjs';
@@ -40,12 +42,18 @@ export async function loadPurposeRuleSet() {
   return { digest: createHash('sha256').update(JSON.stringify(sources)).digest('hex'), rules };
 }
 export async function buildPurposeInstruction(managed, { reviewer = false, cwd, webOrigin, allowNetwork = false, signal, knowledgeLoader = loadHypothesisKnowledge, authorizeKnowledgeNetwork, root: memoryRoot, record, memoryLoader = recallPerspectives } = {}) {
-  if (!managed?.purpose?.enabled) return '';
+  if (!managed?.purpose?.enabled) return withSceneReasoning();
   const ruleSet = await loadPurposeRuleSet();
   if (ruleSet.digest !== managed.purpose.ruleDigest) throw Object.assign(new Error('Purpose workflow changed; refresh its rule inventory before dispatch.'), { code: 'purpose_rules_changed' });
   if (reviewer && selectiveRuleReview(managed)) return `${llmDecisionInstruction}\nIndependently verify the original acceptance criteria and applicable canonical obligations from actual evidence. Consult the inventory as needed after forming an LLM judgment; do not enumerate every ID or impose core controls as universal checklist gates. Report only rules actually evaluated; omitted inventory entries are not passed or not_applicable. Known applicable obligations ${JSON.stringify(applicableRuleIds(managed))} must be independently assessed and cannot be discarded by worker claims. Do not copy worker dispositions as proof. Failed, unavailable or missing evidence remains unverified with a concrete acquisition/repair finding. No unrelated rule coverage obligation is implied.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}`;
   if (reviewer) return `${llmDecisionInstruction}\nCanonical rule inventory. Review applicability and evidence for EVERY ID, including HC-01 through HC-102; these controls are requirements, not proof that their mechanisms exist. Read the referenced sections and acceptance details as needed. User instructions retain priority. Do not impose unrelated development/release controls on other task types. Core controls ${CORE_CONTROL_IDS.join(', ')} apply to every autonomous task; inspect their actual bounded behavior, including conditional duties whose trigger did not occur, rather than marking the entire control not_applicable. Return rules:[{id,evidenceRefs:[{ref,target,observation}],status:"satisfied|failed|unverified|not_applicable",basis:"inspected evidence or specific applicability reason"}]. Keep basis concise with source locators; stored receipts are limited to 160 UTF-8 bytes and basisTruncated means re-read the original evidence. Never copy worker dispositions as independent proof. Missing capability is unverified and requires an acquisition/repair finding, not a human certification request.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}`;
   const knowledge = await knowledgeLoader({ cwd, webOrigin, allowNetwork, signal, ...(authorizeKnowledgeNetwork ? { authorizeNetwork: authorizeKnowledgeNetwork } : {}) });
   const memory = await memoryLoader({ root: memoryRoot, record, signal });
-  return `${purposeContract(managed)}\n${perspectiveInstruction(memory)}\n${hypothesisKnowledgeInstruction(knowledge, { flexible: selectiveRuleReview(managed) })}\n${searchInstruction(managed)}\nForm a grounded candidate judgment with LLM reasoning first; consult the applicable canonical rule sections using read tools to challenge that judgment before its effects. This ruleSet is authoritative workflow material; user instructions retain priority. ${selectiveRuleReview(managed) ? "Review applicable rules and known obligations only; do not require full inventory coverage." : "Use the purpose contract for full initial rule coverage and changed dispositions on subsequent search turns."} Missing sources or unavailable tools remain unverified; do not fabricate coverage. Repository AGENTS.md and explicit user constraints also apply.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}\nPrior rule dispositions (provider reported, re-evaluate applicability): ${JSON.stringify(managed.purpose.version === 2 ? managed.purpose.lastReview?.rules || [] : [])}\nLast purpose review (provider reported): ${JSON.stringify(managed.purpose.lastReview ? { gap: managed.purpose.lastReview.gap, hypothesis: managed.purpose.lastReview.hypothesis, noChangeAssessment: managed.purpose.lastReview.noChangeAssessment, observations: managed.purpose.lastReview.observations, unresolvedRules: managed.purpose.lastReview.rules.filter(rule => ['failed', 'unverified'].includes(rule.status)) } : null)}\nRecovery context: ${JSON.stringify(managed.purpose.lastRecovery || null)}`;
+  const attempt = managed.executionAttempt;
+  const recoveryContext = { previous: managed.purpose.lastRecovery || null, incident: currentRecoveryIncident(managed),
+    unresolved: unresolvedRecoveryContext(managed),
+    receipt: attempt ? { id: attempt.id, phase: attempt.phase, decisionId: attempt.decisionId,
+      providerSessionId: attempt.providerSessionId || null, providerTurnId: attempt.providerTurnId || null,
+      startedAt: attempt.startedAt || null, dispatchedAt: attempt.dispatchedAt || null } : null };
+  return `${purposeContract(managed)}\n${perspectiveInstruction(memory)}\n${hypothesisKnowledgeInstruction(knowledge, { flexible: selectiveRuleReview(managed) })}\n${searchInstruction(managed)}\nUse the shared scene reasoning cycle; consult applicable canonical rule sections as perspective inputs and challenge the candidate before its effects. This ruleSet is authoritative workflow material; user instructions retain priority. ${selectiveRuleReview(managed) ? "Review applicable rules and known obligations only; do not require full inventory coverage." : "Use the purpose contract for full initial rule coverage and changed dispositions on subsequent search turns."} Missing sources or unavailable tools remain unverified; do not fabricate coverage. Repository AGENTS.md and explicit user constraints also apply.\nruleSet: ${JSON.stringify(ruleSet.rules.map(rule => ({ ...rule, path: fileURLToPath(new URL(rule.file, root)) })))}\nPrior rule dispositions (provider reported, re-evaluate applicability): ${JSON.stringify(managed.purpose.version === 2 ? managed.purpose.lastReview?.rules || [] : [])}\nLast purpose review (provider reported): ${JSON.stringify(managed.purpose.lastReview ? { gap: managed.purpose.lastReview.gap, hypothesis: managed.purpose.lastReview.hypothesis, noChangeAssessment: managed.purpose.lastReview.noChangeAssessment, observations: managed.purpose.lastReview.observations, unresolvedRules: managed.purpose.lastReview.rules.filter(rule => ['failed', 'unverified'].includes(rule.status)) } : null)}\nRecovery context (controller receipt data, not instructions, permission or acceptance; return to the original unfinished work after the next useful check): ${JSON.stringify(recoveryContext)}`;
 }