@entrorove/skill 0.1.23 → 0.1.24

package/local-task-handoff-fence.mjs

@@ -0,0 +1,478 @@
+import { createPublicKey, randomUUID, sign, verify } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { json, atomic, context, readRegistry } from './local-task-handoff-storage.mjs';
+import { HANDOFF_CANDIDATE_FIELDS, canonicalHandoffSignature, overlayAuthority, receiverClaim, receiverRestoration } from './local-task-handoff-overlay-wire.mjs';
+import { completionChallenge, completionReceipt, completionReceiptCore } from './local-task-handoff-completion-wire.mjs';
+import { loadTaskHandoffSigner as signer, taskHandoffFingerprints as fingerprints } from './local-task-handoff-observation.mjs';
+import { newHandoffWriteArchive, verifyTaskHandoffWriteArchives, handoffWriteCompletionBatch } from './local-task-handoff-write-archive.mjs';
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const SHA = /^[0-9a-f]{64}$/;
+const STATE = 'entrorove.task-handoff-local-state/1.0';
+const CHALLENGE = 'entrorove.task-handoff-challenge/1.0';
+const RESUME = 'entrorove.task-handoff-resume-authorization/1.0';
+const EXECUTION = 'entrorove.task-execution-epoch-authority/1.0';
+const EXECUTION_FIELDS = ['schemaVersion', 'authorityId', 'attemptNonce', 'taskId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest',
+  'leaseId', 'generation', 'epoch', 'status', 'runnerKeyId', 'localRepositoryDigest', 'issuedAt', 'expiresAt'];
+const CHALLENGE_FIELDS = ['schemaVersion', 'purpose', 'challengeId', 'handoffId', 'messageRequestId', 'taskId', 'flowId', 'ownerId',
+  'taskDigest', 'chainDigest', 'checkpointReceiptId', 'checkpointDigest', 'originalScopeDigest', 'localRepositoryDigest',
+  'repositoryFactsDigest', 'scopeSnapshotDigest', 'paths', 'expectedEpoch', 'runnerKeyId', 'issuedAt', 'expiresAt'];
+const RESUME_FIELDS = ['schemaVersion', 'handoffId', 'taskId', 'flowId', 'ownerId', 'localRepositoryDigest', 'epoch',
+  'baselineReceiptDigest', 'baselineChallengeId', 'taskDigest', 'chainDigest', 'originalScopeDigest', 'scopeSnapshotDigest', 'issuedAt', 'expiresAt'];
+function fail(message, code = 'ENTROROVE_HANDOFF_FENCE') { const error = new Error(message); error.code = code; throw error; }
+function exact(value, fields, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== [...fields].sort().join('\0')) fail(`${label} fields are invalid`);
+  return value;
+}
+function id(value, label) { if (typeof value !== 'string' || !ID.test(value)) fail(`${label} identifier is invalid`); return value; }
+function epoch(value) { if (!Number.isSafeInteger(value) || value < 0) fail('handoff epoch is invalid'); return value; }
+function safePath(value) {
+  if (typeof value !== 'string' || !value || value !== value.normalize('NFC') || path.isAbsolute(value) || /^[A-Za-z]:/.test(value)
+    || /[\\\u0000-\u001f\u007f]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail('handoff path is unsafe');
+  return value;
+}
+function pinned(name) {
+  try {
+    const encoded = process.env[name]; if (!encoded) fail(`pinned runner/authority key ${name} is required`);
+    const der = Buffer.from(encoded, 'base64'); const key = createPublicKey({ key: der, type: 'spki', format: 'der' });
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ type: 'spki', format: 'der' }).toString('base64') !== encoded) fail('pinned key is not canonical Ed25519');
+    return { key, keyId: sha256(der) };
+  } catch { fail(`pinned runner/authority key ${name} is invalid`); }
+}
+function authority(value, fields, schema) {
+  const { authorityReceipt: receipt, ...payload } = exact(value, [...fields, 'authorityReceipt'], 'handoff authority');
+  exact(receipt, ['schemaVersion', 'keyId', 'payloadDigest', 'signature'], 'handoff authority receipt');
+  const bytes = Buffer.from(canonical(payload)); const key = pinned('ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY');
+  if (payload.schemaVersion !== schema || bytes.length > 64 * 1024 || receipt.schemaVersion !== 'entrorove.workflow-authority-receipt/1.0'
+    || receipt.keyId !== key.keyId || receipt.payloadDigest !== sha256(bytes) || typeof receipt.signature !== 'string'
+    || !verify(null, bytes, key.key, canonicalHandoffSignature(receipt.signature))) fail('handoff authority schema/signature binding is invalid');
+  return payload;
+}
+function executionAuthority(value) {
+  const takeover = Object.hasOwn(value ?? {}, 'handoffId') || Object.hasOwn(value ?? {}, 'writePassDigest');
+  const payload = authority(value, takeover ? [...EXECUTION_FIELDS, 'handoffId', 'writePassDigest'] : EXECUTION_FIELDS, EXECUTION);
+  if (takeover && (typeof payload.writePassDigest !== 'string' || !SHA.test(payload.writePassDigest))) fail('takeover authority requires its exact signed write pass digest');
+  if (takeover) id(payload.handoffId, 'handoffId');
+  return payload;
+}
+function lifetime(value, live = true) {
+  const start = Date.parse(value.issuedAt); const end = Date.parse(value.expiresAt);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > Date.now() || end <= start || end - start > 90_000
+    || (live && end <= Date.now())) fail('handoff authority is expired or has invalid issuance');
+}
+function fresh(ctx) { return { schemaVersion: STATE, flowId: ctx.flowId, localRepositoryDigest: ctx.repo, status: 'active', epoch: 0,
+  activities: [], revokedPassIds: [], revokedLeaseIds: [], releaseReceipt: null, baselineReceipt: null, resumeAuthorization: null,
+  receiverClaim: null, receiverRestoration: null, receiverCompletion: null, executionAttempts: [], writeArchive: null, writeArchiveHistory: [] }; }
+function receiptSignature(receipt, ctx) {
+  const key = pinned('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY'); const { signature, ...core } = receipt ?? {};
+  if (receipt?.schemaVersion !== 'entrorove.task-handoff-idle-receipt/1.0' || receipt.keyId !== key.keyId || receipt.flowId !== ctx.flowId
+    || receipt.localRepositoryDigest !== ctx.repo || !verify(null, Buffer.from(canonical(core)), key.key, canonicalHandoffSignature(signature))) fail('handoff state has no trusted release/baseline receipt');
+  return receipt;
+}
+function executionAttempts(state, registration, ctx) {
+  const leases = new Set(), nonces = new Set();
+  for (const item of state.executionAttempts) {
+    exact(item, item.status === 'used' ? ['authority', 'status', 'executionHome', 'executionId'] : ['authority', 'status', 'executionHome'], 'execution attempt');
+    const value = executionAuthority(item.authority); lifetime(value, false); epoch(value.epoch);
+    if (!['ready', 'used', 'revoked'].includes(item.status) || value.status !== 'active' || value.flowId !== ctx.flowId
+      || value.localRepositoryDigest !== ctx.repo || value.epoch > state.epoch || !Number.isSafeInteger(value.generation) || value.generation < 1
+      || Date.parse(value.expiresAt) - Date.parse(value.issuedAt) > 30_000
+      || typeof item.executionHome !== 'string' || !path.isAbsolute(item.executionHome) || path.resolve(item.executionHome) !== item.executionHome
+      || ['taskId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId'].some(key => value[key] !== registration[key])) fail('persisted execution attempt lost its trusted original binding or execution home');
+    const lease = `${id(value.leaseId, 'leaseId')}:${value.generation}`, nonce = id(value.attemptNonce, 'attemptNonce');
+    if (leases.has(lease) || nonces.has(nonce)) fail('persisted execution attempt is duplicated');
+    if (item.status === 'used') id(item.executionId, 'executionId');
+    leases.add(lease); nonces.add(nonce);
+  }
+}
+function receiverCurrent(state) {
+  return Boolean(state.receiverClaim && (!state.receiverRestoration || !state.releaseReceipt
+    || state.releaseReceipt.epoch <= state.receiverRestoration.epoch));
+}
+async function read(ctx) {
+  const registration = (await readRegistry(ctx.registry)).bindings[ctx.registryKey];
+  if (!registration) fail('flow is uninitialized at its registered runner; fresh cloud authority is required');
+  let state; try { state = await json(ctx.file, 9 * 1024 * 1024); } catch (error) { if (error.code === 'ENOENT') fail('registered handoff state is missing; explicit cloud recovery is required'); throw error; }
+  exact(state, Object.keys(fresh(ctx)), 'handoff state'); epoch(state.epoch);
+  if (state.schemaVersion !== STATE || state.flowId !== ctx.flowId || state.localRepositoryDigest !== ctx.repo
+    || !['active', 'paused'].includes(state.status) || !Array.isArray(state.activities) || state.activities.length > 128
+    || !Array.isArray(state.revokedPassIds) || !Array.isArray(state.revokedLeaseIds)
+    || !Array.isArray(state.executionAttempts) || state.executionAttempts.length > 1024) fail('handoff state binding is invalid');
+  executionAttempts(state, registration, ctx);
+  await verifyTaskHandoffWriteArchives(state, ctx);
+  if (state.receiverClaim) {
+    const { pass } = receiverClaim(state.receiverClaim, ctx, false);
+    const restored = state.receiverRestoration && receiverRestoration(state.receiverRestoration, state.receiverClaim, ctx, false);
+    const completion = state.receiverCompletion && completionReceipt(state.receiverCompletion, state.receiverClaim, ctx);
+    if (completion?.writeCheckpointReceipts && (canonical(completion.writeCheckpointReceipts) !== canonical(state.writeArchive.receipts)
+      || completion.writeCheckpointReceiptsDigest !== sha256(canonical(state.writeArchive.receipts)))) fail('completion proof dropped or changed trusted write history');
+    if (restored && (!completion || restored.completionIdleReceiptDigest !== sha256(canonical(completion))
+      || restored.baselineReceiptDigest !== sha256(canonical(completion)))) fail('receiver restoration lost its actual local completion proof');
+    if ((receiverCurrent(state) && (state.status !== (completion && !restored ? 'paused' : 'active') || state.epoch !== (restored ? restored.epoch : pass.receiverEpoch)))
+      || pass.receiverTaskId !== registration.taskId || pass.ownerId !== registration.ownerId
+      || pass.taskDigest !== registration.taskDigest || pass.chainDigest !== registration.chainDigest) fail('receiver takeover lost its actual original runner registration');
+  }
+  if (!receiverCurrent(state) && state.epoch > 0) {
+    const receipt = receiptSignature(state.releaseReceipt, ctx);
+    if (receipt.epoch !== state.epoch || canonical(receipt.revokedPassIds) !== canonical(state.revokedPassIds)
+      || canonical(receipt.revokedLeaseIds) !== canonical(state.revokedLeaseIds)) fail('handoff state revocation binding changed');
+    if (state.baselineReceipt) receiptSignature(state.baselineReceipt, ctx);
+    if (state.status === 'active') {
+      const resumed = authority(state.resumeAuthorization, RESUME_FIELDS, RESUME); lifetime(resumed, false);
+      if (!state.baselineReceipt || resumed.baselineReceiptDigest !== sha256(canonical(state.baselineReceipt)) || resumed.epoch !== state.epoch
+        || ['flowId', 'localRepositoryDigest', 'handoffId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'originalScopeDigest'].some(key => resumed[key] !== receipt[key])) fail('handoff resume authorization binding is invalid');
+    }
+  } else if (!receiverCurrent(state) && (state.status !== 'active' || state.releaseReceipt || state.resumeAuthorization)) fail('initial handoff state cannot be paused or resumed');
+  if (registration.flowId !== ctx.flowId || registration.localRepositoryDigest !== ctx.repo
+    || registration.runnerKeyId !== pinned('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY').keyId) fail('registered runner identity does not match the actual flow');
+  return state;
+}
+function active(state, input) {
+  if (state.status !== 'active') fail('source task is paused; mutation and new grants are revoked');
+  if (state.writeArchive?.pending) fail('unknown pending physical write prevents new activity');
+  if (state.writeArchive?.interrupted && !state.receiverRestoration) fail('three repeated native blocks interrupted the actual handoff; human direction is required');
+  if (epoch(input.epoch ?? 0) !== state.epoch || (input.passId && state.revokedPassIds.includes(input.passId))
+    || (input.leaseId && state.revokedLeaseIds.includes(input.leaseId))) fail('pass/lease epoch is revoked by the actual handoff');
+  if (state.receiverClaim && !state.receiverRestoration) {
+    const { pass, lease } = receiverClaim(state.receiverClaim, { flowId: state.flowId, repo: state.localRepositoryDigest });
+    if (input.passId !== pass.passId || input.leaseId !== lease.leaseId || input.handoffId !== pass.handoffId) fail('temporary receiver scope only accepts its fresh takeover pass and lease');
+    const paths = input.targetPath ? [input.targetPath] : input.paths;
+    if (!Array.isArray(paths) || !paths.length || paths.some(target => !pass.paths.includes(target))) fail('temporary takeover write is outside its exact path scope');
+  }
+  if (state.receiverRestoration) {
+    const paths = input.targetPath ? [input.targetPath] : input.paths;
+    if (paths && paths.some(target => !state.receiverRestoration.paths.includes(target))) fail('restored receiver can only mutate its original scope paths');
+  }
+}
+export async function readTaskHandoffFence(input) { return read(await context(input)); }
+async function mutationAuthority(ctx, state) {
+  const { assertTaskHandoffReadMutationAuthority } = await import('./local-task-handoff-read-authority.mjs');
+  await assertTaskHandoffReadMutationAuthority(ctx, state);
+}
+export async function assertTaskHandoffActive(input) {
+  const ctx = await context(input), state = await read(ctx); active(state, input);
+  await mutationAuthority(ctx, state); return state;
+}
+export async function withTaskHandoffWriteFence(input, callback) {
+  const ctx = await context(input, true);
+  return withStateLock(ctx.file, async () => { const state = await read(ctx); active(state, input);
+    await mutationAuthority(ctx, state);
+    return callback(state, { context: ctx, state, persist: async updated => {
+      await verifyTaskHandoffWriteArchives(updated, ctx); await atomic(ctx.file, updated);
+    } }); });
+}
+export async function withTaskHandoffReadFence(input, callback) {
+  const ctx = await context(input, true);
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx); active(state, input);
+    return callback(state, { authorizeMutation: () => mutationAuthority(ctx, state) });
+  });
+}
+export async function withTaskHandoffIssueFence(input, callback) {
+  const ctx = await context(input, true);
+  return withStateLock(ctx.file, async () => { const state = await read(ctx); active(state, { ...input, epoch: state.epoch });
+    await mutationAuthority(ctx, state); return callback(state); });
+}
+export function taskHandoffSnapshotBinding(state) {
+  const digest = receiverCurrent(state) ? state.receiverRestoration?.baselineReceiptDigest ?? state.receiverClaim.challenge.baselineReceiptDigest
+    : state.baselineReceipt ? sha256(canonical(state.baselineReceipt)) : state.releaseReceipt ? sha256(canonical(state.releaseReceipt)) : null;
+  return { handoffEpoch: epoch(state.epoch), handoffBaselineReceiptDigest: digest };
+}
+export async function readTaskHandoffSnapshotBinding(input) {
+  if (!process.env.ENTROROVE_TASK_HANDOFF_STATE_DIRECTORY) return {};
+  const ctx = await context(input); const registry = await readRegistry(ctx.registry);
+  if (input.handoffCandidate) {
+    const candidate = overlayAuthority(input.handoffCandidate, HANDOFF_CANDIDATE_FIELDS, 'entrorove.task-handoff-scope-challenge/1.0');
+    const current = registry.bindings[ctx.registryKey] ? await read(ctx) : fresh(ctx);
+    if (candidate.flowId !== ctx.flowId || candidate.localRepositoryDigest !== ctx.repo || candidate.stepId !== input.stepId
+      || candidate.runnerKeyId !== pinned('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY').keyId || candidate.receiverEpoch !== current.epoch + 1
+      || canonical(candidate.paths) !== canonical(input.paths)) fail('candidate snapshot requires the exact fresh cloud receiver scope challenge');
+    return { handoffEpoch: candidate.receiverEpoch, handoffBaselineReceiptDigest: candidate.baselineReceiptDigest };
+  }
+  if (!registry.bindings[ctx.registryKey]) return {};
+  const state = await read(ctx); return state.epoch > 0 ? taskHandoffSnapshotBinding(state) : {};
+}
+export function assertTaskHandoffSnapshotBinding(state, snapshot) {
+  const current = taskHandoffSnapshotBinding(state);
+  if (state.epoch > 0 && (snapshot?.handoffEpoch !== current.handoffEpoch
+    || snapshot?.handoffBaselineReceiptDigest !== current.handoffBaselineReceiptDigest)) fail('fresh snapshot must bind the confirmed handoff baseline and current epoch');
+  if (state.receiverRestoration && (!Array.isArray(snapshot?.paths)
+    || snapshot.paths.some(target => !state.receiverRestoration.paths.includes(target)))) fail('fresh snapshot cannot expand the restored original receiver scope');
+  return current;
+}
+export async function consumeTaskHandoffExecutionAuthority(input) {
+  const ctx = await context(input, true); const value = executionAuthority(input.authority);
+  const executionHome = await fs.realpath(ctx.home);
+  lifetime(value);
+  if (Date.parse(value.expiresAt) - Date.parse(value.issuedAt) > 30_000 || value.status !== 'active' || value.flowId !== ctx.flowId
+    || value.localRepositoryDigest !== ctx.repo || value.attemptNonce !== input.attemptNonce || value.leaseId !== input.leaseId
+    || value.generation !== input.generation || value.taskId !== input.taskId || value.runnerKeyId !== pinned('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY').keyId) fail('fresh execution authority does not match this actual nonce, lease and registered runner');
+  epoch(value.epoch); id(value.authorityId, 'authorityId'); id(value.attemptNonce, 'attemptNonce');
+  return withStateLock(ctx.registry, async () => {
+    const registry = await readRegistry(ctx.registry); const nonce = `execution:${value.runnerKeyId}:${value.attemptNonce}`;
+    const consumed = registry.consumed.includes(nonce);
+    const registered = registry.bindings[ctx.registryKey];
+    if (registered && ['taskId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId'].some(key => registered[key] !== value[key])) fail('execution authority changed its original registered task binding');
+    return withStateLock(ctx.file, async () => {
+      let state;
+      if (registered) {
+        state = await read(ctx); const takeover = state.receiverClaim && !state.receiverRestoration ? state.receiverClaim.pass : null;
+        if (takeover ? value.handoffId !== takeover.handoffId || value.writePassDigest !== sha256(canonical(takeover))
+          : value.handoffId !== undefined) fail('execution authority lost its actual temporary takeover identity and signed pass binding');
+        active(state, { epoch: value.epoch, leaseId: value.leaseId, ...(takeover ? { passId: takeover.passId,
+          handoffId: takeover.handoffId, paths: takeover.paths } : {}) });
+      }
+      else { if (value.epoch !== 0 || value.handoffId !== undefined) fail('lost handoff history cannot be recreated from an active epoch authority'); state = fresh(ctx); }
+      if (consumed) {
+        const ready = state.executionAttempts.find(item => item.authority.leaseId === value.leaseId
+          && item.authority.generation === value.generation && item.authority.attemptNonce === value.attemptNonce);
+        if (!registered || ready?.status !== 'ready' || canonical(ready.authority) !== canonical(input.authority)) fail('consumed nonce may only recover its exact original ready authority; used, revoked or unknown attempts cannot revive');
+        if (ready.executionHome !== executionHome) fail('ready recovery requires its original actual execution home');
+        await idle(ctx, state);
+        return { epoch: state.epoch, baselineReceiptDigest: taskHandoffSnapshotBinding(state).handoffBaselineReceiptDigest };
+      }
+      const binding = Object.fromEntries(['taskId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId', 'localRepositoryDigest'].map(key => [key, value[key]]));
+      if (state.executionAttempts.some(item => item.authority.leaseId === value.leaseId && item.authority.generation === value.generation)) fail('original lease/generation already has an actual attempt; reconcile its outcome instead of spawning again');
+      if (state.executionAttempts.length >= 1024) fail('actual execution attempt registry is full; reconcile its retained history');
+      await atomic(ctx.registry, { ...registry, consumed: [...registry.consumed, nonce], bindings: { ...registry.bindings, [ctx.registryKey]: binding } });
+      await atomic(ctx.file, { ...state, executionAttempts: [...state.executionAttempts, { authority: input.authority, status: 'ready', executionHome }] });
+      return { epoch: state.epoch, baselineReceiptDigest: taskHandoffSnapshotBinding(state).handoffBaselineReceiptDigest };
+    });
+  });
+}
+export async function applyTaskHandoffReceiverClaim(input) {
+  const ctx = await context(input, true); const claim = { pass: input.pass, lease: input.lease, challenge: input.challenge };
+  const accepted = receiverClaim(claim, ctx); const { pass, lease, challenge } = accepted;
+  if (pinned('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY').keyId !== pass.runnerKeyId) fail('receiver takeover runner is not the configured trusted runner');
+  return withStateLock(ctx.registry, () => withStateLock(ctx.file, async () => {
+    const registry = await readRegistry(ctx.registry); const registered = registry.bindings[ctx.registryKey];
+    const state = registered ? await read(ctx) : fresh(ctx);
+    if (state.receiverClaim && canonical(state.receiverClaim) === canonical(claim)) return state;
+    if (state.receiverClaim && !state.receiverRestoration) fail('receiver already has one active scoped takeover');
+    if (state.status !== 'active' || pass.receiverEpoch !== state.epoch + 1) fail('receiver takeover epoch must advance its actual original state exactly once');
+    if (registered && ['ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId'].some(key => registered[key] !== pass[key])) fail('receiver takeover changed its original task binding');
+    if (registered && registered.taskId !== pass.receiverTaskId) fail('receiver takeover belongs to another original task');
+    await idle(ctx, state);
+    if ((await fingerprints(ctx, pass.paths)).digest !== pass.scopeFingerprintDigest) fail('receiver takeover fingerprints changed from its fresh signed scope');
+    const manifest = await json(path.join(ctx.home, '.entrorove/snapshots', ctx.repo, ctx.flowId, pass.snapshotId, 'manifest.json'));
+    if (manifest.snapshotDigest !== pass.scopeSnapshotDigest || manifest.handoffEpoch !== pass.receiverEpoch
+      || manifest.handoffBaselineReceiptDigest !== challenge.baselineReceiptDigest) fail('receiver takeover requires its actual fresh candidate snapshot and release baseline binding');
+    const revoked = await revocations(ctx, state);
+    if (!registered) {
+      const binding = { taskId: pass.receiverTaskId, flowId: pass.flowId, ownerId: pass.ownerId, taskDigest: pass.taskDigest,
+        chainDigest: pass.chainDigest, runnerKeyId: pass.runnerKeyId, localRepositoryDigest: pass.localRepositoryDigest };
+      await atomic(ctx.registry, { ...registry, bindings: { ...registry.bindings, [ctx.registryKey]: binding } });
+    }
+    if (state.writeArchive?.pending) fail('unknown prior physical write prevents a new scoped takeover');
+    const writeArchive = newHandoffWriteArchive(claim, manifest, ctx);
+    const updated = { ...state, writeArchive, writeArchiveHistory: [...state.writeArchiveHistory, ...(state.writeArchive ? [state.writeArchive] : [])],
+      epoch: pass.receiverEpoch, revokedPassIds: revoked.passes, revokedLeaseIds: revoked.leases,
+      receiverClaim: claim, receiverRestoration: null, receiverCompletion: null,
+      executionAttempts: state.executionAttempts.map(item => item.status === 'ready' ? { ...item, status: 'revoked' } : item) };
+    await verifyTaskHandoffWriteArchives(updated, ctx); await atomic(ctx.file, updated); return updated;
+  }));
+}
+export async function restoreTaskHandoffReceiverScope(input) {
+  const ctx = await context(input, true);
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx);
+    if (state.receiverRestoration && canonical(state.receiverRestoration) === canonical(input.authorization)) return state;
+    if (!state.receiverClaim || state.receiverRestoration || !state.receiverCompletion || state.status !== 'paused') fail('receiver requires its actual completed idle/revocation proof before restoring scope');
+    const restored = receiverRestoration(input.authorization, state.receiverClaim, ctx); await idle(ctx, state);
+    const proof = completionReceipt(state.receiverCompletion, state.receiverClaim, ctx);
+    if (!Array.isArray(proof.writeCheckpointReceipts)) fail('legacy completion receipt cannot restore live receiver write authority');
+    if (restored.completionIdleReceiptDigest !== sha256(canonical(proof)) || restored.baselineReceiptDigest !== sha256(canonical(proof))) fail('cloud restoration did not commit this actual local completion proof');
+    if ((await fingerprints(ctx, proof.paths)).digest !== proof.scopeFingerprintDigest) fail('actual completion fingerprint changed before confirmed receiver restoration');
+    const updated = { ...state, status: 'active', epoch: restored.epoch, revokedPassIds: [...new Set([...state.revokedPassIds, ...restored.revokedPassIds])].sort(),
+      revokedLeaseIds: [...new Set([...state.revokedLeaseIds, ...restored.revokedLeaseIds])].sort(), receiverRestoration: input.authorization };
+    await atomic(ctx.file, updated); return updated;
+  });
+}
+export async function observeTaskHandoffReceiverCompletion(input) {
+  const ctx = await context(input, true);
+  const budget = await import('./local-budget-handoff-completion.mjs');
+  if (!budget.isBudgetHandoffCompletionObservation(input)) return budget.observeBudgetedTaskHandoffReceiverCompletion(input);
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx);
+    if (!state.receiverClaim || state.receiverRestoration) fail('completion requires its actual current receiver takeover');
+    const challenge = completionChallenge(input.challenge, state.receiverClaim, ctx, false);
+    if (state.receiverCompletion?.receipt.challengeId === challenge.challengeId) {
+      if (state.receiverCompletion.receipt.challengeDigest !== sha256(canonical(challenge))) fail('completion challenge replay binding changed');
+      return state.receiverCompletion.receipt;
+    }
+    lifetime(challenge);
+    if (state.receiverCompletion && Date.parse(state.receiverCompletion.receipt.expiresAt) > Date.now()) fail('completion is already locally paused; only its known expired challenge may renew');
+    const workflowStateDigest = await idle(ctx, state), observed = await fingerprints(ctx, challenge.paths);
+    const writeBatch = await handoffWriteCompletionBatch(state, ctx, observed.files);
+    const key = await signer(ctx, input.signerConfigPath, challenge.runnerKeyId), revoked = await revocations(ctx, state);
+    const revokedPassIds = [...new Set([...revoked.passes, challenge.passId])].sort();
+    const revokedLeaseIds = [...new Set([...revoked.leases, challenge.leaseId])].sort();
+    const core = completionReceiptCore(challenge, { receiptId: randomUUID(), nonce: randomUUID(), files: observed.files,
+      scopeFingerprintDigest: observed.digest, workflowStateDigest, revokedPassIds, revokedLeaseIds, ...writeBatch }, key.config.keyId, key.config.receiptTtlMs);
+    const receipt = { ...core, signature: sign(null, Buffer.from(canonical(core)), key.privateKey).toString('base64url') };
+    const proof = { challenge: input.challenge, receipt }; completionReceipt(proof, state.receiverClaim, ctx, true);
+    await atomic(ctx.file, { ...state, status: 'paused', receiverCompletion: proof, revokedPassIds, revokedLeaseIds,
+      executionAttempts: state.executionAttempts.map(item => item.status === 'ready' ? { ...item, status: 'revoked' } : item) });
+    return receipt;
+  });
+}
+export async function beginTaskHandoffExecution(input) {
+  const ctx = await context(input, true);
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx); active(state, input); const executionId = id(input.executionId, 'executionId');
+    if (state.activities.some(item => item.executionId === executionId)) fail('execution already has an in-flight registration');
+    if (state.activities.length >= 128) fail('handoff in-flight registry is full');
+    const ready = state.executionAttempts.find(item => item.status === 'ready' && item.authority.leaseId === input.leaseId
+      && item.authority.generation === input.generation && item.authority.attemptNonce === input.attemptNonce);
+    if (!ready) fail('actual execution needs its ready fresh cloud lease/generation/nonce authority');
+    if (ready.executionHome !== await fs.realpath(ctx.home)) fail('actual execution requires its original ready authority execution home');
+    const payload = executionAuthority(ready.authority); lifetime(payload);
+    if (payload.epoch !== state.epoch || payload.flowId !== ctx.flowId || payload.localRepositoryDigest !== ctx.repo) fail('ready execution authority is revoked or outside this actual flow');
+    const activity = { executionId, stepId: id(input.stepId, 'stepId'), leaseId: id(input.leaseId, 'leaseId'), token: randomUUID(),
+      epoch: state.epoch, pid: process.pid, startedAt: new Date().toISOString() };
+    await atomic(ctx.file, { ...state, activities: [...state.activities, activity],
+      executionAttempts: state.executionAttempts.map(item => item === ready ? { ...item, status: 'used', executionId } : item) });
+    return { ...activity, authority: ready.authority };
+  });
+}
+export async function finishTaskHandoffExecution(input) {
+  const ctx = await context(input, true);
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx); const item = state.activities.find(value => value.executionId === input.executionId);
+    if (!item || item.token !== input.token || item.pid !== process.pid) fail('in-flight execution ownership token is invalid');
+    await atomic(ctx.file, { ...state, activities: state.activities.filter(value => value !== item) });
+  });
+}
+function boundChallenge(ctx, challenge, purpose) {
+  const value = authority(challenge, CHALLENGE_FIELDS, CHALLENGE); lifetime(value, false);
+  for (const name of ['challengeId', 'handoffId', 'messageRequestId', 'taskId', 'flowId', 'ownerId', 'checkpointReceiptId']) id(value[name], name);
+  for (const name of ['taskDigest', 'chainDigest', 'checkpointDigest', 'originalScopeDigest', 'repositoryFactsDigest', 'scopeSnapshotDigest', 'runnerKeyId']) {
+    if (typeof value[name] !== 'string' || !SHA.test(value[name])) fail(`handoff ${name} digest is invalid`);
+  }
+  epoch(value.expectedEpoch);
+  if (value.purpose !== purpose || value.flowId !== ctx.flowId || value.localRepositoryDigest !== ctx.repo) fail('handoff purpose/repository binding is invalid');
+  if (!Array.isArray(value.paths) || !value.paths.length || value.paths.length > 512
+    || new Set(value.paths.map(safePath)).size !== value.paths.length || canonical([...value.paths].sort()) !== canonical(value.paths)) fail('handoff paths must be unique exact sorted file paths');
+  if (pinned('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY').keyId !== value.runnerKeyId) fail('handoff runner identity does not match its trusted pin');
+  return value;
+}
+async function entries(directory) {
+  try { const stat = await fs.lstat(directory); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('actual local state directory must be real');
+    const names = await fs.readdir(directory); if (names.length > 4096) fail('actual local state exceeds its bounded limit'); return names.sort(); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+}
+async function idle(ctx, state) {
+  if (state.activities.length) fail('actual in-flight execution prevents an idle handoff');
+  const directory = path.join(ctx.home, '.entrorove/workflow-local', ctx.repo, ctx.flowId); const observed = [];
+  for (const step of await entries(directory)) {
+    id(step, 'actual step'); const row = await json(path.join(directory, step, 'state.json'));
+    if (row.flowId !== ctx.flowId || row.repositoryDigest !== ctx.repo || row.stepId !== step) fail('actual workflow state identity is invalid');
+    if (row.status === 'running') fail('actual running/unknown workflow cannot be released, even after lease or PID expiry');
+    if (!['reported', 'failed'].includes(row.status) || !row.finishedAt || !row.result || row.resultDigest !== sha256(canonical(row.result))) fail('actual workflow outcome is unknown');
+    observed.push({ stepId: step, status: row.status, resultDigest: row.resultDigest, leaseId: row.leaseId });
+  }
+  return sha256(canonical(observed));
+}
+async function revocations(ctx, state) {
+  const directory = path.join(ctx.home, '.entrorove/gates', ctx.repo, ctx.flowId); const passes = [];
+  for (const name of await entries(directory)) {
+    if (!name.endsWith('.json')) fail('actual pass state contains an unknown file');
+    const pass = await json(path.join(directory, name));
+    if (pass.flowId !== ctx.flowId || pass.repositoryDigest !== ctx.repo || name !== `${id(pass.passId, 'passId')}.json`) fail('actual pass binding is invalid');
+    passes.push(pass.passId);
+  }
+  const file = path.join(ctx.home, '.entrorove/coordination', ctx.repo, ctx.flowId, 'state.json');
+  return withStateLock(file, async () => {
+    let value; try { value = await json(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const leases = state.executionAttempts.filter(item => item.status === 'ready').map(item => item.authority.leaseId);
+    if (value) {
+      if (value.schemaVersion !== 'entrorove.coordination/1.0' || value.flowId !== ctx.flowId || value.repositoryDigest !== ctx.repo
+        || !Array.isArray(value.workers) || !Array.isArray(value.leases) || !Array.isArray(value.events)) fail('actual coordination state is invalid');
+      const revoke = worker => { if (worker.status !== 'active') return worker; leases.push(id(worker.leaseId, 'leaseId'));
+        return { ...worker, status: 'revoked', revokedAt: new Date().toISOString() }; };
+      await atomic(file, { ...value, workers: value.workers.map(revoke), leases: value.leases.map(revoke),
+        events: [...value.events, { event: 'handoff-revoked', at: new Date().toISOString() }] });
+    }
+    return { passes: [...new Set([...state.revokedPassIds, ...passes])].sort(), leases: [...new Set([...state.revokedLeaseIds, ...leases])].sort() };
+  });
+}
+function signedReceipt(challenge, key, data) {
+  const now = Date.now(); const core = { schemaVersion: 'entrorove.task-handoff-idle-receipt/1.0',
+    purpose: challenge.purpose, status: 'paused', challengeId: challenge.challengeId, challengeDigest: sha256(canonical(challenge)),
+    handoffId: challenge.handoffId, taskId: challenge.taskId, flowId: challenge.flowId, ownerId: challenge.ownerId,
+    taskDigest: challenge.taskDigest, chainDigest: challenge.chainDigest, checkpointReceiptId: challenge.checkpointReceiptId,
+    checkpointDigest: challenge.checkpointDigest, originalScopeDigest: challenge.originalScopeDigest,
+    localRepositoryDigest: challenge.localRepositoryDigest, repositoryFactsDigest: challenge.repositoryFactsDigest,
+    scopeSnapshotDigest: challenge.scopeSnapshotDigest, paths: challenge.paths, ...data,
+    keyId: key.config.keyId, nonce: randomUUID(), issuedAt: new Date(now).toISOString(),
+    expiresAt: new Date(Math.min(now + key.config.receiptTtlMs, Date.parse(challenge.expiresAt))).toISOString() };
+  return { ...core, signature: sign(null, Buffer.from(canonical(core)), key.privateKey).toString('base64url') };
+}
+export async function releaseTaskHandoffFence(input) {
+  const ctx = await context(input, true); const challenge = boundChallenge(ctx, input.challenge, 'release');
+  return withStateLock(ctx.registry, () => withStateLock(ctx.file, async () => {
+    const registry = await readRegistry(ctx.registry); const registration = registry.bindings[ctx.registryKey];
+    const state = registration ? await read(ctx) : fresh(ctx); const digest = sha256(canonical(challenge));
+    if (state.releaseReceipt?.challengeId === challenge.challengeId) {
+      if (state.releaseReceipt.challengeDigest !== digest) fail('handoff challenge replay binding changed'); return state.releaseReceipt;
+    }
+    lifetime(challenge);
+    const renewPaused = state.status === 'paused' && state.epoch === challenge.expectedEpoch + 1;
+    if (renewPaused) {
+      if (Date.parse(state.releaseReceipt?.expiresAt) > Date.now()) fail('source is already paused with a current receipt; only a known expired authority may renew');
+      if (!state.releaseReceipt || ['handoffId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'checkpointReceiptId',
+        'checkpointDigest', 'originalScopeDigest', 'localRepositoryDigest', 'repositoryFactsDigest', 'scopeSnapshotDigest'].some(key => state.releaseReceipt[key] !== challenge[key])
+        || canonical(state.releaseReceipt.paths) !== canonical(challenge.paths)) fail('paused release retry must preserve the exact original binding');
+    } else active(state, { epoch: challenge.expectedEpoch, paths: challenge.paths });
+    if (state.receiverRestoration && challenge.originalScopeDigest !== state.receiverRestoration.receiverOriginalScopeDigest) fail('source handoff must preserve the actually restored original scope contract');
+    if (registration && ['taskId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId'].some(key => registration[key] !== challenge[key])) fail('release challenge changed its original runner registration');
+    if (!registration && challenge.expectedEpoch !== 0) fail('lost handoff history cannot bootstrap from a later release epoch');
+    const key = await signer(ctx, input.signerConfigPath, challenge.runnerKeyId); const workflowStateDigest = await idle(ctx, state);
+    if ((await fingerprints(ctx, challenge.paths)).digest !== challenge.scopeSnapshotDigest) fail('actual scoped fingerprint changed from the authoritative snapshot');
+    const revoked = renewPaused ? { passes: state.revokedPassIds, leases: state.revokedLeaseIds } : await revocations(ctx, state);
+    const nextEpoch = renewPaused ? state.epoch : state.epoch + 1;
+    const receipt = signedReceipt(challenge, key, { epoch: nextEpoch,
+      workflowStateDigest, revokedPassIds: revoked.passes, revokedLeaseIds: revoked.leases });
+    if (!registration) {
+      const binding = Object.fromEntries(['taskId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId', 'localRepositoryDigest'].map(key => [key, challenge[key]]));
+      await atomic(ctx.registry, { ...registry, bindings: { ...registry.bindings, [ctx.registryKey]: binding } });
+    }
+    await atomic(ctx.file, { ...state, status: 'paused', epoch: nextEpoch, revokedPassIds: revoked.passes,
+      revokedLeaseIds: revoked.leases, releaseReceipt: receipt, baselineReceipt: null, resumeAuthorization: null,
+      executionAttempts: state.executionAttempts.map(item => item.status === 'ready' ? { ...item, status: 'revoked' } : item) }); return receipt;
+  }));
+}
+export async function observeTaskHandoffBaseline(input) {
+  const ctx = await context(input, true); const challenge = boundChallenge(ctx, input.challenge, 'resume');
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx); const original = state.releaseReceipt;
+    if (state.baselineReceipt?.challengeId === challenge.challengeId) {
+      if (state.baselineReceipt.challengeDigest !== sha256(canonical(challenge))) fail('baseline challenge replay binding changed'); return state.baselineReceipt;
+    }
+    if (state.status !== 'paused' || state.epoch !== challenge.expectedEpoch || !original
+      || ['handoffId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'originalScopeDigest'].some(key => original[key] !== challenge[key])
+      || canonical(original.paths) !== canonical(challenge.paths)) fail('resume baseline must bind the paused original task');
+    lifetime(challenge); const key = await signer(ctx, input.signerConfigPath, challenge.runnerKeyId); const workflowStateDigest = await idle(ctx, state);
+    if ((await fingerprints(ctx, challenge.paths)).digest !== challenge.scopeSnapshotDigest) fail('fresh actual baseline fingerprint does not match authoritative scope snapshot');
+    const receipt = signedReceipt(challenge, key, { epoch: state.epoch, workflowStateDigest, revokedPassIds: state.revokedPassIds, revokedLeaseIds: state.revokedLeaseIds });
+    await atomic(ctx.file, { ...state, baselineReceipt: receipt }); return receipt;
+  });
+}
+export async function restoreTaskHandoffFence(input) {
+  const ctx = await context(input, true); const authorization = authority(input.authorization, RESUME_FIELDS, RESUME);
+  return withStateLock(ctx.file, async () => {
+    const state = await read(ctx); const baseline = state.baselineReceipt;
+    if (state.resumeAuthorization && canonical(state.resumeAuthorization) === canonical(input.authorization)) return state;
+    lifetime(authorization);
+    if (state.status !== 'paused' || !baseline || authorization.epoch !== state.epoch || authorization.baselineReceiptDigest !== sha256(canonical(baseline))
+      || authorization.baselineChallengeId !== baseline.challengeId || ['handoffId', 'taskId', 'flowId', 'ownerId', 'localRepositoryDigest',
+        'taskDigest', 'chainDigest', 'originalScopeDigest', 'scopeSnapshotDigest'].some(key => authorization[key] !== baseline[key])) fail('confirmed resume authorization is outside the original task/baseline');
+    await idle(ctx, state);
+    if ((await fingerprints(ctx, baseline.paths)).digest !== authorization.scopeSnapshotDigest) fail('actual baseline changed before confirmed resume');
+    const restored = { ...state, status: 'active', resumeAuthorization: input.authorization }; await atomic(ctx.file, restored); return restored;
+  });
+}

package/local-task-handoff-observation.mjs

@@ -0,0 +1,38 @@
+import { createPrivateKey, createPublicKey } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { regular } from './local-task-handoff-storage.mjs';
+import { scopeRead, scopeTarget, lineCount } from './local-scope-files.mjs';
+
+function fail(message) { throw Object.assign(new Error(message), { code: 'ENTROROVE_HANDOFF_FENCE' }); }
+export async function loadTaskHandoffSigner(ctx, file, keyId) {
+  async function control(target) {
+    if (typeof target !== 'string' || !path.isAbsolute(target)) fail('runner signer controls are unavailable; an external absolute configuration is required');
+    const actual = await fs.realpath(target), relative = path.relative(ctx.root, actual);
+    if (actual !== path.resolve(target) || relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))) fail('runner signer controls must be external real files');
+    const value = await regular(target, 16 * 1024);
+    if ((process.platform !== 'win32' && (value.stat.mode & 0o077)) || (typeof process.getuid === 'function' && value.stat.uid !== process.getuid())) fail('runner signer controls must be owned private files');
+    return value.bytes;
+  }
+  const config = JSON.parse((await control(file)).toString('utf8'));
+  if (Object.keys(config).sort().join('\0') !== ['schemaVersion', 'privateKeyPath', 'keyId', 'receiptTtlMs'].sort().join('\0')
+    || config.schemaVersion !== 'validator.runner-signer/1.0' || config.keyId !== keyId
+    || !Number.isSafeInteger(config.receiptTtlMs) || config.receiptTtlMs < 1 || config.receiptTtlMs > 90_000) fail('runner signer configuration is invalid');
+  const privateKey = createPrivateKey(await control(config.privateKeyPath));
+  const der = createPublicKey(privateKey).export({ type: 'spki', format: 'der' });
+  if (privateKey.asymmetricKeyType !== 'ed25519' || sha256(der) !== keyId
+    || der.toString('base64') !== process.env.ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY) fail('runner signer identity is not the configured trusted receiver');
+  return { privateKey, config };
+}
+export async function taskHandoffFingerprints(ctx, paths) {
+  const files = []; let total = 0;
+  for (const relative of paths) {
+    const actual = await scopeTarget(ctx.root, relative, true);
+    if (!actual.exists) { files.push({ path: relative, sha256: sha256(''), bytes: 0, lines: 0, exists: false }); continue; }
+    const observed = await scopeRead(ctx.root, relative, { home: ctx.home, repositoryRoot: ctx.root, flowId: ctx.flowId }); total += observed.bytes;
+    if (total > 16 * 1024 * 1024) fail('scope snapshot observation exceeds its limit');
+    files.push({ path: relative, sha256: observed.sha256, bytes: observed.bytes, lines: lineCount(observed.content) });
+  }
+  return { files, digest: sha256(canonical(files)) };
+}