@awak-app/simy-cli 0.5.36 → 0.5.38

package/src/session-supervision/handoff.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { evaluateAssessedPlan, listRecords, managedBudgetReason, updateRecord } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { openCodexAppServer, readCodexSession } from './codex-app-server.js';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function unsettled(managed) {
+  return managed.phase === 'understanding' || managed.executionUncertain || managed.executionAttempt && managed.executionAttempt.phase !== 'checkpointed' || managed.providerWarning || managed.resumeLease || managed.pendingApproval || managed.approvedAction && !managed.approvedAction.dispatchedAt ||
+    managed.dispatchLedger?.some(entry => !['settled', 'cancelled'].includes(entry.status)) ||
+    managed.dispatches?.some(entry => entry.status && !['settled', 'cancelled', 'completed'].includes(entry.status));
+}
+function exactSource(record, taskId, targetSession, now, allowStoppedPending = false) {
+  if (!record?.run?.managed || !record.admission || record.admission.session !== record.session || record.admission.cwd !== record.cwd || record.run.managed.taskId !== taskId) throw new Error('Exact managed task is unavailable.');
+  if (now !== undefined && managedBudgetReason(record.run, now)) throw new Error('Original task budget exhausted; handoff cannot restore it.');
+  const prior = record.run.managed.handoff;
+  const transfer = prior?.status === 'received' ? null : prior;
+  if (transfer && transfer.targetSession !== targetSession) throw new Error('A different handoff is already recorded.');
+  if (!transfer && (record.run.state !== 'paused' || unsettled(record.run.managed))) throw new Error('Handoff requires paused source with no unsettled lease, dispatch, or approval.');
+  if (transfer && (transfer.status === 'pending' && record.run.state !== 'paused' && !(allowStoppedPending && record.run.state === 'stopped') || transfer.status === 'transferred' && record.run.state !== 'stopped')) throw new Error('Source handoff state changed.');
+  if (transfer && !['pending', 'transferred'].includes(transfer.status)) throw new Error('This session is a handoff recipient.');
+  return record;
+}
+
+// Explicit user command only. This transfers SIMY's durable work binding, not
+// provider turns or external effects. Neither session receives a turn here.
+export async function handoffSession({ root, provider, session, taskId, targetSession, openClient = openCodexAppServer, now = Date.now() }) {
+  if (provider !== 'codex') throw new Error('Claude handoff is unsupported; return to the original live conversation.');
+  if (!UUID.test(session || '') || !UUID.test(targetSession || '') || session === targetSession || !taskId) throw new Error('Distinct exact Codex session IDs and task ID are required.');
+  const source = exactSource((await listRecords(root)).find(item => item.provider === provider && item.session === session), taskId, targetSession, now);
+  const startedWall = Date.now();
+  const budgetNow = () => now + Math.max(0, Date.now() - startedWall);
+  const client = await openClient();
+  let metadata;
+  try {
+    const original = await readCodexSession(client, session);
+    metadata = await readCodexSession(client, targetSession);
+    if (await realpath(original.cwd) !== source.cwd || await realpath(metadata.cwd) !== source.cwd || !metadata.model || metadata.model !== source.run.managed.resumeModel || original.model !== metadata.model) throw new Error('Handoff workspace or model does not match admitted source.');
+    const sourceConfiguration = await client.request('thread/resume', { threadId: session, excludeTurns: true });
+    const targetConfiguration = await client.request('thread/resume', { threadId: targetSession, excludeTurns: true });
+    for (const [configuration, expected] of [[sourceConfiguration, session], [targetConfiguration, targetSession]]) {
+      if (configuration?.thread?.id !== expected || !configuration.cwd || await realpath(configuration.cwd) !== source.cwd || configuration.model !== metadata.model || !['readOnly', 'workspaceWrite', 'dangerFullAccess'].includes(configuration.sandbox?.type)) throw new Error('Exact session admission or sandbox is unavailable.');
+    }
+    if (!isDeepStrictEqual(sourceConfiguration.sandbox, targetConfiguration.sandbox)) throw new Error('Target sandbox must preserve exact source rights.');
+    const enrolled = source.run.managed.providerSandbox;
+    if (enrolled && Object.entries(enrolled).some(([key, value]) => !isDeepStrictEqual(value, sourceConfiguration.sandbox[key]))) throw new Error('Source sandbox changed from enrolled rights.');
+    // Freeze source first. The ordinary control/hook/supervisor paths reject
+    // pending/transferred and pending_received markers, including after crash.
+    const frozen = await updateRecord(root, provider, session, record => {
+      exactSource(record, taskId, targetSession, budgetNow());
+      if ((record.run.managed.handoff?.id || null) !== (source.run.managed.handoff?.id || null)) throw new Error('Handoff identity changed or cancelled during admission.');
+      if (!record.run.managed.handoff || record.run.managed.handoff.status === 'received') record.run.managed.handoff = { id: randomUUID(), sourceSession: session, targetSession, status: 'pending', startedAt: now };
+      return record;
+    });
+    const handoff = frozen.run.managed.handoff;
+    await updateRecord(root, provider, session, async sourceRecord => {
+      exactSource(sourceRecord, taskId, targetSession, budgetNow());
+      if (sourceRecord.run.managed.handoff?.id !== handoff.id) throw new Error('Handoff identity changed or cancelled.');
+      await updateRecord(root, provider, targetSession, target => {
+      if (target?.run) {
+        if (target.run.id !== frozen.run.id || target.run.managed?.handoff?.id !== handoff.id || target.run.managed.taskId !== taskId) throw new Error('Target already owns another run.');
+        return target;
+      }
+      if (target && target.cwd !== source.cwd) throw new Error('Target admission workspace changed.');
+      const run = structuredClone(frozen.run);
+      run.state = 'paused';
+      run.managed.thread = { provider, id: targetSession };
+      run.managed.providerSandbox = structuredClone(targetConfiguration.sandbox);
+      const option = { id: 'inspect_handoff', action: { kind: 'read', scope: run.managed.approvalScopes[0], summary: 'Inspect transferred goal, frozen acceptance, prior evidence, and current workspace before proposing the next action' },
+        assessment: { risk: 'low', reversibility: 'reversible', externalEffect: 'none', blastRadius: 'single_file', uncertainty: 'low', inObjective: true, userChoice: false },
+        expectedVerification: 'Read-only observations reconcile the durable task with this conversation and workspace.', rollback: 'No changes to undo.' };
+      run.managed.plan = { diagnosis: 'Explicit work handoff requires read-only reconciliation before further work.', alternatives: [option], selectedOptionId: option.id, recommendation: { optionId: option.id, reason: 'Preserve task evidence without replaying the previous action.' } };
+      run.managed.decision = evaluateAssessedPlan(run.managed.plan, run.managed.autonomyPolicy, run.managed.approvalScopes, now);
+      run.managed.decisionHistory = [...(run.managed.decisionHistory || []), run.managed.decision].slice(-20);
+      delete run.managed.approvedAction;
+      run.checkpoint = null;
+      run.nextStep = option.action.summary;
+      run.reason = 'Explicit handoff is paused; resume starts with read-only reconciliation.';
+      run.managed.handoff = { ...handoff, status: 'pending_received' };
+      run.managed.threadHistory = [...(run.managed.threadHistory || [session]), targetSession].slice(-20);
+      run.managed.workBindingHistory = [...(run.managed.workBindingHistory || []), { from: session, to: targetSession, handoffId: handoff.id, at: handoff.startedAt }].slice(-20);
+      return { ...(target || {}), schemaVersion: 1, provider, session: targetSession, cwd: source.cwd, monitor: true,
+        admission: { source: 'codex_app_server', provider, session: targetSession, cwd: source.cwd, model: metadata.model, validatedAt: now }, run };
+      });
+      return sourceRecord;
+    });
+    await updateRecord(root, provider, session, record => {
+      exactSource(record, taskId, targetSession, budgetNow());
+      if (record.run.managed.handoff.id !== handoff.id) throw new Error('Handoff identity changed.');
+      record.run.state = 'stopped'; record.run.reason = 'Work transferred to the exact target conversation.';
+      record.run.managed.handoff.status = 'transferred';
+      record.run.managed.handoff.transferredAt ||= now;
+      return record;
+    });
+    const received = await updateRecord(root, provider, targetSession, record => {
+      if (record?.run?.managed?.handoff?.id !== handoff.id) throw new Error('Target handoff identity changed.');
+      record.run.managed.handoff.status = 'received';
+      return record;
+    });
+    return { provider, session: targetSession, sourceSession: session, taskId, runId: frozen.run.id, state: received.run.state, handoffId: handoff.id };
+  } finally { await client.close(); }
+}
+
+
+// Cancellation is explicit and permitted only before this transfer has created
+// its target run. Source-then-target locking shares creation's lock order, so
+// an in-flight creator cannot publish an orphan after the marker is cleared.
+export async function cancelHandoffSession({ root, provider, session, taskId, targetSession }) {
+  if (provider !== 'codex' || !UUID.test(session || '') || !UUID.test(targetSession || '') || session === targetSession || !taskId) throw new Error('Exact Codex source, target, and task ID are required.');
+  const source = await updateRecord(root, provider, session, async record => {
+    exactSource(record, taskId, targetSession, undefined, true);
+    const marker = record.run.managed.handoff;
+    if (marker?.status !== 'pending') throw new Error('Only a pending handoff without a target run can be cancelled.');
+    await updateRecord(root, provider, targetSession, target => {
+      if (target?.run?.managed?.handoff?.id === marker.id) throw new Error('Target run exists; complete the exact handoff instead of cancelling.');
+      return target;
+    });
+    record.run.managed.workBindingHistory = [...(record.run.managed.workBindingHistory || []),
+      { from: session, to: targetSession, handoffId: marker.id, cancelled: true }].slice(-20);
+    delete record.run.managed.handoff;
+    return record;
+  });
+  return { provider, session, targetSession, taskId, state: source.run.state, cancelled: true };
+}

