@awak-app/simy-cli 0.7.9 → 0.7.11

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/desktop-host.js

@@ -1,3 +1,5 @@
+import { sessionWorkState, compareSessionWork, reconcileFamilyCompletion, expireSessionWorkState } from './session-supervision/work-state.js';
+import { createPullRequestObserver } from './session-supervision/pull-requests.js';
 import { sessionDecisionPresentation } from './session-supervision/decision-presentation.js';
 import { PROVIDER_LINKS, readProviderLinks, writeProviderLink, requireProviderLink } from "./provider-links.js";
 import { randomUUID } from "node:crypto";
@@ -11,7 +13,7 @@ import { stopDesktopWorkForUpdate } from './desktop-update-stop.js';
 import { desktopAccessReady, desktopActionAllowed, requireDesktopAccess, validDesktopAccessPath } from './desktop-access.js';
 import { createActionDeadlineService } from './session-supervision/action-deadline.js';
 import { deliveryHookStatus, openHookSetup } from "./delivery-hooks/desktop.js";
-import { controlDelivery, verifyDelivery, createRecordReader, updateRecord, TERMINAL } from "./codex-plugins/simy/hooks/delivery-loop.mjs";
+import { controlDelivery, verifyDelivery, createRecordReader, updateRecord, recordProviderArchive, TERMINAL } from "./codex-plugins/simy/hooks/delivery-loop.mjs";
 import { createManagedSupervisor } from "./delivery-hooks/supervisor.js";
 import { createActionAssociationHost } from "./session-supervision/action-association-host.js";
 import { createStopNotifier } from "./session-supervision/stop-notifications.js";
@@ -101,7 +103,7 @@ function desktopActionError(action, error) {
   if (action === "session_deadline_decide") return error?.code === "conflict"
     ? "Deadline changed; refresh before deciding." : "The deadline is unavailable. Refresh this conversation before deciding.";
   if (typeof action === "string" && action.startsWith("session_")) {
-    return action.startsWith("session_action_") ? associationActionError(error) : sessionActionError(error);
+    return action.startsWith("session_action_") ? associationActionError(error) : sessionActionError(error, action);
   }
   if (["organization_select", "organization_cancel", "organizations_refresh"].includes(action)) {
     return error?.code === "desktop_organization_busy"
@@ -411,6 +413,7 @@ export async function startDesktopHost({ input = process.stdin, output = process
     });
     unfinishedDesktopWork = false;
   })();
+  const observePullRequests = dependencies.observePullRequests || createPullRequestObserver();
   const refreshSessions = (force = false) => {
     if (discoveryStopped && !closed && !relay) return sessionStatus;
     if (closed || relay || !desktopAccessReady(currentAccess)) return { sessions: [], providers: {}, refreshedAt: null };
@@ -428,7 +431,11 @@ export async function startDesktopHost({ input = process.stdin, output = process
             sessionRefreshAgain = desktopAccessReady(latestAccess);
             return;
           }
-          const sessions = linkedSessions(value.sessions);
+          const sessions = await observePullRequests(linkedSessions(value.sessions), { signal: controller.signal });
+          const afterObservation = await accessSnapshot();
+          if (controller.signal.aborted || !desktopAccessReady(afterObservation) || accessScope(afterObservation) !== requestedScope) {
+            await analysisManager.update([]); sessionRefreshAgain = desktopAccessReady(afterObservation); return;
+          }
           await analysisManager.update(analysisSessions(sessions));
           if (controller.signal.aborted) return;
           sessionStatus = { ...value, sessions, initialLoading: false }; sessionRefreshedAt = Date.now(); })
