@awak-app/simy-cli 0.7.29 → 0.7.31

package/src/sqm/claude-plugin.js

@@ -21,7 +21,10 @@ export async function claudePluginFiles() {
     if (!entry.isDirectory()) continue;
     const relative = `skills/${entry.name}/SKILL.md`;
     const content = await readFile(path.join(SOURCE, relative), "utf8");
-    files.set(relative, content.replaceAll("current Codex thread", "current Claude Code conversation"));
+    files.set(relative, content.replaceAll("current Codex thread", "current Claude Code conversation")
+      .replace('For this Codex conversation, use its existing `CODEX_THREAD_ID`:',
+        'For this Claude Code conversation, use the provider-substituted `${CLAUDE_SESSION_ID}` below:')
+      .replace('--provider codex --session "$CODEX_THREAD_ID"', '--provider claude --session "${CLAUDE_SESSION_ID}"'));
   }
   // Codex's local delivery skill is retired. Keep the separately maintained
   // Claude workflow without shipping it back into Codex's skill inventory.
@@ -94,7 +97,7 @@ export async function claudePluginFiles() {
   for (const [name, contents] of [...files].sort(([a], [b]) => a.localeCompare(b))) hash.update(name).update("\0").update(contents);
   const manifest = {
     name: "simy", version: `${sourceManifest.version.split("+")[0]}+claude.${hash.digest("hex").slice(0, 20)}`,
-    description: "SIMY quality checks, pull request review, and connection reminders for Claude Code.",
+    description: "SIMY Auto Continue through the original conversation controller, quality checks, and PR review for Claude Code.",
     author: sourceManifest.author, repository: sourceManifest.repository,
     license: sourceManifest.license, keywords: sourceManifest.keywords,
   };

package/src/sqm/history-store.js

@@ -112,6 +112,9 @@ function metadata(entry) {
   if (Number.isInteger(entry.errorStatus) && entry.errorStatus >= 400 && entry.errorStatus <= 599) item.errorStatus = entry.errorStatus;
   if (Number.isInteger(entry.httpStatus) && entry.httpStatus >= 400 && entry.httpStatus <= 599) item.httpStatus = entry.httpStatus;
   if (typeof entry.noApplicableChecks === 'boolean') item.noApplicableChecks = entry.noApplicableChecks;
+  if (Number.isSafeInteger(entry.checkCount) && entry.checkCount >= 0) item.checkCount = entry.checkCount;
+  if (['verified', 'unmet', 'unconfirmed'].includes(entry.inspectionStatus)) item.inspectionStatus = entry.inspectionStatus;
+  if (Number.isSafeInteger(entry.passedCheckCount) && entry.passedCheckCount >= 0 && entry.passedCheckCount <= item.checkCount) item.passedCheckCount = entry.passedCheckCount;
   if (Array.isArray(entry.checked)) item.checked = entry.checked.filter(value => typeof value === 'string').slice(0, 10).map(value => value.slice(0, 160));
   if (Number.isSafeInteger(entry.findings) && entry.findings >= 0) item.findings = entry.findings;
   const providerDiagnostic = safeProviderDiagnostic(entry.providerDiagnostic);
@@ -156,6 +159,9 @@ export function createSqmCheckRecorder({ root, scope, phase, cwd, baseBranch, pr
         proofId: proof?.proof_id, proofDigest: proof?.integrity?.digest, evidenceId: result.signed_evidence?.evidence_id,
         checked: result.checked_descriptions || presentation.checked || [],
         noApplicableChecks: (proof?.outcome.reasons || minCheck.coverage_reasons || []).includes('no_applicable_rules'),
+        checkCount: proof?.inspection_scope?.checked_count,
+        inspectionStatus: proof?.inspection_scope?.status,
+        passedCheckCount: Array.isArray(proof?.inspection_scope?.checks) ? proof.inspection_scope.checks.filter(check => check.status === 'passed').length : undefined,
         findings: (proof?.findings || result.preliminary_findings || minCheck.preliminary_findings || []).length, finishedAt: new Date().toISOString(), repository,
         label: `${phase === "min" ? "Min-check" : "Check"} · ${repository || basename(cwd)}`,
         instruction: [repository || basename(cwd), `Base: ${identity?.base_ref || baseBranch}`, identity?.head_commit ? `Head: ${identity.head_commit}` : ""].filter(Boolean).join("\n"),

package/src/team-threads.js

@@ -26,7 +26,7 @@ const invalid = () => {
 };
 export const teamThreadKey = (scope, candidate) =>
   digest(
-    JSON.stringify([scope.fenceKey, candidate.provider, candidate.session]),
+    JSON.stringify(candidate.hostId && candidate.hostId !== 'local' ? [scope.fenceKey, candidate.hostId, candidate.provider, candidate.session] : [scope.fenceKey, candidate.provider, candidate.session]),
   );
 function projectSummary(row) {
   if (

package/src/update-detachment/coordinator.js

@@ -1,3 +1,4 @@
+import { verifyTransferredPreservationHealth } from './retained-paused.js';
 // PR3 owns sequencing only. Persistence/fencing and provider identity checks are
 // supplied by PR1/PR2; absence of either must never become permission to update.
 export function createUpdateCoordinator({ store, gate, boundary, reconcile, now = Date.now,
@@ -91,7 +92,12 @@ export function createUpdateCoordinator({ store, gate, boundary, reconcile, now
           // verification; it owns rollback. An ambiguous outcome stays fenced.
           await save('detached', 'updating');
           const result = await update();
-          if (result?.connectionTransferred === true && result?.healthy === true) { state = 'connected'; phase = 'complete'; return snapshot(); }
+          if (result?.connectionTransferred === true && result?.healthy === true) {
+            const checkpoint=await store.read();
+            if(checkpoint?.schemaVersion===2 && !verifyTransferredPreservationHealth(checkpoint,result.preservationAcknowledgement))
+              throw new Error('Updated runtime did not acknowledge the retained checkpoint.');
+            state = 'connected'; phase = 'complete'; return snapshot();
+          }
           if (result?.healthy !== true) throw new Error('Updated runtime health was not verified.');
           return await reconcileConnection();
         } catch (error) {

package/src/update-detachment/history-recovery.js

@@ -31,6 +31,24 @@ export async function planDispatchHistoryRecovery({root}) {
  const auditRef=join(directory,randomUUID()+'.json'),bytes=JSON.stringify(audit,null,2)+'\n';await writeFile(auditRef,bytes,{flag:'wx',mode:0o600});
  return {auditRef,auditDigest:sha(bytes),revision:state.revision,generation:state.generation,results:items.filter(i=>i.disposition==='saved_terminal_result').length,blocked:items.filter(i=>i.disposition==='retain_blocked_unknown').length,replayAttempts:false};
 }
+// The desktop host already owns the desktop process lock. Its in-app recovery
+// runs the same audited plan and revision/generation CAS apply: saved results
+// settle, unknown attempts stay quarantined per task, nothing is replayed.
+export async function recoverDispatchHistoryInProcess({root}) {
+ root=await realpath(root);const plan=await planDispatchHistoryRecovery({root});
+ const result=reconcileDispatchHistory({root,auditRef:plan.auditRef,auditDigest:plan.auditDigest,expectedRevision:plan.revision,expectedGeneration:plan.generation});
+ return {...result,auditRef:plan.auditRef,auditDigest:plan.auditDigest};
+}
+// In-app Try again: reconnect first; only when unknown historical attempts are
+// the remaining blocker, quarantine them through the audited recovery and
+// reconnect once more. Any evidence change fails closed in recovery_required.
+export async function reconnectWithHistoryRecovery({root,coordinator,eligible,recover=recoverDispatchHistoryInProcess}) {
+ await coordinator.reconnect();
+ if(coordinator.snapshot().state!=='recovery_required' || !eligible())return {historyRecovery:null,snapshot:coordinator.snapshot()};
+ const historyRecovery=await recover({root});
+ await coordinator.reconnect();
+ return {historyRecovery,snapshot:coordinator.snapshot()};
+}
 export async function applyDispatchHistoryRecovery({root,auditRef,auditDigest}) {
  root=await realpath(root);const lock=await acquireDesktopProcessLock(root);
  try {const audit=JSON.parse(await readFile(auditRef,'utf8'));return reconcileDispatchHistory({root,auditRef,auditDigest,expectedRevision:audit.expectedRevision,expectedGeneration:audit.expectedGeneration});}

package/src/update-detachment/ledger-adapter.js

@@ -56,6 +56,7 @@ export function createLedgerCoordinatorAdapters({ root = detachmentRoot(), bound
       },
     },
     handoff: release,
+    ownsLease: () => releaseOwner !== null,
     boundary,
     reconcile,
   };

package/src/update-detachment/retained-paused.js

@@ -0,0 +1,290 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { acquireLock, digest } from './state-store.js';
+import { listDispatchRegistrations } from './provenance.js';
+import { readDispatchGate, unresolvedDispatchAttempts, DISPATCH_PROTOCOL } from './dispatch-gate.js';
+import { requireProviderLink } from '../provider-links.js';
+import { readClaudeSession, readClaudeBoundary, snapshotClaudeHumanCursor } from '../session-supervision/claude-sessions.js';
+import { recordPath, updateRecord, processIdentity, stopMarkerPath, updateInvalidationPath,
+  hasPendingUserStop, hasPendingUpdateInvalidation } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+
+export const RETAINED_PAUSED_CAPABILITY = 'retained-paused-update-v1';
+const terminal = new Set(['completed', 'reported_done', 'failed', 'succeeded']);
+const fail = code => { throw Object.assign(new Error(`Retained update: ${code}`), { code }); };
+const sha = bytes => createHash('sha256').update(bytes).digest('hex');
+const key = row => `${row.provider}:${row.session}`;
+const actorIdentity = actor => ({ account: actor?.account, device: actor?.device, origin: actor?.origin });
+const fingerprint = info => [info.dev, info.ino, info.birthtimeNs, info.size, info.mtimeNs, info.ctimeNs].map(String).join(':');
+function fileSnapshot(file, optional = false) {
+  try {
+    const before = lstatSync(file, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 4n * 1024n * 1024n || realpathSync(file) !== file) fail('source_unavailable');
+    const bytes = readFileSync(file), after = lstatSync(file, { bigint: true });
+    if (fingerprint(before) !== fingerprint(after)) fail('source_changed');
+    return { ref: file, sha256: sha(bytes), value: JSON.parse(bytes) };
+  } catch (error) { if (optional && error.code === 'ENOENT') return null; throw error; }
+}
+function marker(file) {
+  const snapshot = fileSnapshot(file, true);
+  return snapshot && { ref: snapshot.ref, sha256: snapshot.sha256 };
+}
+function stableTranscript(cursor) {
+  if (cursor?.version !== 2) fail('transcript_unavailable');
+  const info = lstatSync(cursor.path, { bigint: true });
+  if (!info.isFile() || info.isSymbolicLink() || realpathSync(cursor.path) !== cursor.path || info.birthtimeNs <= 0n ||
+      String(info.dev) !== cursor.dev || String(info.ino) !== cursor.ino || String(info.birthtimeNs) !== cursor.birthtimeNs ||
+      info.size !== BigInt(cursor.size)) fail('transcript_changed');
+  return { ref: cursor.path, metadata: fingerprint(info) };
+}
+function gateEvidence(gate) {
+  return digest([gate.generation, gate.attempts, gate.receipts, gate.recoveryFences, gate.writerCapabilities,
+    gate.hookOwners, gate.ownerRenewals, gate.taskFences]);
+}
+function requireEmptyIntake(root) {
+  try { if (readdirSync(join(root, 'update-detachment', 'intake')).length) fail('receipt_intake_pending'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+function contextEvidence(context) {
+  for (const row of [...(context.runs || []), ...(context.localTasks || []), ...(context.directTasks || [])]) {
+    if (!['completed', 'failed', 'cancelled', 'stopped', 'succeeded', 'reported_done', 'paused', 'paused_by_user'].includes(row.status || row.state)) fail('execution_not_quiescent');
+    if (row.child || row.operation || row.pendingLedgerUpdate || row.ledgerUpdateRunning || row.worker_handle ||
+        ['queued', 'running', 'dispatching', 'coding', 'stopping'].includes(row.status)) fail('execution_not_quiescent');
+  }
+  return digest([actorIdentity(context.actor), context.runs || [], context.localTasks || [], context.directTasks || []]);
+}
+function eligible(record) {
+  const run = record?.run, m = run?.managed;
+  if (record?.provider !== 'claude' || record.schemaVersion !== 1 || record.autoContinue !== false || run?.state !== 'paused' ||
+      !run.id || !m?.taskId || !m.liveHookOwner?.identity || !Number.isSafeInteger(m.liveHookOwner.pid) || m.liveHookOwner.pid < 2 ||
+      record.providerArchived || m.executionUncertain || m.executionAttempt && m.executionAttempt.phase !== 'settled' ||
+      run.blocker || m.pendingApproval || m.nativeWait || run.providerRequest || m.resumeLease || m.liveWorkspaceLease ||
+      m.outcomeAudit?.lease || ['awaiting_human', 'prepared', 'gate_committed'].includes(m.ownerRenewal?.status) ||
+      ['pending', 'pending_received', 'transferred'].includes(m.handoff?.status)) fail('record_not_retained_paused');
+  if (realpathSync(record.cwd) !== record.cwd) fail('cwd_changed');
+}
+function retainedFence(root, gate, record) {
+  const attempts = Object.entries(gate.attempts).filter(([, row]) =>
+    row.taskHash === digest(record.run.id) || row.taskHash === digest(record.run.managed.taskId));
+  const unknown = attempts.filter(([, row]) => row.phase !== 'confirmed');
+  // This narrow mode preserves an already audited historical quarantine. It
+  // cannot invent registration or create a new dispatch exception/fence.
+  if (!unknown.length || unknown.some(([id, row]) => gate.recoveryFences?.items?.[id]?.attemptDigest !== digest(row)))
+    fail('history_fence_required');
+  const auditRef = gate.recoveryFences.auditRef;
+  if (typeof auditRef !== 'string' || !auditRef.startsWith(join(root, 'update-detachment', 'recovery') + '/')) fail('history_audit_changed');
+  const audit = fileSnapshot(auditRef);
+  if (audit.sha256 !== gate.recoveryFences.auditDigest || audit.value.version !== 1 || !Array.isArray(audit.value.items) ||
+      unknown.some(([, row]) => !audit.value.items.some(item => item.attemptId === row.id &&
+        item.attemptDigest === digest(row) && item.disposition === 'retain_blocked_unknown'))) fail('history_audit_changed');
+  return { auditRef, auditDigest: gate.recoveryFences.auditDigest,
+    items: unknown.map(([id, row]) => ({ key: id, attemptDigest: digest(row) })) };
+}
+function validCheckpoint(checkpoint) {
+  return checkpoint?.capability === RETAINED_PAUSED_CAPABILITY && typeof checkpoint.operationId === 'string' &&
+    checkpoint.operationId.length > 0 && checkpoint.payload !== null && typeof checkpoint.payload === 'object' &&
+    !Array.isArray(checkpoint.payload) && Array.isArray(checkpoint.payload.inventory) &&
+    Array.isArray(checkpoint.payload.records) && Number.isSafeInteger(checkpoint.payload.generation) &&
+    checkpoint.payload.generation >= 0 && checkpoint.digest === digest(checkpoint.payload);
+}
+export function retainedCheckpointChallenge(transaction) {
+  const checkpoint = transaction?.retainedCheckpoint;
+  if (transaction?.schemaVersion !== 2 || !validCheckpoint(checkpoint) ||
+      checkpoint.operationId !== transaction.operationId) fail('checkpoint_invalid');
+  return { kind: 'retained_checkpoint_challenge', capability: RETAINED_PAUSED_CAPABILITY, schemaVersion: 2,
+    operationId: transaction.operationId, checkpointDigest: checkpoint.digest,
+    inventoryDigest: digest(checkpoint.payload.inventory), generation: checkpoint.payload.generation };
+}
+function exactDescriptor(expected, actual) {
+  return actual !== null && typeof actual === 'object' && !Array.isArray(actual) &&
+    Object.keys(actual).length === Object.keys(expected).length &&
+    Object.keys(expected).every(name => actual[name] === expected[name]);
+}
+export function matchesRetainedCheckpointChallenge(transaction, challenge) {
+  return exactDescriptor(retainedCheckpointChallenge(transaction), challenge);
+}
+function validVerifier(value) {
+  return Number.isSafeInteger(value?.pid) && value.pid > 1 && typeof value.identity === 'string' && value.identity.length > 0;
+}
+export function createPreservationVerification(transaction, gate, verifier) {
+  const challenge = retainedCheckpointChallenge(transaction), transfer = transaction.consumedRetainedTransfer;
+  if (gate.connection !== 'reconciling' || gate.generation !== challenge.generation || !validVerifier(verifier) ||
+      !Number.isSafeInteger(transaction.revision) || transaction.transferToken) fail('preservation_verification_unavailable');
+  if (transfer && (transfer.kind !== 'retained_transfer_consumed' || transfer.version !== 1 ||
+      !exactDescriptor(challenge, transfer.challenge) || !validVerifier(transfer.source) ||
+      transfer.source.pid === verifier.pid ||
+      !/^[a-f0-9]{64}$/.test(transfer.tokenDigest || '') || !validVerifier(transfer.candidate) ||
+      transfer.candidate.pid !== verifier.pid || transfer.candidate.identity !== verifier.identity ||
+      transaction.ownerPid !== verifier.pid || transaction.ownerIdentity !== verifier.identity)) fail('preservation_candidate_changed');
+  // This is preservation metadata, never a provider terminal/execution receipt.
+  return { kind: 'retained_preservation_verification', version: 1, id: randomUUID(), challenge,
+    verifier: { ...verifier }, transferDigest: transfer ? digest(transfer) : null,
+    committedRevision: transaction.revision + 1 };
+}
+export function retainedPreservationHealth(transaction, gate) {
+  const challenge = retainedCheckpointChallenge(transaction), receipt = transaction.preservationVerification;
+  if (transaction.connectionState !== 'connected' || transaction.phase !== 'complete' || gate?.connection !== 'connected' ||
+      gate.generation !== challenge.generation || transaction.transferToken ||
+      receipt?.kind !== 'retained_preservation_verification' || receipt.version !== 1 ||
+      typeof receipt.id !== 'string' || !receipt.id || !exactDescriptor(challenge, receipt.challenge) ||
+      !validVerifier(receipt.verifier) || receipt.verifier.pid !== transaction.ownerPid ||
+      receipt.verifier.identity !== transaction.ownerIdentity || !Number.isSafeInteger(receipt.committedRevision) ||
+      receipt.committedRevision < 1 || receipt.committedRevision > transaction.revision) fail('preservation_health_unverified');
+  const transfer = transaction.consumedRetainedTransfer;
+  if (transfer ? transfer.kind !== 'retained_transfer_consumed' || transfer.version !== 1 ||
+      !exactDescriptor(challenge, transfer.challenge) || !validVerifier(transfer.source) ||
+      transfer.source.pid === receipt.verifier.pid ||
+      !/^[a-f0-9]{64}$/.test(transfer.tokenDigest || '') || transfer.candidate?.pid !== receipt.verifier.pid ||
+      transfer.candidate.identity !== receipt.verifier.identity || receipt.transferDigest !== digest(transfer)
+    : receipt.transferDigest !== null) fail('preservation_health_unverified');
+  return { ...challenge, kind: 'retained_preservation_health', verificationId: receipt.id,
+    verificationDigest: digest(receipt), verifierPid: receipt.verifier.pid, verifierIdentity: receipt.verifier.identity,
+    transferDigest: receipt.transferDigest };
+}
+export function verifyTransferredPreservationHealth(view, acknowledgement) {
+  try {
+    // These two fields are supplied only by runtime.store.read from its fresh
+    // durable transaction and actual ledger, not by a command/callback echo.
+    if (!view?.preservationGate || view.preservationTransactionConnection !== 'connected' ||
+        view.transferToken !== null || !view.consumedRetainedTransfer || view.updateState !== 'succeeded') return false;
+    const durable = { ...view, connectionState: view.preservationTransactionConnection };
+    return exactDescriptor(retainedPreservationHealth(durable, view.preservationGate), acknowledgement);
+  } catch { return false; }
+}
+
+// Host-owned maintenance dependencies only; no public command or bootstrap is
+// wired here. Explicit mode never creates a registration, writer or execution.
+export function createRetainedPausedPreserver({ root, origin, configuration, readContext }) {
+  const { authorize, inspectProcess = processIdentity, transcriptHome, expectedProviderEpoch } = configuration;
+  const expectedActor = structuredClone(configuration.expectedActor), targets = structuredClone(configuration.targets);
+  if (configuration.hostId !== 'local' || expectedActor?.origin !== origin || typeof authorize !== 'function' || !Object.hasOwn(configuration, 'expectedProviderEpoch') ||
+      !(expectedProviderEpoch === null || typeof expectedProviderEpoch === 'string' && expectedProviderEpoch.length > 0 && expectedProviderEpoch.length <= 128) ||
+      !expectedActor || !['account', 'device', 'origin'].every(name => typeof expectedActor[name] === 'string' && expectedActor[name]) ||
+      !Array.isArray(targets) || targets.length !== 1 || targets.some(row => row.provider !== 'claude' ||
+        !row.session || !row.runId || !row.taskId)) fail('maintenance_authority_required');
+  const deliveryRoot = join(root, 'delivery-hooks');
+  const hasTarget = record => targets.some(row => key(row) === key(record) && row.runId === record.run?.id && row.taskId === record.run?.managed?.taskId);
+  function inventory(ordinaryTasks = []) {
+    if (ordinaryTasks.length) fail('mixed_retention_unsupported');
+    let names;
+    try { names = readdirSync(deliveryRoot).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).sort(); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; names = []; }
+    if (names.length > 512) fail('inventory_too_large');
+    let bytes = 0;
+    const values = names.map(name => {
+      const snapshot = fileSnapshot(join(deliveryRoot, name)), record = snapshot.value;
+      bytes += lstatSync(snapshot.ref).size;
+      if (bytes > 64 * 1024 * 1024 || record.schemaVersion !== 1 || !['codex', 'claude'].includes(record.provider) ||
+          typeof record.session !== 'string' || recordPath(deliveryRoot, record.provider, record.session) !== snapshot.ref) fail('inventory_invalid');
+      const classification = hasTarget(record) ? 'retained_paused' : !record.run ? 'observed' : terminal.has(record.run.state) ? 'terminal' : 'registered';
+      if (classification === 'registered') fail('mixed_retention_unsupported');
+      return { ref: snapshot.ref, sha256: snapshot.sha256, provider: record.provider, session: record.session,
+        runId: record.run?.id || null, taskId: record.run?.managed?.taskId || record.run?.id || null, classification };
+    });
+    if (targets.some(target => !values.some(row => key(row) === key(target) && row.runId === target.runId &&
+        row.taskId === target.taskId && row.classification === 'retained_paused'))) fail('target_changed');
+    return values;
+  }
+  async function authority() {
+    await authorize();
+    if (digest(actorIdentity(readContext().actor)) !== digest(expectedActor)) fail('actor_changed');
+    await requireProviderLink({ root: deliveryRoot, provider: 'claude', expectedEpoch: expectedProviderEpoch });
+  }
+  async function dead(owner) {
+    if (!Number.isSafeInteger(owner?.pid) || owner.pid < 2 || !owner.identity) fail('writer_unknown');
+    const actual = await inspectProcess(owner.pid);
+    if (actual === null || actual === undefined) fail('writer_unknown');
+    if (actual !== '') fail(actual === owner.identity ? 'writer_active' : 'writer_pid_reused');
+  }
+  async function writers(gate, records) {
+    for (const record of records) await dead(record.run.managed.liveHookOwner);
+    for (const writer of Object.values(gate.writerCapabilities || {})) {
+      if (writer.protocol !== DISPATCH_PROTOCOL || !writer.moduleDigest) fail('writer_unknown');
+      await dead({ pid: writer.pid, identity: writer.processIdentity });
+    }
+  }
+  function targetRecords(rows) {
+    return rows.filter(row => row.classification === 'retained_paused').map(row => {
+      const record = fileSnapshot(row.ref).value; eligible(record);
+      if (listDispatchRegistrations(root, { retained: true }).some(registration =>
+          registration.recordRef === row.ref && registration.taskId === record.run.managed.taskId)) fail('retained_registered_task');
+      if (hasPendingUserStop(deliveryRoot, record) || hasPendingUpdateInvalidation(deliveryRoot, record)) fail('native_boundary_changed');
+      return record;
+    });
+  }
+  function syncCheck(payload, ordinaryTasks) {
+    requireEmptyIntake(root);
+    const targets = payload.inventory.filter(row => row.classification === 'retained_paused');
+    if (payload.records.length !== targets.length || new Set(payload.records.map(row => row.recordRef)).size !== targets.length ||
+        targets.some(row => !payload.records.some(proof => proof.recordRef === row.ref && proof.recordDigest === row.sha256 &&
+          proof.runId === row.runId && proof.taskId === row.taskId && proof.canResume === false)) ||
+        digest(payload.actor) !== digest(expectedActor) || payload.providerEpoch !== expectedProviderEpoch ||
+        payload.generation !== readDispatchGate(root).generation) fail('checkpoint_invalid');
+    if (digest(inventory(ordinaryTasks)) !== digest(payload.inventory) || contextEvidence(readContext()) !== payload.contextEvidence ||
+        digest(actorIdentity(readContext().actor)) !== digest(expectedActor) ||
+        gateEvidence(readDispatchGate(root)) !== payload.gateEvidence ||
+        digest(marker(join(root, 'provider-links.json'))) !== digest(payload.providerLinkFile)) fail('checkpoint_changed');
+    for (const row of payload.records) {
+      const record = fileSnapshot(row.recordRef).value; eligible(record);
+      if (digest(retainedFence(root, readDispatchGate(root), record)) !== digest(row.historyFence) ||
+          hasPendingUserStop(deliveryRoot, record) || hasPendingUpdateInvalidation(deliveryRoot, record) ||
+          digest(marker(stopMarkerPath(deliveryRoot, record.provider, record.session))) !== digest(row.stopMarker) ||
+          digest(marker(updateInvalidationPath(deliveryRoot, record.provider, record.session))) !== digest(row.nativeMarker) ||
+          digest(stableTranscript(row.cursor)) !== digest(row.transcript)) fail('native_boundary_changed');
+    }
+  }
+  async function prepare(ordinaryTasks, operationId) {
+    await authority();
+    const gate = readDispatchGate(root);
+    if (!['detaching', 'reconciling'].includes(gate.connection) || unresolvedDispatchAttempts(gate).length) fail('history_unresolved');
+    requireEmptyIntake(root);
+    const rows = inventory(ordinaryTasks), records = targetRecords(rows);
+    const payload = { actor: expectedActor, providerEpoch: expectedProviderEpoch, generation: gate.generation, inventory: rows,
+      contextEvidence: contextEvidence(readContext()), providerLinkFile: marker(join(root, 'provider-links.json')),
+      gateEvidence: gateEvidence(gate), records: [] };
+    await writers(gate, records);
+    for (const record of records) {
+      const historyFence = retainedFence(root, gate, record);
+      const metadata = await readClaudeSession({ session: record.session, cwd: record.cwd }, { home: transcriptHome });
+      const cursor = await snapshotClaudeHumanCursor({ session: record.session, cwd: record.cwd }, { home: transcriptHome });
+      if (!metadata || !cursor) fail('transcript_unavailable');
+      const transcript = stableTranscript(cursor), boundary = await readClaudeBoundary(metadata, { home: transcriptHome });
+      if (!boundary?.complete || boundary.digest !== cursor.prefixSHA256 || boundary.byteLength !== cursor.size ||
+          digest(stableTranscript(cursor)) !== digest(transcript)) fail('transcript_changed');
+      payload.records.push({ title: record.title || record.provider, recordRef: recordPath(deliveryRoot, record.provider, record.session),
+        runId: record.run.id, taskId: record.run.managed.taskId, owner: record.run.managed.liveHookOwner,
+        recordDigest: rows.find(row => key(row) === key(record)).sha256,
+        budgetDigest: digest([record.run.continuations, record.run.failures, record.run.deadline, record.run.managed.usage]),
+        grantsDigest: digest([record.run.managed.grants, record.run.managed.approvalScopes, record.run.managed.acceptanceCriteria]),
+        historyFence, boundary, cursor, transcript, stopMarker: marker(stopMarkerPath(deliveryRoot, record.provider, record.session)),
+        nativeMarker: marker(updateInvalidationPath(deliveryRoot, record.provider, record.session)), canResume: false });
+    }
+    return { capability: RETAINED_PAUSED_CAPABILITY, operationId, payload, digest: digest(payload) };
+  }
+  async function withVerified(checkpoint, ordinaryTasks, commit) {
+    if (!validCheckpoint(checkpoint)) fail('checkpoint_invalid');
+    const gateRelease = acquireLock(join(root, 'update-detachment', 'gate.json'));
+    try {
+      const lock = async index => {
+        if (index === checkpoint.payload.inventory.length) {
+          await authority(); await writers(readDispatchGate(root), targetRecords(checkpoint.payload.inventory));
+          // All async authorization/link/process and record-lock awaits precede
+          // this final synchronous source/marker/inventory check and commit.
+          syncCheck(checkpoint.payload, ordinaryTasks);
+          return commit();
+        }
+        const row = checkpoint.payload.inventory[index];
+        let result;
+        await updateRecord(deliveryRoot, row.provider, row.session, async () => { result = await lock(index + 1); return null; }, { inspectProcess });
+        return result;
+      };
+      return await lock(0);
+    } finally { gateRelease(); }
+  }
+  return { hasTarget, prepare, withVerified, assertSupported: tasks => {
+    requireEmptyIntake(root); inventory(tasks); contextEvidence(readContext());
+  }, assertUnchanged: (checkpoint, tasks) => {
+    if (!validCheckpoint(checkpoint)) fail('checkpoint_invalid');
+    syncCheck(checkpoint.payload, tasks);
+  } };
+}

package/src/update-detachment/runtime.js

@@ -1,3 +1,5 @@
+import { createRetainedPausedPreserver, RETAINED_PAUSED_CAPABILITY, retainedCheckpointChallenge,
+  matchesRetainedCheckpointChallenge, createPreservationVerification, retainedPreservationHealth } from './retained-paused.js';
 import { readCodexPolicyContext } from './codex-context.js';
 import { mkdirSync, realpathSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
@@ -72,20 +74,31 @@ export async function observeOriginalProvider(record, { openClient = openCodexAp
 }
 
 export function createUpdateRuntime({ root, origin, readContext, listRecords, observe = observeOriginalProvider,
-  worker = null, now=Date.now } = {}) {
+  worker = null, now=Date.now, retainedPaused = null } = {}) {
   mkdirSync(root,{recursive:true,mode:0o700});root=realpathSync(root); const file=join(root,'update-detachment','transaction.json');
-  let transaction=readState(file), ownerTransferred=false;
+  const readTransaction=()=> {
+    const value=readState(file,{versions:retainedPaused?[1,2]:[1]});
+    if(value?.schemaVersion===2 && (value.preservationCapability!==RETAINED_PAUSED_CAPABILITY ||
+        typeof value.operationId!=='string' || !value.operationId || !Array.isArray(value.tasks)))throw failure('preservation_capability_required');
+    return value;
+  };
+  let transaction=readTransaction(), ownerTransferred=false, retainedVerified=false;
+  const retainer=retainedPaused?createRetainedPausedPreserver({root,origin,configuration:retainedPaused,readContext:()=>readContext?.() || {}}):null;
   const workerFor=identity=>worker || createLedgerExecutionWorker({identity});
   const context=()=>readContext?.() || {runs:[],directTasks:[],localTasks:[]};
   const write=patch=>withLock(file,()=> {
-    const current=readState(file);
+    const current=readTransaction();
     if (transaction && current?.revision!==transaction.revision) throw failure('transaction_revision_changed');
-    transaction={schemaVersion:1,operationId:randomUUID(),tasks:[],...current,...patch,revision:(current?.revision || 0)+1};
+    if (retainer && (current?.operationId!==transaction?.operationId || digest(current)!==digest(transaction)))
+      throw failure('transaction_revision_changed');
+    transaction={schemaVersion:1,operationId:randomUUID(),tasks:[],...current,...patch,...(retainer?{schemaVersion:2,preservationCapability:RETAINED_PAUSED_CAPABILITY}:{}),revision:(current?.revision || 0)+1};
     atomicSave(file,transaction);
   });
   let presented=null;
   const uiState = task => task.stop_requested ? 'stopped' : ['stopped','cancelled'].includes(task.status || task.state) ? 'stopped' : ['paused','paused_by_user'].includes(task.status || task.state) ? 'paused' : task.managed?.pendingApproval ? 'approval_wait' : ['running','queued','active','dispatching','coding'].includes(task.status || task.state) ? 'running' : 'needs_user';
-  const rows=()=> (transaction?.connectionState==='detaching' ? transaction?.pendingTasks || [] : transaction?.tasks || []).map(task=>({title:task.title || 'Provider task',taskState:task.canResume===false && !['paused','paused_by_user','cancelled','stopped','approval_wait'].includes(task.uiState)?'needs_user':['paused_by_user','cancelled'].includes(task.uiState)?'paused':task.uiState || 'needs_user',
+  const rows=()=> (transaction?.connectionState==='detaching' ? transaction?.pendingTasks || [] : [
+    ...(transaction?.tasks || []),...(transaction?.retainedCheckpoint?.payload?.records || []).map(record=>({
+      title:record.title,uiState:'paused',canResume:false}))]).map(task=>({title:task.title || 'Provider task',taskState:task.canResume===false && !['paused','paused_by_user','cancelled','stopped','approval_wait'].includes(task.uiState)?'needs_user':['paused_by_user','cancelled'].includes(task.uiState)?'paused':task.uiState || 'needs_user',
     ...(task.canResume===false?{canResume:false,reason:'Open the original conversation to review and continue.'}:{}),
     disposition:task.workerPreserved?'continuing':transaction.connectionState==='detaching'?'waiting_for_boundary':'saved',executionPreserved:task.workerPreserved===true}));
   const pendingTasks=async()=> {
@@ -109,7 +122,13 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
     }
     return writers;
   }});
-  const store={read:async()=>({...await adapters.store.read(),...transaction,connectionState:readDispatchGate(root).connection}),
+  const store={read:async()=> {
+      if(ownerTransferred)transaction=readTransaction();
+      const ledger=await adapters.store.read();
+      return {...ledger,...transaction,connectionState:ledger.connection,
+        ...(retainer?{preservationGate:{connection:ledger.connection,generation:ledger.generation},
+          preservationTransactionConnection:transaction?.connectionState}:{})};
+    },
     write:async patch=>{write({...patch,...(patch.connectionState==='detaching'?{pendingTasks:await pendingTasks()}:{}),...(patch.connectionState==='connected' && transaction?.updateState==='applying'?{updateState:'succeeded'}:patch.connectionState==='recovery_required' && transaction?.updateState==='applying'?{updateState:'failed'}:{})});await adapters.store.write(patch);}};
   const records=async()=> (await listRecords()).filter(record=>record.run);
   const currentRecord=async record=>(await records()).find(item=>item.provider===record.provider && item.session===record.session);
@@ -131,7 +150,7 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
       // Closed records remain in their original durable storage. They have no
       // live writer to reconnect and may legitimately outlive their worktree.
       // The global receipt check below still rejects every unresolved attempt.
-      if(terminal.has(record.run.state))continue;
+      if(terminal.has(record.run.state) || retainer?.hasTarget(record))continue;
       const binding=await bind(record), provider=await observe(record,{readCurrentRecord:()=>currentRecord(record),readInvalidation:current=>hasPendingUpdateInvalidation(join(root,'delivery-hooks'),current)});
       if(provider.identity.session!==binding.session || provider.identity.worktree!==await realpath(record.cwd)) throw failure('provider_identity_changed');
       if(provider.running) return null;
@@ -146,6 +165,7 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
   const boundary=async()=> {
     const startingGate=readDispatchGate(root);
     if(startingGate.connection!=='detaching')return {safe:false,liveExecutions:0,pendingWrites:0,unsettledPermissions:0};
+    retainer?.assertSupported([]);
     const c=context(), execution=[...(c.runs||[]),...(c.localTasks||[])];
     const unowned=execution.filter(run=>run.child || run.operation || run.pendingLedgerUpdate || run.ledgerUpdateRunning || ['queued','running','dispatching','coding'].includes(run.status));
     const workers=[];
@@ -166,6 +186,9 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
     const pendingWrites=execution.filter(run=>run.pendingLedgerUpdate||run.ledgerUpdateRunning).length;
     if(unowned.length || pendingWrites) return {safe:false,liveExecutions:unowned.length,pendingWrites,unsettledPermissions:0};
     const tasks=await capture(); if(!tasks) return {safe:false,liveExecutions:1,pendingWrites:0,unsettledPermissions:0};
+    // Capture contains awaits. Recheck the conservative subset before any
+    // ordinary receipt confirmation, policy fence, or checkpoint side effect.
+    retainer?.assertSupported(tasks);
     flushDispatchIntake(root);
     let ledger=readDispatchGate(root);
     for(const attempt of Object.values(ledger.attempts)) {
@@ -188,10 +211,17 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
     if(currentGate.connection!=='detaching' || currentGate.generation!==startingGate.generation)throw failure('boundary_owner_changed');
     for(const task of tasks)if(task.canResume===false)await adapters.gate.fenceTask({identity:task.identity,taskId:task.taskId,
       reason:{code:task.policy.model?'provider_policy_unknown':'provider_model_unknown',evidenceRef:task.recordRef}});
-    write({tasks:[...tasks,...workers]});
+    if(retainer) {
+      if(!adapters.ownsLease())throw failure('coordinator_ownership_required');
+      const retainedCheckpoint=await retainer.prepare(tasks,transaction.operationId);
+      await retainer.withVerified(retainedCheckpoint,tasks,()=>write({tasks:[...tasks,...workers],retainedCheckpoint,
+        preservationVerification:null,consumedRetainedTransfer:null,transferToken:null}));
+      retainedVerified=false;
+    } else write({tasks:[...tasks,...workers]});
     return {safe:true,liveExecutions:workers.filter(task=>task.workerPreserved).length,workerHandoffVerified:true,pendingWrites:0,unsettledPermissions:0};
   };
   const reconcile=async()=> {
+    retainer?.assertSupported(transaction?.tasks || []);
     const actor=context().actor, assessments=[];
     const workers=(transaction?.tasks || []).filter(task=>task.handle);
     if(unresolvedDispatchAttempts(readDispatchGate(root)).some(attempt=> !workers.some(task=>task.handle.attemptId===attempt.id)))return {verified:false,unresolvedAttempts:1};
@@ -255,15 +285,37 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
       // Verified original hook lifetime, no cold process takeover.
       adoptHookOwner({root,provider:task.identity.provider,session:task.identity.session,expectedRevision:readDispatchGate(root).revision});
     }
+    if(retainer) {
+      if(!adapters.ownsLease() || !transaction?.retainedCheckpoint)throw failure('retained_checkpoint_required');
+      const verifier={pid:process.pid,identity:await processIdentity(process.pid)};
+      if(!verifier.identity)throw failure('preservation_verifier_unavailable');
+      await retainer.withVerified(transaction.retainedCheckpoint,transaction.tasks,()=>{
+        const preservationVerification=createPreservationVerification(transaction,readDispatchGate(root),verifier);
+        write({preservationVerification,ownerPid:verifier.pid,ownerIdentity:verifier.identity});
+        retainedVerified=true;
+      });
+      assessments.push({status:'retained_paused',canResume:false,reasons:['original_owner_unverified','historical_effects_quarantined']});
+    }
     return {verified:true,unresolvedAttempts:0,assessments};
   };
   return {bind,boundary,reconcile,store,gate:adapters.gate,
+    // Only unknown historical attempts block reconnect: live worker handoffs
+    // reconcile through their own proof and are never quarantined here.
+    historyRecoveryEligible() {
+      const gate=readDispatchGate(root);
+      return gate.connection==='recovery_required' && unresolvedDispatchAttempts(gate).length>0 && !(transaction?.tasks || []).some(task=>task.handle);
+    },
     async initialize() {if(!transaction)write({connectionState:readDispatchGate(root).connection,phase:'startup',updateState:'pending'});},
     snapshot(base,update,{accessReady=true}={}) {
-      if(ownerTransferred)transaction=readState(file);
+      if(ownerTransferred)transaction=readTransaction();
       const action=base.state==='connected' && update?.state==='waiting_for_idle'?'detach_update':base.state==='detaching'?'cancel_detach_update':!base.busy && ['detached','recovery_required'].includes(base.state)?'update_reconnect':null;
       const frame={...base,schemaVersion:1,connectionState:base.state,
         updateState:transaction?.updateState || 'pending',updaterState:update?.state || 'unknown',tasks:rows(),actions:action?[action]:[]};
+      if(retainer && retainedVerified && base.state==='connected' && transaction?.connectionState==='connected' &&
+          readDispatchGate(root).connection==='connected') {
+        retainer.assertUnchanged(transaction.retainedCheckpoint,transaction.tasks);
+        frame.preservationAcknowledgement=retainedPreservationHealth(transaction,readDispatchGate(root));
+      }
       // Revision the exact frame the native client sees. Filtering after the
       // fingerprint makes an access change look like conflicting data at the
       // same revision, which correctly fences all native update actions.
@@ -283,7 +335,10 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
       if(gate.connection!=='detached' || transaction?.connectionState!=='detached')throw failure('handoff_not_detached');
       const token=randomUUID(),ownerIdentity=await processIdentity(process.pid);
       if(!ownerIdentity)throw failure('handoff_owner_unavailable');
-      write({transferToken:token,ownerPid:process.pid,ownerIdentity,generation:gate.generation,updateState:'applying'});
+      const commit=()=>write({transferToken:token,ownerPid:process.pid,ownerIdentity,generation:gate.generation,updateState:'applying',
+        ...(retainer?{preservationVerification:null,consumedRetainedTransfer:null}: {})});
+      if(retainer)await retainer.withVerified(transaction.retainedCheckpoint,transaction.tasks,commit);
+      else commit();
       for(const task of context().directTasks || []) {
         if(transaction.tasks.some(saved=>saved.handle && saved.taskId===task.id)) {
           task.observation_suspended=true;task.update_owner_transferred=true;
@@ -291,25 +346,33 @@ export function createUpdateRuntime({ root, origin, readContext, listRecords, ob
       }
       adapters.handoff();ownerTransferred=true;return token;
     },
-    async acceptHandoff(token) {
-      transaction=readState(file);
+    async acceptHandoff(token, preservation = null) {
+      transaction=readTransaction();
       const original=transaction;
+      if(retainer && !matchesRetainedCheckpointChallenge(transaction,preservation))throw failure('preservation_challenge_required');
+      if(retainer && original?.ownerPid===process.pid)throw failure('preservation_distinct_candidate_required');
       if(!original || original.transferToken!==token || original.generation!==readDispatchGate(root).generation || readDispatchGate(root).connection!=='detached' || original.connectionState!=='detached' || await processIdentity(original.ownerPid)!==original.ownerIdentity)throw failure('handoff_identity_changed');
       // Claim coordinator ownership before consuming the transfer token. Both
       // the durable revision and token are checked again after asynchronous IO.
       const ownerIdentity=await processIdentity(process.pid);
       if(!ownerIdentity)throw failure('handoff_owner_unavailable');
       await adapters.gate.close();
-      write({ownerPid:process.pid,ownerIdentity,transferToken:null});
+      const commit=()=>write({ownerPid:process.pid,ownerIdentity,transferToken:null,...(retainer?{
+        preservationVerification:null,consumedRetainedTransfer:{kind:'retained_transfer_consumed',version:1,
+          tokenDigest:digest(token),challenge:retainedCheckpointChallenge(transaction),
+          source:{pid:original.ownerPid,identity:original.ownerIdentity},candidate:{pid:process.pid,identity:ownerIdentity}}}: {})});
+      if(retainer)await retainer.withVerified(transaction.retainedCheckpoint,transaction.tasks,commit);
+      else commit();
     },
     async reclaimFailedHandoff() {
-      const current=readState(file);
+      const current=readTransaction();
       if(!ownerTransferred || !current)return;
       if(current.ownerPid!==process.pid && await processIdentity(current.ownerPid)===current.ownerIdentity)throw failure('candidate_owner_still_live');
       transaction=current;
       const ownerIdentity=await processIdentity(process.pid);
       if(!ownerIdentity)throw failure('handoff_owner_unavailable');
-      write({transferToken:null,ownerPid:process.pid,ownerIdentity,updateState:'failed'});
+      write({transferToken:null,ownerPid:process.pid,ownerIdentity,updateState:'failed',
+        ...(retainer?{preservationVerification:null,consumedRetainedTransfer:null}: {})});
       for(const task of context().directTasks || []) {
         if(transaction.tasks.some(saved=>saved.handle && saved.taskId===task.id)) {
           task.observation_suspended=false;task.update_owner_transferred=false;