package/src/session-supervision/index.js

@@ -60,7 +60,9 @@ export async function discoverSessions({ root, openClient = openCodexAppServer,
       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 },
+      capabilities: { canMonitor: item.capabilities?.canMonitor ?? true,
+        canAnalyze: !run && (item.provider === 'codex' ? item.observation.source === 'codex_app_server' && !codexError : item.observation.source === 'claude_local_index' && !claudeError),
+        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.' :
@@ -96,9 +98,10 @@ export async function monitorSession({ root, provider, session, monitor = true,
 }
 
 export async function enrollSession({ root, provider, session, objective, acceptanceCriteria, contextBootstrap = false, autonomyPolicy = 'balanced',
-  maxMinutes = 30, maxContinuations = 6, maxFailures = 3, openClient = openCodexAppServer,
+  maxMinutes = 30, maxContinuations = 6, maxFailures = 3, maxNoProgressMinutes, maxTokens, 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 (maxTokens !== undefined && provider !== 'codex') throw new Error('Token-budgeted supervision requires host-observed Codex usage; Claude live hooks cannot enforce this budget.');
   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;
@@ -123,7 +126,7 @@ export async function enrollSession({ root, provider, session, objective, accept
   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',
+    managed: { acceptanceCriteria, contextBootstrap, autonomyPolicy, maxNoProgressMinutes, maxTokens, 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 } });

package/src/session-supervision/workspace-lease.js

@@ -0,0 +1,2 @@
+// The identical lease protocol also ships with the provider hooks.
+export { acquireWorkspaceLease, releaseWorkspaceLease, leaseOwnerDead } from '../codex-plugins/simy/hooks/workspace-lease.mjs';

package/src/sqm/claude-plugin.js

@@ -21,6 +21,7 @@ export async function claudePluginFiles() {
     files.set(relative, content.replaceAll("current Codex thread", "current Claude Code conversation"));
   }
   files.set("hooks/delivery-loop.mjs", await readFile(path.join(SOURCE, "hooks/delivery-loop.mjs"), "utf8"));
+  files.set("hooks/workspace-lease.mjs", await readFile(path.join(SOURCE, "hooks/workspace-lease.mjs"), "utf8"));
   files.set("hooks/connection-reminder.mjs", await readFile(path.join(SOURCE, "hooks/connection-reminder.mjs"), "utf8"));
   const hooks = JSON.parse(await readFile(path.join(SOURCE, "hooks/hooks.json"), "utf8"));
   delete hooks.hooks.Interrupt; // Codex-only event; Claude interruptions cannot be vetoed.

package/src/sqm/review-worker.js

@@ -178,10 +178,14 @@ export async function runStructuredProviderReview(
     inspectExecutor = inspectDesktopExecutor,
     executionTimeoutMs = DEFAULT_EXECUTION_TIMEOUT_MS,
     environment = process.env,
+    signal,
+    readOnlyAnalysis = false,
+    terminationGraceMs = 1_000,
   } = {},
 ) {
   assertProvider(provider);
   assertStructuredRequest(request);
+  if (signal?.aborted) throw new SqmLocalReviewError('Local analysis was cancelled.', { code: 'analysis_cancelled' });
   const label = provider === "claude" ? "Claude Code" : "Codex";
   const inspection = await inspectExecutor(provider);
   if (!inspection?.compatible || !inspection.executable) {
@@ -207,6 +211,7 @@ export async function runStructuredProviderReview(
         "--no-session-persistence", "--tools", "",
         "--setting-sources", "", "--settings", '{"disableAllHooks":true}',
         "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
+        ...(readOnlyAnalysis ? ["--system-prompt", request.system, "--max-turns", "1"] : []),
       ] : [
         "exec",
         "--skip-git-repo-check",
@@ -215,6 +220,7 @@ export async function runStructuredProviderReview(
         "--ephemeral",
         "--ignore-user-config",
         "--ignore-rules",
+        ...(readOnlyAnalysis ? codexAnalysisArguments(request.system) : []),
         "--output-schema",
         schemaPath,
         "--output-last-message",
@@ -222,7 +228,8 @@ export async function runStructuredProviderReview(
         "-",
       ],
       prompt,
-      { spawnImpl, executionTimeoutMs, label, cwd: workDir, environment, provider },
+      { spawnImpl, executionTimeoutMs, label, cwd: workDir, environment, provider, signal, readOnlyAnalysis,
+        terminationGraceMs: Number.isInteger(terminationGraceMs) ? Math.max(1, Math.min(terminationGraceMs, 5_000)) : 1_000 },
     );
     const envelope = provider === "claude" ? JSON.parse(stdout) : null;
     if (envelope?.is_error || (envelope && envelope.subtype !== "success")) {
@@ -248,8 +255,22 @@ export async function runStructuredProviderReview(
   }
 }
 
-function spawnReview(command, args, prompt, { spawnImpl, executionTimeoutMs, label, cwd, environment, provider }) {
+function codexAnalysisArguments(system) {
+  // --ignore-user-config excludes user-configured MCP. Disable plugins/apps,
+  // host skills and tool families as well; read-only sandbox remains a second
+  // boundary. These flags are supported by the packaged Codex CLI.
+  const disabled = ['shell_tool', 'unified_exec', 'shell_snapshot', 'view_image', 'apps', 'plugins', 'hooks',
+    'memories', 'multi_agent', 'multi_agent_v2', 'browser_use', 'computer_use', 'image_generation',
+    'code_mode', 'code_mode_host', 'skill_search', 'skill_mcp_dependency_install', 'workspace_dependencies', 'goals'];
+  return ['--json', ...disabled.flatMap(feature => ['--disable', feature]),
+    '-c', 'features.skip_host_skill_discovery=true', '-c', 'web_search="disabled"',
+    '-c', 'mcp_servers={}', '-c', 'approval_policy="never"',
+    '-c', `developer_instructions=${JSON.stringify(system)}`];
+}
+
+function spawnReview(command, args, prompt, { spawnImpl, executionTimeoutMs, label, cwd, environment, provider, signal, readOnlyAnalysis, terminationGraceMs }) {
   return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error('Local analysis was cancelled'));
     const child = spawnImpl(command, args, {
       env: safeReviewEnvironment(environment, provider),
       cwd,
@@ -259,35 +280,61 @@ function spawnReview(command, args, prompt, { spawnImpl, executionTimeoutMs, lab
     let stdout = "";
     let stderr = "";
     let settled = false;
+    let terminalError = null;
+    let killTimer = null;
+    const halt = error => {
+      if (settled || terminalError) return;
+      terminalError = error;
+      child.kill?.('SIGTERM');
+      if (!settled) killTimer = setTimeout(() => {
+        child.kill?.('SIGKILL');
+        // Do not acknowledge cancellation while an owned provider is still
+        // shutting down. A broken process API is nevertheless bounded.
+        if (!settled) killTimer = setTimeout(() => finish(new Error('Local analysis process did not confirm termination')), terminationGraceMs);
+      }, terminationGraceMs);
+    };
+    const cancelled = () => halt(new Error('Local analysis was cancelled'));
     const timer = setTimeout(() => {
-      child.kill?.("SIGTERM");
-      finish(new Error(`${label} timed out after ${executionTimeoutMs}ms`));
+      halt(new Error(`${label} timed out after ${executionTimeoutMs}ms`));
     }, executionTimeoutMs);
     timer.unref?.();
     const finish = (error = null) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      clearTimeout(killTimer);
+      signal?.removeEventListener('abort', cancelled);
       error ? reject(error) : resolve(stdout);
     };
     child.stdout?.setEncoding?.("utf8");
     child.stdout?.on?.("data", (chunk) => {
       if (settled) return;
       stdout += chunk;
+      if (readOnlyAnalysis && provider === 'codex') {
+        for (const line of stdout.split('\n').filter(Boolean)) {
+          let event;
+          try { event = JSON.parse(line); } catch { continue; }
+          if (/command_execution|mcp_tool_call|web_search|file_change|tool_call/.test(event.item?.type || '')) {
+            halt(new Error('Read-only analysis attempted to use a tool'));
+            return;
+          }
+        }
+      }
       if (Buffer.byteLength(stdout, "utf8") > 2 * 1024 * 1024) {
-        child.kill?.("SIGTERM");
-        finish(new Error(`${label} structured output exceeded the size limit`));
+        halt(new Error(`${label} structured output exceeded the size limit`));
       }
     });
     child.stdin?.on?.("error", finish);
     child.stderr?.setEncoding?.("utf8");
     child.stderr?.on?.("data", (chunk) => {
-      stderr = `${stderr}${chunk}`.slice(-4000);
+      if (!readOnlyAnalysis) stderr = `${stderr}${chunk}`.slice(-4000);
     });
     child.on("error", finish);
     child.on("close", (code) => {
-      finish(code === 0 ? null : new Error(stderr.trim() || `${label} exited with code ${code}`));
+      finish(terminalError || (code === 0 ? null : new Error(stderr.trim() || `${label} exited with code ${code}`)));
     });
+    signal?.addEventListener('abort', cancelled, { once: true });
+    if (signal?.aborted) { cancelled(); return; }
     child.stdin?.end(prompt);
   });
 }