@awak-app/simy-cli 0.5.33 → 0.5.35

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

@@ -0,0 +1,290 @@
+import { spawn } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { inspectBackendExecutable } from '../backend-executable.js';
+import { assessedCheckpointContract, understandingCheckpointContract } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+
+const REQUEST_TIMEOUT = 15_000;
+const MAX_LINE = 256 * 1024;
+const SOURCE_KINDS = ['cli', 'vscode', 'exec', 'appServer', 'unknown'];
+
+export class CodexAppServerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'CodexAppServerError';
+    this.code = code;
+  }
+}
+
+export class CodexAppServerClient {
+  constructor(child) {
+    this.child = child;
+    this.nextId = 0;
+    this.pending = new Map();
+    this.listeners = new Set();
+    this.closed = false;
+    // Provider output can include private text. Hold only one bounded JSON-RPC
+    // line at a time, and discard overlong lines before parsing them.
+    let pending = Buffer.alloc(0), discard = false;
+    child.stdout.on('data', chunk => {
+      let offset = 0;
+      while (offset < chunk.length) {
+        const newline = chunk.indexOf(10, offset);
+        const end = newline < 0 ? chunk.length : newline;
+        const piece = chunk.subarray(offset, end);
+        if (!discard) {
+          if (pending.length + piece.length > MAX_LINE) { pending = Buffer.alloc(0); discard = true; }
+          else if (piece.length) pending = pending.length ? Buffer.concat([pending, piece]) : Buffer.from(piece);
+        }
+        if (newline >= 0) {
+          if (!discard && pending.length) this.consume(pending.toString('utf8'));
+          pending = Buffer.alloc(0); discard = false; offset = newline + 1;
+        } else offset = end;
+      }
+    });
+    child.on('error', error => this.fail(error));
+    child.on('close', () => this.fail(new CodexAppServerError('closed', 'Codex app-server closed.')));
+    // Diagnostics can contain private data. Drain, but never retain or expose them.
+    child.stderr?.resume();
+  }
+
+  consume(line) {
+    if (Buffer.byteLength(line) > MAX_LINE) return;
+    let message;
+    try { message = JSON.parse(line); } catch { return; }
+    if (typeof message.method === 'string') {
+      for (const listener of this.listeners) listener(message.method, message.params || {}, message.id);
+    } else if (message.id !== undefined) {
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) pending.reject(new CodexAppServerError(message.error.code, String(message.error.message || 'Codex app-server request failed.').slice(0, 300)));
+      else pending.resolve(message.result);
+    }
+  }
+
+  fail(error) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); }
+    this.pending.clear();
+  }
+
+  request(method, params = {}, timeout = REQUEST_TIMEOUT) {
+    if (this.closed) return Promise.reject(new CodexAppServerError('closed', 'Codex app-server closed.'));
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new CodexAppServerError('timeout', `${method} timed out.`)); }, timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      this.child.stdin.write(`${JSON.stringify({ id, method, params })}\n`, error => {
+        if (!error) return;
+        const pending = this.pending.get(id);
+        if (pending) { clearTimeout(pending.timer); this.pending.delete(id); reject(error); }
+      });
+    });
+  }
+
+  notify(method, params = {}) {
+    if (!this.closed) this.child.stdin.write(`${JSON.stringify({ method, params })}\n`);
+  }
+
+  onNotification(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+
+  async close() {
+    if (this.child.exitCode !== null) return;
+    this.child.stdin.end();
+    this.child.kill('SIGTERM');
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { this.child.kill('SIGKILL'); resolve(); }, 2_000);
+      this.child.once('close', () => { clearTimeout(timer); resolve(); });
+    });
+  }
+}
+
+export function supportsCodexWriterLock(version) {
+  const match = String(version || '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return false;
+  const parts = match.slice(1).map(Number);
+  return parts[0] > 0 || parts[1] > 158 || parts[1] === 158 && parts[2] >= 0;
+}
+
+export async function openCodexAppServer({ inspectExecutable = inspectBackendExecutable, spawnImpl = spawn, signal } = {}) {
+  if (signal?.aborted) throw new CodexAppServerError('cancelled', 'Codex app-server was cancelled.');
+  const inspection = await inspectExecutable('codex');
+  if (!inspection?.available || !inspection.executable) throw new CodexAppServerError('unavailable', 'Codex executable is unavailable.');
+  if (!supportsCodexWriterLock(inspection.installed_version)) throw new CodexAppServerError('unsupported', 'Codex version does not have a verified app-server writer lock.');
+  if (signal?.aborted) throw new CodexAppServerError('cancelled', 'Codex app-server was cancelled.');
+  // Keep the owned writer alive long enough to interrupt a cancelled turn and
+  // restore a temporary read-only override. The caller's signal is checked
+  // before spawn and by the turn watcher below.
+  const child = spawnImpl(inspection.executable, ['app-server', '--stdio'], { stdio: ['pipe', 'pipe', 'pipe'] });
+  const client = new CodexAppServerClient(child);
+  try {
+    await client.request('initialize', { clientInfo: { name: 'simy_session_supervision', title: 'SIMY Session Supervision', version: '1.0.0' } });
+    client.notify('initialized');
+    return client;
+  } catch (error) { await client.close(); throw error; }
+}
+
+export function codexThreadMetadata(thread) {
+  if (!thread || typeof thread.id !== 'string' || !/^[0-9a-f-]{36}$/i.test(thread.id) || typeof thread.cwd !== 'string' || !thread.cwd || thread.ephemeral) return null;
+  if (thread.parentThreadId) return null;
+  return {
+    provider: 'codex', session: thread.id, cwd: thread.cwd,
+    title: typeof thread.name === 'string' && thread.name.trim() ? thread.name.slice(0, 200) : '',
+    source: typeof thread.source === 'string' ? thread.source : thread.source?.type || 'unknown',
+    lastActivityAt: Number.isFinite(thread.updatedAt) ? thread.updatedAt * 1000 : null,
+    model: typeof thread.model === 'string' ? thread.model : null,
+    observation: { source: 'codex_app_server', observedAt: Date.now() },
+    availability: 'unknown',
+  };
+}
+
+export async function listCodexSessions({ client, maxPages = 40, pageSize = 5 } = {}) {
+  const sessions = [];
+  let cursor = null;
+  for (let page = 0; page < maxPages; page++) {
+    const response = await client.request('thread/list', { cursor, limit: pageSize, sourceKinds: SOURCE_KINDS, archived: false });
+    for (const thread of response?.data || []) {
+      const metadata = codexThreadMetadata(thread);
+      if (metadata) sessions.push(metadata);
+    }
+    cursor = response?.nextCursor || null;
+    if (!cursor) break;
+  }
+  return sessions;
+}
+
+export async function readCodexSession(client, session) {
+  const response = await client.request('thread/read', { threadId: session, includeTurns: false });
+  const metadata = codexThreadMetadata(response?.thread);
+  if (!metadata || metadata.session !== session) throw new CodexAppServerError('identity', 'Exact Codex session metadata is unavailable.');
+  return metadata;
+}
+
+export function isCodexWriterBusy(error) {
+  return error instanceof CodexAppServerError && error.code === -32600 && /already has an active writer/i.test(error.message);
+}
+
+export async function executeCodexAppServer(record, { openClient = openCodexAppServer, signal, beforeDispatch = async () => {} } = {}) {
+  const run = record.run, decision = run.managed?.decision;
+  if (!decision || !run.managed.autonomyPolicy) throw new CodexAppServerError('decision', 'An assessed action is required before Codex dispatch.');
+  if (!['read', 'local_edit', 'local_test'].includes(decision.action?.kind)) throw new CodexAppServerError('manual_provider_action', 'This action must be completed in the original provider conversation.');
+  const approved = run.managed.approvedAction;
+  const authorizedWait = decision.outcome === 'wait' && approved?.id === decision.id && !approved.dispatchedAt &&
+    JSON.stringify(approved.action) === JSON.stringify(decision.action);
+  if (decision.outcome === 'wait' && !authorizedWait) throw new CodexAppServerError('approval', 'The exact assessed action needs an unused scoped approval.');
+  const client = await openClient({ signal });
+  let originalSandbox = null, overrideStarted = false, activeTurnId = null, turnCompleted = false, turnStart = null;
+  let primaryError = null;
+  try {
+    const metadata = await readCodexSession(client, record.session);
+    if (await realpath(metadata.cwd) !== record.cwd || metadata.model !== run.managed.resumeModel) throw new CodexAppServerError('identity', 'Codex session workspace or model changed.');
+    let resumed;
+    try { resumed = await client.request('thread/resume', { threadId: record.session, excludeTurns: true }); }
+    catch (error) { if (isCodexWriterBusy(error)) return { code: -3, busy: true }; throw error; }
+    if (resumed?.thread?.id !== record.session || !resumed.cwd || await realpath(resumed.cwd) !== record.cwd || resumed.model !== run.managed.resumeModel) throw new CodexAppServerError('identity', 'Codex resumed a different session configuration.');
+    if (!canRestoreSandboxExactly(resumed.sandbox)) throw new CodexAppServerError('permission_restore', 'This Codex sandbox has custom rights that cannot be restored after a managed turn. Use the original conversation.');
+    if (signal?.aborted) throw new CodexAppServerError('cancelled', 'Codex dispatch was cancelled.');
+    await beforeDispatch(resumed.sandbox);
+    if (signal?.aborted) throw new CodexAppServerError('cancelled', 'Codex dispatch was cancelled.');
+    const context = { taskId: run.managed.taskId, objective: run.objective, acceptanceCriteria: run.managed.acceptanceCriteria,
+      decision, diagnosis: run.managed.plan?.diagnosis, remainingWork: run.managed.remainingWork, nextStep: run.nextStep,
+      enrolledScopes: run.managed.approvalScopes,
+      ...(authorizedWait ? { approvedAction: { approvalId: approved.id, action: approved.action, oneShot: true } } : {}),
+      budgets: { deadline: run.deadline, continuations: run.continuations, maxContinuations: run.maxContinuations, failures: run.failures, maxFailures: run.maxFailures } };
+    const approvalInstruction = authorizedWait ? `SIMY recorded a matching, one-shot scoped user approval ${approved.id} for this exact selected action. The decision outcome "wait" describes its pre-approval assessment; the approved action is authorized now. Execute it once, then report what actually happened. ` : '';
+    const prompt = run.managed.phase === 'understanding' ? `Understand the ORIGINAL user request in this exact Codex conversation. This first/clarifying turn is read-only and must not perform task work. Context: ${JSON.stringify({ ...context, priorUnderstanding: run.managed.sessionUnderstanding, userAnswer: run.managed.understandingAnswer })}\n${understandingCheckpointContract(decision)} Do not write SIMY state directly.` : `Continue this existing SIMY managed task in the exact Codex conversation. Context: ${JSON.stringify(context)}\n${approvalInstruction}Execute ONLY the selected decision action. Do not perform any action from the NEXT plan in this turn. For a next local action within the enrolled task use the exact scope "task"; do not relabel external, broad, or destructive work as local. Preserve provider permissions. End with one JSON checkpoint. ${assessedCheckpointContract(decision)} Do not write SIMY state directly.`;
+    const initialSandbox = run.managed.providerSandbox || resumed.sandbox;
+    const currentSandbox = resumed.sandbox;
+    originalSandbox = currentSandbox;
+    let sandboxPolicy = { type: 'readOnly', networkAccess: false };
+    if (decision.action.kind === 'local_edit') {
+      if (!canWriteWorkspace(initialSandbox, record.cwd) || !canWriteWorkspace(currentSandbox, record.cwd)) throw new CodexAppServerError('permission_narrowed', 'Current or enrolled Codex sandbox does not allow this local edit.');
+      sandboxPolicy = { type: 'workspaceWrite', writableRoots: [record.cwd], networkAccess: false,
+        excludeTmpdirEnvVar: true, excludeSlashTmp: true };
+    }
+    const done = new Promise((resolve, reject) => {
+      let turnId = null, completion = null, settled = false;
+      const messages = new Map();
+      const cleanup = () => { unsubscribe(); signal?.removeEventListener('abort', cancelled); client.child.removeListener('close', closed); };
+      const finish = (error, value) => { if (settled) return; settled = true; cleanup(); if (error) reject(error); else resolve(value); };
+      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;
+        turnCompleted = true;
+        if (completion.turn.status !== 'completed') return finish(new CodexAppServerError('turn_failed', 'Codex turn did not complete.'));
+        const message = messages.get(turnId);
+        if (!message || Buffer.byteLength(message) > 16 * 1024) return finish(new CodexAppServerError('checkpoint', 'Codex did not return a bounded checkpoint.'));
+        try { finish(null, JSON.parse(message)); } catch { finish(new CodexAppServerError('checkpoint', 'Codex final message was not a JSON checkpoint.')); }
+      };
+      const unsubscribe = client.onNotification((method, params, requestId) => {
+        if (requestId !== undefined && /requestApproval|requestPermissions|requestUserInput/i.test(method)) return finish(new CodexAppServerError('provider_approval', 'Codex requires provider approval or user input.'));
+        if (params.threadId !== record.session) return;
+        if (method === 'item/completed' && params.item?.type === 'agentMessage' && typeof params.item.text === 'string' && typeof params.turnId === 'string') messages.set(params.turnId, params.item.text);
+        if (method === 'turn/completed') { completion = params; if (params.turn?.id === turnId) turnCompleted = true; complete(); }
+      });
+      signal?.addEventListener('abort', cancelled, { once: true });
+      client.child.once('close', closed);
+      overrideStarted = true;
+      turnStart = client.request('turn/start', { threadId: record.session, input: [{ type: 'text', text: prompt }], cwd: record.cwd,
+        model: run.managed.resumeModel, sandboxPolicy })
+        .then(response => { turnId = response?.turn?.id; activeTurnId = turnId; if (!turnId) finish(new CodexAppServerError('turn_failed', 'Codex did not start a turn.')); else complete(); })
+        .catch(error => finish(error));
+    });
+    const checkpoint = await done;
+    return { code: 0, checkpoint };
+  } catch (error) {
+    primaryError = error;
+    throw error;
+  } finally {
+    if (overrideStarted && originalSandbox && !client.closed) {
+      // Interrupt a cancelled turn before releasing our writer. Codex may
+      // report its turn override while this writer is loaded, so verify the
+      // durable policy only after the writer is fully closed.
+      if (turnStart && !activeTurnId) await Promise.race([turnStart, new Promise(resolve => setTimeout(resolve, 2_000))]).catch(() => {});
+      if (!turnCompleted && activeTurnId) await client.request('turn/interrupt', { threadId: record.session, turnId: activeTurnId }, 2_000).catch(() => {});
+    }
+    await client.close();
+    if (overrideStarted && originalSandbox) {
+      let verified = false, verifier;
+      try {
+        verifier = await openClient({});
+        const durable = await verifier.request('thread/resume', { threadId: record.session, excludeTurns: true });
+        verified = durable?.thread?.id === record.session && durable.model === run.managed.resumeModel &&
+          durable.cwd && await realpath(durable.cwd) === record.cwd && sameSandboxRights(durable.sandbox, originalSandbox);
+      } catch { /* A busy or unavailable verifier leaves restoration unconfirmed. */ }
+      finally { await verifier?.close().catch(() => {}); }
+      if (!verified) {
+        if (primaryError) primaryError.restorationUnverified = true;
+        else throw new CodexAppServerError('permission_restore', 'Codex could not confirm the original provider sandbox after the managed turn. Inspect the original conversation.');
+      }
+    }
+  }
+}
+
+function canWriteWorkspace(sandbox, cwd) {
+  if (sandbox?.type === 'dangerFullAccess') return true;
+  if (sandbox?.type !== 'workspaceWrite' || !Array.isArray(sandbox.writableRoots)) return false;
+  // Codex workspaceWrite always includes its verified thread cwd. The roots
+  // array lists *additional* writable directories and is usually empty.
+  return Boolean(cwd);
+}
+
+function sameSandboxRights(left, right) {
+  if (left?.type !== right?.type) return false;
+  if (left.type === 'workspaceWrite') return left.networkAccess === right.networkAccess &&
+    JSON.stringify(left.writableRoots || []) === JSON.stringify(right.writableRoots || []) &&
+    Boolean(left.excludeTmpdirEnvVar) === Boolean(right.excludeTmpdirEnvVar) &&
+    Boolean(left.excludeSlashTmp) === Boolean(right.excludeSlashTmp);
+  return left.type === 'readOnly' ? left.networkAccess === right.networkAccess : left.type === 'dangerFullAccess';
+}
+
+function canRestoreSandboxExactly(sandbox) {
+  if (sandbox?.type === 'workspaceWrite') return sandbox.networkAccess === false &&
+    Array.isArray(sandbox.writableRoots) && sandbox.writableRoots.length === 0 &&
+    sandbox.excludeTmpdirEnvVar === false && sandbox.excludeSlashTmp === false;
+  if (sandbox?.type === 'readOnly') return sandbox.networkAccess === false;
+  return sandbox?.type === 'dangerFullAccess';
+}

