@awak-app/simy-cli 0.5.35 → 0.5.37

package/src/delivery-hooks/command.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { startDelivery, checkpointDelivery, controlDelivery, listRecords, rootDirectory, verifyDelivery } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { continueSession } from '../session-supervision/index.js';
+import { cancelHandoffSession, handoffSession } from '../session-supervision/handoff.js';
 
 async function readCheckpointInput(input) {
   const chunks = [];
@@ -16,11 +18,12 @@ async function readCheckpointInput(input) {
 export async function runDeliveryCommand(argv, { root = rootDirectory(), cwd = process.cwd(), input = process.stdin, output = console.log } = {}) {
   const [action, ...args] = argv;
   if (!action || action === '--help') {
+    output('simy delivery continue --provider codex|claude --session ID [--max-no-progress-minutes 30] [--max-tokens N (Codex only)]\nsimy delivery dependency_ready --provider PROVIDER --session ID --task-id ID --wait-id ID --answer TEXT\nsimy delivery handoff|handoff_cancel --provider codex --session ID --task-id ID --target-session ID');
     output('simy delivery start --provider codex|claude --session ID --objective TEXT --next-step TEXT [--managed-file task.json] [--max-continuations 6] [--max-failures 3] [--max-minutes 30]\nsimy delivery checkpoint --provider codex|claude --session ID --file checkpoint.json|-\nsimy delivery status\nsimy delivery stop|pause|resume --provider codex|claude --session ID [--task-id ID]\nsimy delivery replan --provider PROVIDER --session ID --task-id ID\nsimy delivery approve|reject --provider PROVIDER --session ID --task-id ID --approval-id ID\nsimy delivery verify --provider PROVIDER --session ID --task-id ID --criterion-id ID\nsimy delivery set_policy --provider PROVIDER --session ID --task-id ID --autonomy-policy strict|balanced|autonomous\nEnable and review SIMY hooks in your provider first. Manual managed start requires an acceptance specification. Desktop Continue infers the original conversation goal first. Resume preserves original budgets.');
     return 0;
   }
   const options = {};
-  const allowed = new Set(['provider', 'session', 'objective', 'next-step', 'max-continuations', 'max-failures', 'max-minutes', 'file', 'managed-file', 'task-id', 'approval-id', 'criterion-id', 'autonomy-policy']);
+  const allowed = new Set(['provider', 'session', 'objective', 'next-step', 'max-continuations', 'max-failures', 'max-minutes', 'max-no-progress-minutes', 'max-tokens', 'file', 'managed-file', 'task-id', 'approval-id', 'criterion-id', 'autonomy-policy', 'wait-id', 'answer', 'target-session']);
   for (let i = 0; i < args.length; i += 2) {
     const key = args[i]?.replace(/^--/, '');
     if (!args[i]?.startsWith('--') || !allowed.has(key) || args[i + 1] === undefined || Object.hasOwn(options, key)) throw new Error('Invalid delivery option. Use simy delivery --help.');
@@ -29,6 +32,11 @@ export async function runDeliveryCommand(argv, { root = rootDirectory(), cwd = p
   const base = { root, cwd, provider: options.provider, session: options.session };
   let result;
   if (action === 'status') result = (await listRecords(root)).filter(r => (!options.provider || r.provider === options.provider) && (!options.session || r.session === options.session));
+  else if (action === 'continue') result = await continueSession({ ...base, autonomyPolicy: options['autonomy-policy'],
+    ...Object.fromEntries([['max-continuations', 'maxContinuations'], ['max-failures', 'maxFailures'], ['max-minutes', 'maxMinutes'],
+      ['max-no-progress-minutes', 'maxNoProgressMinutes'], ['max-tokens', 'maxTokens']].filter(([key]) => options[key] !== undefined).map(([key, field]) => [field, Number(options[key])])) });
+  else if (action === 'handoff') result = await handoffSession({ ...base, taskId: options['task-id'], targetSession: options['target-session'] });
+  else if (action === 'handoff_cancel') result = await cancelHandoffSession({ ...base, taskId: options['task-id'], targetSession: options['target-session'] });
   else if (action === 'start') {
     let managed;
     if (options['managed-file']) {
@@ -36,6 +44,11 @@ export async function runDeliveryCommand(argv, { root = rootDirectory(), cwd = p
       if (Buffer.byteLength(data) > 64 * 1024) throw new Error('Managed task specification exceeds 64 KiB.');
       managed = JSON.parse(data);
     }
+    if (options['max-tokens'] !== undefined || options['max-no-progress-minutes'] !== undefined) {
+      if (!managed || typeof managed !== 'object') throw new Error('Managed budget flags require --managed-file; use delivery continue for context-first supervision.');
+      managed = { ...managed, ...Object.fromEntries([['max-tokens', 'maxTokens'], ['max-no-progress-minutes', 'maxNoProgressMinutes']]
+        .filter(([key]) => options[key] !== undefined).map(([key, field]) => [field, Number(options[key])])) };
+    }
     result = await startDelivery({ ...base, objective: options.objective, nextStep: options['next-step'], managed,
     ...Object.fromEntries([['max-continuations', 'maxContinuations'], ['max-failures', 'maxFailures'], ['max-minutes', 'maxMinutes']].filter(([key]) => options[key] !== undefined).map(([key, field]) => [field, Number(options[key])])) });
   }
@@ -44,7 +57,7 @@ export async function runDeliveryCommand(argv, { root = rootDirectory(), cwd = p
     const data = options.file === '-' ? await readCheckpointInput(input) : await readFile(options.file, 'utf8');
     if (Buffer.byteLength(data) > 64 * 1024) throw new Error('Checkpoint exceeds 64 KiB.');
     result = await checkpointDelivery({ ...base, checkpoint: JSON.parse(data) });
-  } else if (['stop', 'pause', 'resume', 'replan', 'approve', 'reject', 'set_policy'].includes(action)) result = await controlDelivery({ ...base, taskId: options['task-id'], approvalId: options['approval-id'], autonomyPolicy: options['autonomy-policy'], action });
+  } else if (['stop', 'pause', 'resume', 'replan', 'approve', 'reject', 'set_policy', 'dependency_ready'].includes(action)) result = await controlDelivery({ ...base, taskId: options['task-id'], approvalId: options['approval-id'], autonomyPolicy: options['autonomy-policy'], waitId: options['wait-id'], answer: options.answer, action });
   else if (action === 'verify') result = await verifyDelivery({ ...base, taskId: options['task-id'], criterionId: options['criterion-id'] });
   else throw new Error('Unknown delivery command.');
   output(JSON.stringify(result, null, 2));

package/src/delivery-hooks/desktop.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { canReplanDelivery, reconcileRecords, rootDirectory } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { canReplanDelivery, managedBudgetReason, reconcileRecords, rootDirectory } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
 import { originalSessionTarget } from '../session-supervision/original-session-target.js';
 
 export const HOOK_SETUP = Object.freeze({
@@ -27,6 +27,13 @@ export async function deliveryHookStatus({ root = rootDirectory(), now = Date.no
       phase: r.run.managed?.phase || 'active', sessionUnderstanding: r.run.managed?.sessionUnderstanding || null,
       understandingQuestion: r.run.managed?.understandingQuestion || null,
       remainingWork: r.run.managed?.remainingWork || null, nextStep: r.run.nextStep,
+      dependencyWait: r.run.managed?.dependencyWait || null,
+      executionAttempt: r.run.managed?.executionAttempt || null, executionUncertain: r.run.managed?.executionUncertain || null,
+      handoff: r.run.managed?.handoff || null, threadHistory: r.run.managed?.threadHistory || [],
+      progressBudget: r.run.managed ? { minutes: r.run.managed.maxNoProgressMinutes, lastVerifiedProgressAt: r.run.managed.lastVerifiedProgressAt,
+        attempts: r.run.managed.noProgress, maxAttempts: r.run.managed.maxNoProgress } : null,
+      tokenBudget: r.run.managed?.maxTokens ? { limit: r.run.managed.maxTokens, used: r.run.managed.tokensUsed,
+        usageAvailable: r.run.managed.usageAvailable, source: 'provider_observed', dollarCost: null } : null,
       pendingApproval: r.run.managed?.pendingApproval || null,
       autonomyPolicy: r.run.managed?.autonomyPolicy || null, plan: r.run.managed?.plan || null,
       decision: r.run.managed?.decision || null, decisionHistory: r.run.managed?.decisionHistory || [],
@@ -45,12 +52,15 @@ export async function deliveryHookStatus({ root = rootDirectory(), now = Date.no
         r.run.state === 'recovery_required' && ['session_supervision', 'approved_action'].includes(r.run.recoveryCause) &&
         r.run.managed.resumeChannel === 'codex_app_server' && r.run.managed.autoRecovery),
       canResume: ['blocked', 'recovery_required', 'paused'].includes(r.run.state) && r.run.managed?.phase !== 'needs_clarification' &&
-        !r.run.managed?.pendingApproval && now < r.run.deadline && r.run.continuations < r.run.maxContinuations,
+        !r.run.managed?.pendingApproval && !r.run.managed?.dependencyWait && !['pending', 'pending_received', 'transferred'].includes(r.run.managed?.handoff?.status) &&
+        !managedBudgetReason(r.run, now) && now < r.run.deadline && r.run.continuations < r.run.maxContinuations,
       canApprove: r.run.state === 'blocked' && Boolean(r.run.managed?.pendingApproval) && !r.run.managed.pendingApproval.denied,
       canReject: r.run.state === 'blocked' && Boolean(r.run.managed?.pendingApproval) && !r.run.managed.pendingApproval.denied,
       canReplan: canReplanDelivery(r.run, r.provider, now),
       canAnswer: r.run.managed?.phase === 'needs_clarification' && r.run.state === 'blocked' && Boolean(r.run.managed.understandingQuestion?.id) &&
         now < r.run.deadline && r.run.continuations < r.run.maxContinuations && r.run.failures < r.run.maxFailures,
+      canResolveDependency: r.run.state === 'blocked' && r.run.blocker === 'external_dependency' && Boolean(r.run.managed?.dependencyWait?.id) &&
+        !managedBudgetReason(r.run, now) && !['pending', 'pending_received', 'transferred'].includes(r.run.managed?.handoff?.status),
       canSetPolicy: Boolean(r.run.managed?.autonomyPolicy) && !['completed', 'reported_done', 'stopped', 'failed', 'budget_exhausted'].includes(r.run.state),
     })),
   };

package/src/delivery-hooks/supervisor.js

@@ -1,13 +1,14 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
-import { assessedCheckpointContract, checkpointDelivery, decideStop, listRecords, notifyState, reconcileRecords, updateRecord, verifyAutomaticCriteria } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+import { assessedCheckpointContract, checkpointDelivery, decideStop, listRecords, managedBudgetReason, notifyState, processIdentity, reconcileRecords, updateRecord, verifyAutomaticCriteria } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
 import { resolveBackendExecutable } from '../backend-executable.js';
 import { executeCodexAppServer } from '../session-supervision/codex-app-server.js';
+import { acquireWorkspaceLease, leaseOwnerDead } from '../session-supervision/workspace-lease.js';
 
 const MAX_OUTPUT = 64 * 1024;
 const SAFE_PROVIDER_CODES = new Set(['identity', 'permission_narrowed', 'permission_restore', 'turn_failed', 'checkpoint',
-  'closed', 'timeout', 'unsupported', 'unavailable', 'manual_provider_action', 'checkpoint_rejected', 'provider_approval']);
+  'closed', 'timeout', 'unsupported', 'unavailable', 'manual_provider_action', 'checkpoint_rejected', 'provider_approval', 'usage_unavailable']);
 function safeProviderCode(code) { return SAFE_PROVIDER_CODES.has(code) ? code : 'provider_error'; }
 function providerFailureReason(code) {
   if (code === 'permission_restore') return 'Codex sandbox restoration could not be confirmed; inspect the original conversation before resuming.';
@@ -24,6 +25,7 @@ async function assertActiveLease(root, provider, session, leaseId, signal, curre
     throw new Error('Managed recovery lease changed before provider dispatch.');
   }
   if (currentTime() >= current.run.deadline) throw new Error('Managed recovery deadline expired before provider dispatch.');
+  if (managedBudgetReason(current.run, currentTime())) throw new Error('Managed progress budget expired before provider dispatch.');
   const managed = current.run.managed;
   const approvedWait = managed.decision?.outcome === 'wait' && managed.approvedAction?.id === managed.decision.id && !managed.approvedAction.dispatchedAt;
   if (managed.autonomyPolicy && ((managed.decision?.outcome === 'wait' && !approvedWait) || managed.resumeLease.decisionId !== managed.decision?.id)) throw new Error('Assessed action changed before provider dispatch.');
@@ -51,13 +53,14 @@ export function parseAgentCheckpoint(output, expectedSession) {
 
 // The provider CLI is a new process. It is used only for an exact Codex UUID
 // enrolled for this recovery channel after a corroborated process exit.
-export async function executeCodexResume(record, { signal, root, leaseId, executable = resolveBackendExecutable, currentTime = Date.now } = {}) {
+export async function executeCodexResume(record, { signal, root, leaseId, executable = resolveBackendExecutable, currentTime = Date.now, onActivity = () => {} } = {}) {
   if (signal?.aborted) throw new Error('Managed recovery cancelled before provider dispatch.');
   const binary = await executable('codex');
   if (!binary) throw new Error('Codex executable unavailable.');
   await assertActiveLease(root, record.provider, record.session, leaseId, signal, currentTime);
   const run = record.run;
-  const context = { taskId: run.managed.taskId, session: record.session, objective: run.objective, nextStep: run.nextStep,
+    const context = { taskId: run.managed.taskId, session: record.session, objective: run.objective, nextStep: run.nextStep,
+    lastDependencyResolution: run.managed.lastDependencyResolution,
     remainingWork: run.managed.remainingWork, acceptanceCriteria: run.managed.acceptanceCriteria, proposedAction: run.managed.proposedAction,
     currentDecision: run.managed.autonomyPolicy ? run.managed.decision : undefined, diagnosis: run.managed.plan?.diagnosis,
     budgets: { continuations: run.continuations, maxContinuations: run.maxContinuations, failures: run.failures, maxFailures: run.maxFailures, deadline: run.deadline } };
@@ -95,6 +98,7 @@ export async function executeCodexResume(record, { signal, root, leaseId, execut
     }, 500);
     watch.unref();
     child.stdout.on('data', chunk => {
+      onActivity();
       const lines = (pending + chunk).split('\n');
       pending = lines.pop().slice(-MAX_OUTPUT);
       for (const line of lines) consumeLine(line);
@@ -111,7 +115,7 @@ export async function executeCodexResume(record, { signal, root, leaseId, execut
   });
 }
 
-export async function tickManagedTasks({ root, now = Date.now(), execute, inspectProcess, signal } = {}) {
+export async function tickManagedTasks({ root, now = Date.now(), execute, inspectProcess = processIdentity, signal } = {}) {
   const tickWallStart = Date.now();
   const currentTime = () => now + Math.max(0, Date.now() - tickWallStart);
   if (signal?.aborted) return;
@@ -123,11 +127,18 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
     const claimNow = currentTime();
     const run = record.run;
     if (!run?.managed) continue;
-    if (run.state === 'auto_resuming' && claimNow - run.managed.resumeLease?.claimedAt > 5 * 60_000) {
+    if (run.state === 'auto_resuming') {
+      const owner = run.managed.resumeLease?.owner;
+      const ownerDead = await leaseOwnerDead(owner, inspectProcess);
+      // A live/unknown owner is never taken over merely because time passed.
+      if (!ownerDead && (owner || claimNow - run.managed.resumeLease?.claimedAt <= 5 * 60_000)) continue;
       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.managed.autoRecovery = false;
         current.run.reason = 'Managed recovery was interrupted; inspect the original session before manual resume.';
+        const attempt = current.run.managed.executionAttempt;
+        if (attempt?.phase === 'dispatching' && attempt.action?.kind !== 'read') current.run.managed.executionUncertain = {
+          attemptId: attempt.id, decisionId: attempt.decisionId, action: attempt.action, at: claimNow };
         current.run.updatedAt = claimNow; notifyState(current.run, claimNow); return current;
       });
       continue;
@@ -136,8 +147,11 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
     const causeAllowed = run.recoveryCause === 'process_exit' || appServer && ['session_supervision', 'approved_action'].includes(run.recoveryCause);
     const approvedWait = run.managed.decision?.outcome === 'wait' && ['read', 'local_edit', 'local_test'].includes(run.managed.decision.action?.kind) &&
       run.managed.approvedAction?.id === run.managed.decision.id && !run.managed.approvedAction.dispatchedAt;
+    if (run.managed.executionUncertain && run.managed.recoveryDiagnosisDecisionId !== run.managed.decision?.id) continue;
+    if (['pending', 'transferred', 'pending_received'].includes(run.managed.handoff?.status)) continue;
     if (run.state !== 'recovery_required' || !causeAllowed || !run.managed.autoRecovery || run.managed.pendingApproval || run.managed.autonomyPolicy && run.managed.decision?.outcome === 'wait' && !approvedWait || appServer && run.managed.nextAttemptAt > claimNow) continue;
     const leaseId = randomUUID();
+    const ownerIdentity = await inspectProcess(process.pid) || `pid:${process.pid}`;
     let claimed;
     try { claimed = await updateRecord(root, record.provider, record.session, current => {
       const live = current?.run;
@@ -146,27 +160,39 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
       const approved = live?.managed?.decision?.outcome === 'wait' && ['read', 'local_edit', 'local_test'].includes(live.managed.decision.action?.kind) &&
         live.managed.approvedAction?.id === live.managed.decision.id && !live.managed.approvedAction.dispatchedAt;
       if (!live?.managed?.autoRecovery || live.state !== 'recovery_required' || !allowedCause || live.managed.pendingApproval || live.managed.autonomyPolicy && (!live.managed.decision || live.managed.decision.outcome === 'wait' && !approved) || appChannel && live.managed.nextAttemptAt > currentTime()) return current;
-      if (currentTime() >= live.deadline || live.continuations >= live.maxContinuations || live.failures >= live.maxFailures) {
+      if (managedBudgetReason(live, currentTime()) || currentTime() >= live.deadline || live.continuations >= live.maxContinuations || live.failures >= live.maxFailures) {
         live.state = 'budget_exhausted'; live.reason = 'Original managed continuation budget exhausted.'; live.updatedAt = currentTime(); notifyState(live, live.updatedAt); return current;
       }
-      live.state = 'auto_resuming'; live.managed.resumeLease = { id: leaseId, claimedAt: currentTime(), checkpointRevision: live.revision, decisionId: live.managed.decision?.id || null };
+      live.state = 'auto_resuming'; live.managed.resumeLease = { id: leaseId, claimedAt: currentTime(), checkpointRevision: live.revision, decisionId: live.managed.decision?.id || null,
+        owner: { pid: process.pid, identity: ownerIdentity } };
+      live.managed.executionAttempt = { id: leaseId, decisionId: live.managed.decision?.id || null,
+        action: live.managed.decision?.action || live.managed.proposedAction, phase: 'claimed', claimedAt: currentTime(), lastActivityAt: currentTime() };
       live.managed.autoAttempts = (live.managed.autoAttempts || 0) + 1;
       live.updatedAt = currentTime(); return current;
     }); } catch (error) {
-      if (error?.message === 'Delivery state is busy; retry the command.') continue;
+      // mkdir can become visible before its owner receipt is written. Treat an
+      // ambiguous owner as contention, never as permission to reclaim it.
+      if (error?.message === 'Delivery state is busy; retry the command.' ||
+        error?.message === 'Delivery state lock owner is unavailable; inspect the lock before retrying.') continue;
       throw error;
     }
     if (claimed?.run?.managed?.resumeLease?.id !== leaseId) continue;
     let result;
+    let resource;
+    let lastActivityAt = currentTime();
+    let usage = null;
+    let tokenBudgetExceeded = false;
+    let dispatched = false, waitingForTool = false;
     const controller = new AbortController();
     const abort = () => controller.abort();
     if (signal?.aborted) controller.abort();
     else signal?.addEventListener('abort', abort, { once: true });
-    const timeout = setTimeout(abort, Math.max(1, Math.min(5 * 60_000, claimed.run.deadline - currentTime())));
+    const timeout = setTimeout(abort, Math.max(1, claimed.run.deadline - currentTime()));
     const watch = setInterval(() => {
       void listRecords(root).then(records => {
         const current = records.find(item => item.provider === record.provider && item.session === record.session);
-        if (current?.run?.state !== 'auto_resuming' || current.run.managed?.resumeLease?.id !== leaseId) controller.abort();
+        if (current?.run?.state !== 'auto_resuming' || current.run.managed?.resumeLease?.id !== leaseId ||
+          managedBudgetReason(current.run, currentTime()) || !waitingForTool && currentTime() - lastActivityAt >= 5 * 60_000) controller.abort();
       }).catch(() => controller.abort());
     }, 500);
     watch.unref();
@@ -174,8 +200,42 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
       if (!controller.signal.aborted) await assertActiveLease(root, record.provider, record.session, leaseId, controller.signal, currentTime);
       if (controller.signal.aborted) result = { code: -2, cancelled: true };
       else {
+        resource = await acquireWorkspaceLease({ root, record: claimed, leaseId, inspectProcess, onRecover: async prior => {
+          await updateRecord(root, prior.provider, prior.session, previous => {
+            if (previous?.run?.managed?.taskId === prior.taskId && previous.run.managed.executionAttempt?.phase !== 'checkpointed') {
+              previous.run.managed.executionUncertain ||= { attemptId: prior.leaseId, decisionId: prior.decisionId, at: currentTime() };
+              previous.run.managed.autoRecovery = false;
+            }
+            return previous;
+          });
+        } });
+        if (resource.recoveredOwner) {
+          // The earlier writer may have changed files before its host crashed.
+          // Keep this workspace blocked until its original task is inspected.
+          await updateRecord(root, resource.recoveredOwner.provider, resource.recoveredOwner.session, previous => {
+            if (previous?.run?.managed?.taskId === resource.recoveredOwner.taskId && previous.run.managed.executionAttempt?.phase !== 'checkpointed') {
+              previous.run.managed.executionUncertain ||= { attemptId: resource.recoveredOwner.leaseId,
+                decisionId: resource.recoveredOwner.decisionId, at: currentTime() };
+              previous.run.managed.autoRecovery = false;
+              if (!['stopped', 'paused', 'completed', 'reported_done'].includes(previous.run.state)) previous.run.state = 'recovery_required';
+              previous.run.reason = 'An interrupted workspace writer needs read-only result reconciliation before more changes.';
+            }
+            return previous;
+          });
+          result = { code: -3, busy: true };
+        } else if (resource.busy) result = { code: -3, busy: true };
+        else if (['local_edit', 'local_test'].includes(claimed.run.managed.decision?.action.kind) &&
+          (await listRecords(root)).some(other => other.cwd === claimed.cwd && other.run?.managed?.executionUncertain)) result = { code: -3, busy: true };
+        if (!result) {
         const runner = execute || (appServer ? executeCodexAppServer : executeCodexResume);
         result = await runner(claimed, { signal: controller.signal, root, leaseId, currentTime,
+          onActivity: observation => { lastActivityAt = currentTime(); waitingForTool = observation?.waitingForTool === true; },
+          onUsage: observed => {
+            usage = observed;
+            if (claimed.run.managed.maxTokens && (claimed.run.managed.tokensUsed || 0) + observed.tokens >= claimed.run.managed.maxTokens) {
+              tokenBudgetExceeded = true; controller.abort();
+            }
+          },
           beforeDispatch: async providerSandbox => {
             await assertActiveLease(root, record.provider, record.session, leaseId, controller.signal, currentTime);
             await updateRecord(root, record.provider, record.session, current => {
@@ -187,6 +247,10 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
                   ...(providerSandbox.type === 'workspaceWrite' ? { writableRoots: Array.isArray(providerSandbox.writableRoots) ? providerSandbox.writableRoots.filter(value => typeof value === 'string').slice(0, 20) : [] } : {}) };
               }
               const approved = live.managed.approvedAction;
+              live.managed.executionAttempt.phase = 'dispatching';
+              live.managed.executionAttempt.dispatchedAt = currentTime();
+              live.managed.executionAttempt.lastActivityAt = currentTime();
+              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.');
                 approved.dispatchedAt = currentTime();
@@ -194,21 +258,51 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
               return current;
             });
           } });
+        }
       }
     } catch (error) { result = { code: controller.signal.aborted ? -2 : -1, cancelled: controller.signal.aborted,
       errorCode: error?.code || 'provider_error', restorationUnverified: error?.restorationUnverified === true }; }
     finally { clearTimeout(timeout); clearInterval(watch); signal?.removeEventListener('abort', abort); }
     if (controller.signal.aborted) result = { ...result, code: -2, cancelled: true };
+    if (claimed.run.managed.maxTokens && !usage && !result.busy && dispatched) {
+      result = { ...result, usageUnavailable: true };
+    }
     if (result.code === 0) {
       try {
         await checkpointDelivery({ root, provider: record.provider, session: record.session, cwd: record.cwd,
           checkpoint: result.checkpoint || parseAgentCheckpoint(result.output, record.session), expectedLease: leaseId, now: Date.now() });
+        await updateRecord(root, record.provider, record.session, current => {
+          if (current?.run?.managed?.executionAttempt?.id !== leaseId) return current;
+          current.run.managed.executionAttempt.phase = 'checkpointed';
+          current.run.managed.executionAttempt.checkpointRevision = current.run.revision;
+          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
+            // old action. The newly assessed plan still passes the normal gate.
+            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);
+            delete current.run.managed.executionUncertain;
+            delete current.run.managed.recoveryDiagnosisDecisionId;
+          }
+          return current;
+        });
       } catch { result = { code: -1, errorCode: 'checkpoint_rejected' }; }
     }
     await updateRecord(root, record.provider, record.session, async current => {
       const live = current?.run;
       if (live?.managed?.resumeLease?.id !== leaseId) return current;
       delete live.managed.resumeLease;
+      if (usage) {
+        live.managed.tokensUsed = (live.managed.tokensUsed || 0) + usage.tokens;
+        live.managed.usageAvailable = true;
+        live.managed.lastUsage = { ...usage, attemptId: leaseId };
+      } else if (!result.busy && live.managed.maxTokens && dispatched) {
+        live.managed.usageAvailable = false; live.managed.usageBlocked = true;
+      }
+      const attempt = live.managed.executionAttempt;
+      if (!result.busy && attempt?.phase === 'dispatching' && attempt.action?.kind !== 'read') live.managed.executionUncertain = {
+        attemptId: leaseId, decisionId: attempt.decisionId, action: attempt.action, at: Date.now() };
       live.managed.attempts ||= [];
       live.managed.attempts.push({ id: leaseId, startedAt: claimed.run.managed.resumeLease.claimedAt, endedAt: Date.now(),
         checkpointRevision: live.revision, outcome: result.busy ? 'busy' : result.cancelled ? 'cancelled' : result.code === 0 ? 'checkpoint' : 'failed',
@@ -222,9 +316,19 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
         if (live.state !== 'auto_resuming') live.reason = `${String(live.reason || '').slice(0, 400)} ${live.managed.providerWarning}`.trim();
       }
       if (live.state !== 'auto_resuming') {
+        if (live.managed.usageBlocked && !['stopped', 'paused', 'completed', 'reported_done'].includes(live.state)) {
+          live.managed.autoRecovery = false;
+          live.reason = `${live.reason} Provider token usage is unavailable; further budgeted turns are blocked.`;
+        }
         live.updatedAt = Date.now(); notifyState(live, live.updatedAt); return current;
       }
-      if (result.busy) {
+      if (tokenBudgetExceeded || live.managed.maxTokens && live.managed.tokensUsed >= live.managed.maxTokens) {
+        live.state = 'budget_exhausted'; live.managed.autoRecovery = false;
+        live.reason = 'Observed provider token budget exhausted; inspect any interrupted action in the original conversation.';
+      } else if (live.managed.usageBlocked) {
+        live.state = 'recovery_required'; live.managed.autoRecovery = false;
+        live.reason = 'Provider usage was unavailable; token-budgeted continuation cannot safely start another turn.';
+      } else if (result.busy) {
         live.state = 'recovery_required'; live.recoveryCause = 'session_supervision';
         live.reason = 'Original Codex conversation is in use; SIMY will retry after the writer lock becomes available.';
         live.managed.nextAttemptAt = Date.now() + 15_000;
@@ -264,6 +368,9 @@ export async function tickManagedTasks({ root, now = Date.now(), execute, inspec
       }
       current.run.updatedAt = Date.now(); notifyState(current.run, current.run.updatedAt); return current;
     });
+    // Settling uncertainty must precede unlocking: otherwise another session
+    // could start a write in the effect/checkpoint persistence gap.
+    await resource?.release({ unconfirmed: result.restorationUnverified === true });
   }
 }
 

package/src/desktop-host.js

@@ -233,9 +233,9 @@ export async function startDesktopHost({ input = process.stdin, output = process
         else if (action === "codex_hooks" || action === "claude_hooks") {
           const provider = action === "codex_hooks" ? "codex" : "claude";
           await (dependencies.openHookSettings || openHookSetup)(provider);
-        } else if (["delivery_stop", "delivery_resume", "delivery_pause", "delivery_approve", "delivery_reject", "delivery_replan", "delivery_set_policy"].includes(action)) {
+        } else if (["delivery_stop", "delivery_resume", "delivery_pause", "delivery_approve", "delivery_reject", "delivery_replan", "delivery_set_policy", "delivery_dependency_ready"].includes(action)) {
           await controlDelivery({ root: join(root, "delivery-hooks"), provider: command.provider, session: command.session,
-            taskId: command.taskId, approvalId: command.approvalId, autonomyPolicy: command.autonomyPolicy, action: action.slice("delivery_".length) });
+            taskId: command.taskId, approvalId: command.approvalId, autonomyPolicy: command.autonomyPolicy, waitId: command.waitId, answer: command.answer, action: action.slice("delivery_".length) });
         } else if (action === "delivery_verify") {
           await verifyDelivery({ root: join(root, "delivery-hooks"), provider: command.provider, session: command.session,
             taskId: command.taskId, criterionId: command.criterionId });
@@ -247,12 +247,12 @@ export async function startDesktopHost({ input = process.stdin, output = process
           await (dependencies.enrollSession || enrollSession)({ root: join(root, "delivery-hooks"), provider: command.provider,
             session: command.session, objective: command.objective, acceptanceCriteria: command.acceptanceCriteria,
             autonomyPolicy: command.autonomyPolicy, maxMinutes: command.maxMinutes,
-            maxContinuations: command.maxContinuations, maxFailures: command.maxFailures });
+            maxContinuations: command.maxContinuations, maxFailures: command.maxFailures, maxNoProgressMinutes: command.maxNoProgressMinutes, maxTokens: command.maxTokens });
           await refreshSessions(true);
         } else if (action === "session_continue") {
           await (dependencies.continueSession || continueSession)({ root: join(root, "delivery-hooks"), provider: command.provider,
             session: command.session, autonomyPolicy: command.autonomyPolicy, maxMinutes: command.maxMinutes,
-            maxContinuations: command.maxContinuations, maxFailures: command.maxFailures });
+            maxContinuations: command.maxContinuations, maxFailures: command.maxFailures, maxNoProgressMinutes: command.maxNoProgressMinutes, maxTokens: command.maxTokens });
           await refreshSessions(true);
         } else if (action === "session_answer") {
           await (dependencies.answerSession || answerSession)({ root: join(root, "delivery-hooks"), provider: command.provider,

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

@@ -166,7 +166,7 @@ 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 () => {} } = {}) {
+export async function executeCodexAppServer(record, { openClient = openCodexAppServer, signal, beforeDispatch = async () => {}, onActivity = () => {}, onUsage = () => {} } = {}) {
   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.');
@@ -177,6 +177,7 @@ export async function executeCodexAppServer(record, { openClient = openCodexAppS
   const client = await openClient({ signal });
   let originalSandbox = null, overrideStarted = false, activeTurnId = null, turnCompleted = false, turnStart = null;
   let primaryError = null;
+  let usage = null, lastTotal = 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.');
@@ -191,6 +192,7 @@ export async function executeCodexAppServer(record, { openClient = openCodexAppS
     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,
+      lastDependencyResolution: run.managed.lastDependencyResolution,
       ...(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. ` : '';
@@ -207,6 +209,22 @@ export async function executeCodexAppServer(record, { openClient = openCodexAppS
     const done = new Promise((resolve, reject) => {
       let turnId = null, completion = null, settled = false;
       const messages = new Map();
+      const activeTools = new Set();
+      const earlyUsage = [];
+      const earlyActivity = [];
+      const observeActivity = (method, params) => {
+        if (method === 'item/started' && ['commandExecution', 'mcpToolCall', 'webSearch', 'fileChange'].includes(params.item?.type)) activeTools.add(params.item.id);
+        if (method === 'item/completed') activeTools.delete(params.item?.id);
+        onActivity({ waitingForTool: activeTools.size > 0 });
+      };
+      const observeUsage = params => {
+        const total = params.tokenUsage?.total?.totalTokens, last = params.tokenUsage?.last?.totalTokens;
+        if (!Number.isSafeInteger(total) || total < 0 || !Number.isSafeInteger(last) || last < 0 || last > total) return;
+        if (lastTotal === null) usage = { source: 'codex_app_server', tokens: last, observedAt: Date.now() };
+        else usage.tokens += Math.max(0, total - lastTotal);
+        lastTotal = Math.max(lastTotal ?? 0, total);
+        onUsage({ ...usage });
+      };
       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.'));
@@ -222,6 +240,15 @@ export async function executeCodexAppServer(record, { openClient = openCodexAppS
       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;
+        // Only this owned turn's activity may renew its response watchdog.
+        if (params.turnId === turnId || params.turn?.id === turnId) {
+          if (turnId) observeActivity(method, params);
+        } else if (!turnId && typeof params.turnId === 'string' && earlyActivity.length < 100) earlyActivity.push({ method, turnId: params.turnId,
+          item: { id: params.item?.id, type: params.item?.type } });
+        if (method === 'thread/tokenUsage/updated') {
+          if (turnId && params.turnId === turnId) observeUsage(params);
+          else if (!turnId && earlyUsage.length < 100) earlyUsage.push({ turnId: params.turnId, tokenUsage: params.tokenUsage });
+        }
         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(); }
       });
@@ -230,11 +257,15 @@ export async function executeCodexAppServer(record, { openClient = openCodexAppS
       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(); })
+        .then(response => { turnId = response?.turn?.id; activeTurnId = turnId; if (!turnId) finish(new CodexAppServerError('turn_failed', 'Codex did not start a turn.')); else {
+          for (const params of earlyUsage) if (params.turnId === turnId) observeUsage(params);
+          for (const params of earlyActivity) if (params.turnId === turnId) observeActivity(params.method, params);
+          complete();
+        } })
         .catch(error => finish(error));
     });
     const checkpoint = await done;
-    return { code: 0, checkpoint };
+    return { code: 0, checkpoint, usage };
   } catch (error) {
     primaryError = error;
     throw error;

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 };
+}