@@ -626,7 +633,7 @@ export async function startDesktopHost({ input = process.stdin, output = process
       // Cached enrichment must follow the current connection preference even
       // while a full projection is waiting on records or remote metadata.
       status.deliveryHooks.runs = linkedSessions(status.deliveryHooks.runs || []);
-      status.sessionSupervision.sessions = linkedSessions(status.sessionSupervision.sessions || []);
+      status.sessionSupervision.sessions = linkedSessions(status.sessionSupervision.sessions || []).map(candidate => expireSessionWorkState(candidate)).sort(compareSessionWork);
       status.sessionSupervision.providers ||= {};
       for (const provider of PROVIDER_LINKS) {
         if (!providerLinks[provider].connected) status.sessionSupervision.providers[provider] = { discovery: 'disconnected', reason: null };
@@ -705,6 +712,7 @@ export async function startDesktopHost({ input = process.stdin, output = process
       automaticContinuation?.tick(discovery.sessions);
       const sessions = discovery.sessions.map(candidate => automaticContinuation.project(analysisManager.project(candidate)));
       await actionAssociations.decorateSessions?.(sessions, projection);
+      const stateRunsBySession = new Map((projection?.records || records).filter(record => record.run).map(record => [`${record.provider}:${record.session}`, record.run]));
       const runsBySession = new Map((status.deliveryHooks.runs || []).map(run => [`${run.provider}:${run.session}`, run]));
       for (const session of sessions) {
         const key = `${session.provider}:${session.session}`;
@@ -727,8 +735,9 @@ export async function startDesktopHost({ input = process.stdin, output = process
         const run = runsBySession.get(`${session.provider}:${session.session}`);
         if (run) run.actionDeadline = session.actionDeadline;
       }
-      status.sessionSupervision = { ...discovery, refreshing: Boolean(sessionRefresh), sessions: sessions.map(candidate => ({ ...candidate,
-        decisionRequest: sessionDecisionPresentation(candidate, runsBySession.get(`${candidate.provider}:${candidate.session}`)) })) };
+      status.sessionSupervision = { ...discovery, refreshing: Boolean(sessionRefresh), sessions: reconcileFamilyCompletion(sessions.map(candidate => ({ ...candidate,
+        decisionRequest: sessionDecisionPresentation(candidate, runsBySession.get(`${candidate.provider}:${candidate.session}`)),
+        workState: sessionWorkState(candidate, runsBySession.get(`${candidate.provider}:${candidate.session}`) || stateRunsBySession.get(`${candidate.provider}:${candidate.session}`), { provider: discovery.providers?.[candidate.provider] }) }))).sort(compareSessionWork) };
       const latestAccess = await accessSnapshot();
       if (JSON.stringify(await readProviderLinks(root)) !== requestedLinks ||
         !desktopAccessReady(latestAccess) || accessScope(latestAccess) !== requestedScope ||
@@ -1339,6 +1348,25 @@ export async function startDesktopHost({ input = process.stdin, output = process
           await authorizeWork(commandScope);
           const result = await deadlines.decide(context, { ...command, requestId: command.requestId || command.decisionId });
           if (result.status === 'conflict') throw Object.assign(new Error('Deadline changed; refresh before deciding.'), { code: 'conflict' });
+        } else if (action === "session_archive" || action === "session_restore") {
+          const candidate = await selectedSession(command, { preferObserved: true });
+          await authorizeWork(commandScope);
+          if (!['local', 'provider'].includes(command.scope)) throw new Error('Choose local or provider archive explicitly.');
+          const archived = action === 'session_archive';
+          if (command.scope === 'provider') {
+            if (command.provider !== 'codex') throw new Error('Archive or restore this conversation in Claude, then refresh SIMY.');
+            const client = await (dependencies.openCodexAppServer || openCodexAppServer)();
+            try { await client.request(archived ? 'thread/archive' : 'thread/unarchive', { threadId: command.session });
+              if (archived) await recordProviderArchive(deliveryRoot, command.provider, command.session, true, Date.now());
+            }
+            finally { await client.close(); }
+          } else {
+            await updateRecord(deliveryRoot, command.provider, command.session, previous => ({
+              ...(previous || { schemaVersion: 1, provider: command.provider, session: command.session, cwd: candidate.cwd, observedAt: Date.now() }),
+              listHidden: archived,
+            }));
+          }
+          refreshSessions(true);
         } else if (action === "session_track" || action === "session_untrack") {
           const candidate = await selectedSession(command);
           if (candidate.capabilities?.canMonitor !== true) throw new Error('Tracking is unavailable for this conversation.');
@@ -1439,7 +1467,7 @@ function associationActionError(error) {
   return 'The Action service is unavailable. Your conversation continues with its existing settings.';
 }
 
-function sessionActionError(error) {
+function sessionActionError(error, action) {
   if (error instanceof AutoContinueUnavailableError) return error.message.replace(/[\r\n\x00-\x1f]/g, ' ').slice(0, 600);
   const message = String(error?.message || "");
   if (/already has a Delivery Loop|budgets cannot be reset/i.test(message)) return "This conversation already has a task. Open its existing supervision instead.";
@@ -1447,6 +1475,7 @@ function sessionActionError(error) {
   if (/workspace changed|metadata.*unavailable|session.*changed/i.test(message)) return "The conversation identity or workspace changed. Refresh and select it again.";
   if (/objective|acceptance|autonomy policy|budget/i.test(message)) return message.replace(/[\r\n\x00-\x1f]/g, " ").slice(0, 240);
   if (/question changed|answer is empty|session understanding|context/i.test(message)) return message.replace(/[\r\n\x00-\x1f]/g, " ").slice(0, 240);
+  if (action === "session_answer") return "Answer acceptance is unconfirmed. Check the original conversation before sending again.";
   return "This conversation could not be enrolled. Refresh its provider status and try again.";
 }
 

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,