package/src/session-supervision/index.js

@@ -0,0 +1,140 @@
+import { realpath } from 'node:fs/promises';
+import { controlDelivery, listRecords, processIdentity, startDelivery, updateRecord } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { listCodexSessions, openCodexAppServer, readCodexSession } from './codex-app-server.js';
+import { listClaudeSessions, readClaudeSession } from './claude-sessions.js';
+import { originalSessionTarget } from './original-session-target.js';
+
+function initialDiagnosisPlan(objective, contextBootstrap = false) {
+  const action = { kind: 'read', scope: 'task', summary: contextBootstrap ? 'Understand the original user request and current progress without changing files' : 'Inspect the selected conversation and acceptance evidence without changing files' };
+  return {
+    diagnosis: contextBootstrap ? 'Read the original conversation context to infer the user goal, constraints, progress, and what remains before choosing any work.' : `Establish the current state of this enrolled objective before choosing work: ${objective.slice(0, 500)}`,
+    alternatives: [{ id: 'inspect_current_state', action,
+      assessment: { risk: 'low', reversibility: 'reversible', externalEffect: 'none', blastRadius: 'single_file', uncertainty: 'low', inObjective: true, userChoice: false },
+      expectedVerification: contextBootstrap ? 'Return a grounded structured session understanding and a concrete assessed next action, or one focused question.' : 'Report the actual current state and a concrete next assessed action.', rollback: 'No changes to undo.' }],
+    selectedOptionId: 'inspect_current_state', recommendation: { optionId: 'inspect_current_state', reason: 'Read-only diagnosis establishes what remains before any change.' },
+  };
+}
+
+async function withClient(openClient, work) {
+  const client = await openClient();
+  try { return await work(client); } finally { await client.close(); }
+}
+
+async function liveClaudeHook(record, metadata, inspectProcess) {
+  if (!record || record.provider !== 'claude' || record.session !== metadata?.session ||
+      metadata.observation?.source !== 'claude_local_index' || !record.hookStartedAt ||
+      !(['SessionStart', 'Stop'].includes(record.lastEvent) || record.lastEvent === 'Notification' && record.lastNotificationType === 'idle_prompt') ||
+      !record.process?.identity) return false;
+  try {
+    if (record.cwd !== await realpath(metadata.cwd)) return false;
+    return await inspectProcess(record.process.pid) === record.process.identity;
+  } catch { return false; }
+}
+
+export async function discoverSessions({ root, openClient = openCodexAppServer, listClaude = listClaudeSessions,
+  inspectProcess = processIdentity, now = Date.now() } = {}) {
+  const records = await listRecords(root);
+  let discovered = [], codexError = null, claude = [], claudeError = null;
+  try { discovered = await withClient(openClient, client => listCodexSessions({ client })); }
+  catch (error) { codexError = error?.code === 'unavailable' ? 'Codex executable unavailable.' : error?.code === 'unsupported' ? 'This Codex version lacks a verified app-server writer lock; update before enrollment.' : 'Codex conversation discovery unavailable.'; }
+  try { claude = await listClaude(); } catch { claudeError = 'Claude conversation discovery unavailable.'; }
+  const byKey = new Map();
+  for (const item of [...discovered, ...claude]) byKey.set(`${item.provider}:${item.session}`, item);
+  for (const record of records) {
+    const key = `${record.provider}:${record.session}`;
+    if (!byKey.has(key) && (record.observedAt || record.admission || record.monitor || record.run)) byKey.set(key, {
+      provider: record.provider, session: record.session, cwd: record.cwd, title: '', source: record.admission?.source || 'hook',
+      lastActivityAt: record.observedAt || record.admission?.validatedAt || record.run?.updatedAt || null,
+      observation: { source: record.admission?.source || `${record.provider}_hook`, observedAt: record.observedAt || record.admission?.validatedAt || null },
+      availability: 'unknown', model: record.admission?.model || null,
+    });
+  }
+  const projected = (await Promise.all([...byKey.values()].map(async item => {
+    const record = records.find(r => r.provider === item.provider && r.session === item.session);
+    const run = record?.run;
+    const mode = run?.managed ? run.state === 'recovery_required' && run.recoveryCause === 'session_supervision' ? 'pending_takeover' : 'managed' : run ? 'standard_loop' : record?.monitor ? 'monitor' : 'unmanaged';
+    const supported = item.provider === 'codex' && item.observation.source === 'codex_app_server' && Boolean(item.model) && !codexError;
+    const liveHook = item.provider === 'claude' && !claudeError && await liveClaudeHook(record, item, inspectProcess);
+    return { provider: item.provider, session: item.session, cwd: item.cwd, title: item.title, source: item.source,
+      lastActivityAt: item.lastActivityAt, observation: item.observation, availability: item.availability,
+      binding: { mode, taskId: run?.managed?.taskId || null },
+      originalSessionTarget: originalSessionTarget(item.provider, item.session),
+      continuationMode: item.provider === 'claude' ? liveHook ? 'live_hook' : 'manual' : supported ? 'codex_app_server' : 'manual',
+      capabilities: { canMonitor: item.capabilities?.canMonitor ?? true, canEnroll: (supported || liveHook) && !run, canContinue: (supported || liveHook) && !run, canAutoContinue: supported || liveHook },
+      reason: item.provider === 'claude' ? liveHook ? 'Live SIMY hook can continue this Claude session at its next Stop boundary; cold CLI takeover is unavailable.' :
+        process.platform === 'win32' ? 'Claude live hook enrollment is unavailable on Windows because provider process identity cannot be verified; monitoring remains available.' :
+          'Claude enrollment needs a live matching SIMY SessionStart hook and provider process; cold CLI takeover is unavailable.' :
+        codexError || (!supported ? 'Exact model or provider metadata is unavailable.' : null),
+    };
+  }))).sort((a, b) => (b.lastActivityAt || 0) - (a.lastActivityAt || 0));
+  // Keep existing bindings visible during a truncated discovery or provider
+  // outage, even when newer unbound conversations fill the candidate window.
+  const bound = projected.filter(item => item.binding.mode !== 'unmanaged');
+  const sessions = [...bound, ...projected.filter(item => item.binding.mode === 'unmanaged').slice(0, Math.max(0, 200 - bound.length))];
+  return { sessions, providers: { codex: { discovery: codexError ? 'unavailable' : 'ready', reason: codexError }, claude: { discovery: claudeError ? 'unavailable' : 'local_index', reason: claudeError } }, refreshedAt: now };
+}
+
+export async function monitorSession({ root, provider, session, monitor = true, openClient = openCodexAppServer, readClaude = readClaudeSession, now = Date.now() }) {
+  if (!['codex', 'claude'].includes(provider)) throw new Error('Unsupported provider.');
+  if (!monitor) {
+    await updateRecord(root, provider, session, previous => {
+      if (!previous || previous.run) throw new Error('Stop the managed task before removing its monitor.');
+      previous.monitor = false;
+      return previous;
+    });
+    return null;
+  }
+  const metadata = provider === 'codex' ? await withClient(openClient, client => readCodexSession(client, session)) : await readClaude(session);
+  if (!metadata) throw new Error('Exact provider session metadata is unavailable.');
+  const cwd = await realpath(metadata.cwd);
+  await updateRecord(root, provider, session, previous => {
+    if (previous && previous.cwd !== cwd) throw new Error('Session workspace changed; refresh its metadata.');
+    return { ...(previous || { schemaVersion: 1, provider, session, cwd, run: null }), monitor,
+      admission: { source: metadata.observation.source, provider, session, cwd, model: metadata.model, validatedAt: now } };
+  });
+  return metadata;
+}
+
+export async function enrollSession({ root, provider, session, objective, acceptanceCriteria, contextBootstrap = false, autonomyPolicy = 'balanced',
+  maxMinutes = 30, maxContinuations = 6, maxFailures = 3, openClient = openCodexAppServer,
+  readClaude = readClaudeSession, inspectProcess = processIdentity, now = Date.now() }) {
+  if (!['codex', 'claude'].includes(provider)) throw new Error('This provider does not have a verified exact-session enrollment channel.');
+  if (typeof objective !== 'string' || !objective.trim() || objective.length > 4000) throw new Error('A concrete objective is required.');
+  if (!['autonomous', 'balanced', 'strict'].includes(autonomyPolicy)) throw new Error('Choose an autonomy policy.');
+  let metadata;
+  if (provider === 'claude') {
+    metadata = await readClaude(session);
+    const record = (await listRecords(root)).find(item => item.provider === provider && item.session === session);
+    if (!await liveClaudeHook(record, metadata, inspectProcess)) throw new Error('Claude needs a live matching SIMY SessionStart hook; cold CLI takeover is unavailable.');
+    if (record.run) throw new Error('This session already has a Delivery Loop.');
+    await monitorSession({ root, provider, session, monitor: true, readClaude: async () => metadata, now });
+    // A second check narrows the time between metadata admission and the
+    // original provider's next Stop boundary. Process exit still remains a
+    // manual recovery condition; SIMY never starts claude -r.
+    if (!await liveClaudeHook((await listRecords(root)).find(item => item.provider === provider && item.session === session), metadata, inspectProcess)) throw new Error('Claude provider process exited before enrollment.');
+  } else {
+    metadata = await monitorSession({ root, provider, session, monitor: true, openClient, now });
+    if (!metadata.model) throw new Error('Codex did not expose this conversation’s model; automatic continuation is unavailable.');
+  }
+  const cwd = await realpath(metadata.cwd);
+  const initialPlan = initialDiagnosisPlan(objective.trim(), contextBootstrap);
+  const admission = provider === 'codex' ? { source: 'codex_app_server', provider, session, cwd, model: metadata.model } : undefined;
+  const liveRecord = provider === 'claude' ? (await listRecords(root)).find(item => item.provider === provider && item.session === session) : null;
+  const run = await startDelivery({ root, provider, session, cwd, objective: objective.trim(), nextStep: 'Inspect current evidence and propose the next assessed action.',
+    maxMinutes, maxContinuations, maxFailures, now, admission, inspectProcess,
+    liveHookAdmission: liveRecord ? { hookStartedAt: liveRecord.hookStartedAt, pid: liveRecord.process.pid, identity: liveRecord.process.identity } : undefined,
+    managed: { acceptanceCriteria, contextBootstrap, autonomyPolicy, approvalScopes: ['task'], approvalPolicy: 'wait',
+      initialAction: initialPlan.alternatives[0].action, initialPlan, remainingWork: objective.trim(),
+      autoRecovery: provider === 'codex', resumeChannel: provider === 'codex' ? 'codex_app_server' : null,
+      resumeModel: metadata.model } });
+  return { provider, session, taskId: run.run.managed.taskId, state: run.run.state, deadline: run.run.deadline };
+}
+
+export async function continueSession(options) {
+  return enrollSession({ ...options, objective: 'Understand and continue the selected conversation’s current user request.',
+    acceptanceCriteria: [], contextBootstrap: true });
+}
+
+export async function answerSession({ root, provider, session, taskId, questionId, answer, now = Date.now() }) {
+  return controlDelivery({ root, provider, session, taskId, questionId, answer, action: 'session_answer', now });
+}

