@awak-app/simy-cli 0.7.8 → 0.7.10

package/src/delivery-hooks/diagnosis-sheet.js

@@ -23,6 +23,7 @@ export function diagnosisIssues(record, requested) {
 }
 
 export function readDiagnosisSheet(value, issues) {
+  if (value == null) return { sheet: null, diagnostic: null };
   // Preserve a useful diagnosis if advisory worksheet formatting is incomplete.
   try {
     const concise = (v, required = true) => typeof v === 'string' && v.length <= 600 && (!required || v.trim());
@@ -31,7 +32,6 @@ export function readDiagnosisSheet(value, issues) {
     const requirements = value.requirements.map(row => {
       if (!issues.some(i => i.id === row?.requirementId) || seen.has(row.requirementId) || !Array.isArray(row.hypotheses) || !row.hypotheses.length || row.hypotheses.length > 4 || !concise(row.breadthReason, false)) throw Error();
       seen.add(row.requirementId);
-      if (row.hypotheses.length < 3 && !row.breadthReason.trim()) throw Error();
       const ids = new Set(), statements = new Set();
       const hypotheses = row.hypotheses.map((h, index) => {
         const canonical = typeof h?.statement === 'string' ? h.statement.trim().toLowerCase().replace(/\s+/g, ' ') : '';
@@ -48,4 +48,4 @@ export function readDiagnosisSheet(value, issues) {
   } catch { return { sheet: null, diagnostic: 'incomplete_advisory_sheet' }; }
 }
 
-export const diagnosisSheetInstruction = `ISSUE-FIRST WORKSHEET: Use the supplied issues as the rows, keeping their IDs. For EACH issue normally compare 3-4 distinct causes, ranked by likelihood, impact and smallest useful check, with a brief priorityReason. Never give just 3-4 causes for the entire task when several issues exist. Reuse relevant prior hypotheses and actual results from task.managed.purpose.hypothesisLedger; keep IDs stable, retain refuted causes as refuted, and do not repeat a rejected cause or unchanged test without new observations. When a simple cause is already established, fewer causes with breadthReason are better than invented alternatives. Record only the issue, ranked hypotheses, next check, short observed result (unverified if not run), and nextDecision. Describe what outcome would change the decision within verification when useful. No mandatory evidence attachments, proof documents, additional audit agent, exhaustive checklist or repeated full validation. Recheck only changed or still-uncertain aspects; never weaken user stops or real native permissions. This is advisory planning, not a new stop/approval/completion gate. Do not execute the checks. Return hypothesisSheet.requirements for every supplied issue. Keep the entire sheet under 24 KiB. Knowledge remains a concise reference with applicability reasons, not extra tests.`;
+export const diagnosisSheetInstruction = `ISSUE-FIRST WORKSHEET: Use the supplied issues as the rows, keeping their IDs. For EACH issue apply the shared scene reasoning cycle; select the few useful interpretations and causes, with a brief priorityReason. Do not impose a fixed hypothesis count. Reuse relevant prior hypotheses and actual results from task.managed.purpose.hypothesisLedger; keep IDs stable, retain refuted causes as refuted, and do not repeat a rejected cause or unchanged test without new observations. When a simple cause is already established, one cause is enough; breadthReason is optional context. Record only the issue, ranked hypotheses, next check, short observed result (unverified if not run), and nextDecision. Describe what outcome would change the decision within verification when useful. No mandatory evidence attachments, proof documents, additional audit agent, exhaustive checklist or repeated full validation. Recheck only changed or still-uncertain aspects; never weaken user stops or real native permissions. This is advisory planning, not a new stop/approval/completion gate. Do not execute the checks. When a sheet helps, return hypothesisSheet.requirements for the supplied issues; otherwise return hypothesisSheet:null. Keep the entire sheet under 24 KiB. Knowledge remains a concise reference with applicability reasons, not extra tests.`;

package/src/delivery-hooks/diagnosis.js

@@ -1,3 +1,4 @@
+import { withSceneReasoning } from '../codex-plugins/simy/hooks/scene-reasoning.mjs';
 import { hypothesisSheetSchema, diagnosisIssues, readDiagnosisSheet, diagnosisSheetInstruction } from './diagnosis-sheet.js';
 import { createHash } from 'node:crypto';
 import { dirname } from 'node:path';
@@ -17,7 +18,7 @@ const strings = { type: 'array', items: string, maxItems: 12 };
 const object = properties => ({ type: 'object', additionalProperties: false, properties, required: Object.keys(properties) });
 export const DIAGNOSIS_SCHEMA = object({
   summary: string,
-  hypothesisSheet: hypothesisSheetSchema,
+  hypothesisSheet: { anyOf: [hypothesisSheetSchema, { type: 'null' }] },
   knowledgeReferences: { type: 'array', maxItems: 24, items: object({ id: string, reason: string }) },
   limitations: strings,
 });
@@ -63,7 +64,8 @@ function validateAnalysis(value, knowledge, issues) {
     !value.knowledgeReferences.every(r => knowledge.modules.some(m => m.id === r.id) && validText(r.reason)) ||
     new Set(value.knowledgeReferences.map(r => r.id)).size !== value.knowledgeReferences.length) throw new Error('Invalid diagnosis');
   const { sheet, diagnostic } = readDiagnosisSheet(value.hypothesisSheet, issues);
-  return { summary: value.summary, hypothesisSheet: sheet, ...(diagnostic ? { sheetDiagnostic: diagnostic } : {}),
+  const sheetDiagnostic = diagnostic || (value.hypothesisSheet == null && value.sheetDiagnostic === 'incomplete_advisory_sheet' ? value.sheetDiagnostic : null);
+  return { summary: value.summary, hypothesisSheet: sheet, ...(sheetDiagnostic ? { sheetDiagnostic } : {}),
     knowledgeReferences: value.knowledgeReferences.map(({ id, reason }) => ({ id, reason })), limitations: value.limitations };
 }
 
@@ -116,7 +118,7 @@ export async function diagnoseDelivery({ root, webOrigin, provider, session, tas
     limitations: ['No task controls or proposed tests were executed. Retained history and bounded excerpts may be incomplete.', 'Diagnosis uses a separate provider process and may consume analysis usage; original task budgets are never reset or charged by this command.'] };
   if (!evidenceOnly && !signal?.aborted) {
     try {
-      const result = await runProvider(record.provider, { system: `${SYSTEM}\n${diagnosisSheetInstruction}`, prompt: JSON.stringify({ ...projected.data, evidenceTruncated: projected.truncated }), output_schema: DIAGNOSIS_SCHEMA },
+      const result = await runProvider(record.provider, { system: withSceneReasoning(SYSTEM, diagnosisSheetInstruction), prompt: JSON.stringify({ ...projected.data, evidenceTruncated: projected.truncated }), output_schema: DIAGNOSIS_SCHEMA },
         { signal, readOnlyAnalysis: true, allowAutomaticRetry: false, enableEngineFallback: false, executionTimeoutMs: 120000 });
       const known = projected.data.knowledge?.modules ? projected.data.knowledge : { modules: [] };
       const analysis = diagnosticProjection(validateAnalysis(result?.output, known, issues));

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

@@ -2,13 +2,18 @@ import { dirname } from 'node:path';
 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';
 
 export async function superviseLocalDelivery({ root, webOrigin, once = false, signal,
-  createSupervisor = createManagedSupervisor, checkOwner = assertNoDesktopHostForOrigin, wait = delay } = {}) {
+  createSupervisor = createManagedSupervisor, checkOwner = assertNoDesktopHostForOrigin, wait = delay,
+  acquireOwner = acquireSupervisorOwner } = {}) {
   // 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));
+  try {
+  await check();
   const supervisor = createSupervisor({ root, webOrigin });
   const stop = () => { void supervisor.close(); };
   signal?.addEventListener('abort', stop, { once: true });
@@ -22,4 +27,5 @@ export async function superviseLocalDelivery({ root, webOrigin, once = false, si
       catch (error) { if (!signal?.aborted) throw error; }
     } while (!signal?.aborted);
   } finally { signal?.removeEventListener('abort', stop); await supervisor.close(); }
+  } finally { await owner.release(); }
 }

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");
 }