package/src/session-supervision/original-session-target.js

@@ -0,0 +1,20 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// Navigation never records an approval, resumes a provider, or acquires a
+// writer. The installed macOS Codex app registers codex: and itself generates
+// codex://threads/<id> conversation links. Other handlers are not verified.
+export function originalSessionTarget(provider, session, { platform = process.platform } = {}) {
+  if (provider === 'codex' && typeof session === 'string' && session.length === 36 && UUID.test(session)) return {
+    kind: 'url', url: `codex://threads/${encodeURIComponent(session)}`, label: 'Open in Codex',
+    verifiedOnPlatform: platform === 'darwin',
+    reason: platform === 'darwin' ? null : 'Codex link handling is not verified on this platform; use the exact session ID if opening fails.',
+  };
+  if (provider === 'claude') return {
+    kind: 'manual', url: null, label: 'Switch to Claude', verifiedOnPlatform: false,
+    reason: 'Return to the original Claude window. No verified direct link exists; opening a second CLI process could conflict with the live session.',
+  };
+  return {
+    kind: 'manual', url: null, label: 'Find original conversation', verifiedOnPlatform: false,
+    reason: 'No verified exact-conversation link is available for this session.',
+  };
+}

package/src/windows-update.js

@@ -3,6 +3,7 @@ import { mkdir, readFile, writeFile, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
 
 const exec = promisify(execFile);
 export const WINDOWS_MANIFEST_URL = "https://simy.one/downloads/simy-cli/windows/latest.json";
@@ -50,7 +51,32 @@ export async function downloadWindowsArtifact(item, destination, fetchImpl = fet
   if (size !== item.size || createHash('sha256').update(bytes).digest('hex') !== item.sha256) throw new Error('Update checksum mismatch');
   await writeFile(destination, bytes);
 }
-export async function applyWindowsUpdate({ installation, stateRoot, release, fetchImpl = fetch, verifyCandidate = verifyWindowsCandidate, extract = extractWindowsZip }) {
+async function pathExists(file) {
+  try { await stat(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+// Windows may briefly keep an extracted or health-probed executable open after
+// its process closes. Retry only that promotion rename, while the verified
+// source still exists and no other writer has created the immutable target.
+export async function promoteWindowsCandidate(source, target, {
+  renameImpl = rename,
+  platform = process.platform,
+  retryDelaysMs = [250, 500, 1000, 2000, 4000, 8000, 16000],
+  sleep = delay,
+} = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try { await renameImpl(source, target); return; }
+    catch (error) {
+      if (platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) ||
+          attempt >= retryDelaysMs.length || !(await pathExists(source)) || await pathExists(target)) throw error;
+      await sleep(retryDelaysMs[attempt]);
+      // A competing publisher may have created the immutable target while we
+      // waited. Do not let the next rename replace it.
+      if (!(await pathExists(source)) || await pathExists(target)) throw error;
+    }
+  }
+}
+export async function applyWindowsUpdate({ installation, stateRoot, release, fetchImpl = fetch, verifyCandidate = verifyWindowsCandidate, extract = extractWindowsZip, promote = promoteWindowsCandidate }) {
   validateWindowsRelease(release);
   const current = await selectedWindowsRoot(installation, stateRoot);
   const currentVersion = (await json(path.join(current, 'cli/package.json'))).version;
@@ -70,7 +96,7 @@ export async function applyWindowsUpdate({ installation, stateRoot, release, fet
     await mkdir(path.dirname(target), { recursive: true });
     // Immutable directory: never replace a running or previously staged version.
     try { await stat(target); throw new Error('Release directory already exists'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
-    await rename(candidate, target);
+    await promote(candidate, target);
     await atomicJson(path.join(stateRoot, 'current.json'), { version: release.version, previous: currentVersion });
     return target;
   } finally { await rm(staging, { recursive: true, force: true }); }