codex-workflow-v2 2.0.0-beta.13.8 → 2.0.0-beta.14

package/src/alpha6/handoff.ts

@@ -0,0 +1,1443 @@
+import os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import type {
+  MilestoneDependencyBinding,
+  TaskCoordinationLevel,
+  TaskHandbackRecord,
+  TaskHandoffBundle,
+  TaskHandoffEvent,
+  TaskHandoffEventType,
+  TaskState,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import type { FileStateStore } from '../state/store.js';
+import { createUlid } from '../ulid.js';
+import {
+  assertNoSymlinkPathComponents,
+  computeSidecarEventHash,
+  prepareSidecarAppend,
+  sha256Hex,
+} from './store-sidecars.js';
+
+const HANDOFF_SIDECAR = 'handoffs.jsonl';
+const NON_TERMINAL_TASK_STATUSES = new Set<TaskState['status']>([
+  'planning',
+  'awaiting_execution_authorization',
+  'ready',
+  'in_progress',
+  'validating',
+  'blocked',
+  'needs_fix',
+  'awaiting_final_acceptance',
+  'ready_to_merge',
+  'merging',
+]);
+const HANDOFF_EVENT_TYPES = new Set<TaskHandoffEventType>(['handoff', 'claim', 'credential-replace', 'yield', 'handback']);
+const COORDINATION_LEVEL: TaskCoordinationLevel = 'C1';
+
+export type TaskC1Posture =
+  | { state: 'none'; latestEvent: TaskHandoffEvent | null }
+  | { state: 'pending'; latestEvent: TaskHandoffEvent; targetActor: string }
+  | { state: 'claimed'; latestEvent: TaskHandoffEvent; claimant: string; writerLeaseTokenHash: string | null };
+
+export interface TaskMutationAuthority {
+  actor: string;
+  writerToken: string | null;
+}
+
+export interface PrepareTaskHandoffInput {
+  actor: string;
+  targetActor: string;
+  reason: string;
+  writerToken: string | null;
+  milestoneDisplayNumber: number | null;
+  taskDisplayNumber: number | null;
+  dependencyBinding: MilestoneDependencyBinding | null;
+  expectedNext: string;
+  grantId: string | null;
+  expiresAt: string;
+  replacePending: boolean;
+}
+
+export interface PreparedTaskCorrectiveYield {
+  readonly event: TaskHandoffEvent;
+  readonly postimage: Buffer;
+}
+
+/**
+ * Materializes the exact append-only coordination effect without writing it. The caller must own
+ * the resulting bytes in a durable Task transaction before publishing them.
+ */
+export function prepareTaskCorrectiveYield(
+  store: FileStateStore,
+  task: TaskState,
+  input: { actor: string; writerToken: string; reason: string; eventId: string },
+  now: Date,
+): PreparedTaskCorrectiveYield {
+  assertTaskSupportsC1Handoff(task);
+  if (task.steps.some((step) => step.status === 'in_progress')) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} cannot yield while a Step is in progress.`, {
+      taskId: task.id,
+    });
+  }
+  const actor = normalizeActor(input.actor, 'Yield actor');
+  const reason = normalizeReason(input.reason);
+  if (typeof input.writerToken !== 'string' || input.writerToken.length === 0) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective yield requires the claimant writer token.');
+  }
+  if (typeof input.eventId !== 'string' || !/^HOF-[a-f0-9]{64}$/.test(input.eventId)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective yield eventId must bind the transaction SHA-256.');
+  }
+  const events = readTaskHandoffEvents(store, task);
+  const posture = readTaskC1Posture(store, task);
+  const writerLeaseTokenHash = sha256Hex(input.writerToken);
+  if (posture.state !== 'claimed' || posture.claimant !== actor
+    || posture.writerLeaseTokenHash !== writerLeaseTokenHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} corrective yield requires the exact active claimant and lease.`, {
+      taskId: task.id,
+      posture: posture.state,
+      actor,
+    });
+  }
+  const prepared = prepareSidecarAppend<TaskHandoffEvent>(events, {
+    eventId: input.eventId,
+    recordedAt: now.toISOString(),
+    ...contextFromEvent(posture.latestEvent),
+    taskId: task.id,
+    taskRevision: task.revision,
+    eventType: 'yield',
+    coordinationLevel: COORDINATION_LEVEL,
+    actor,
+    targetActor: null,
+    machineEvidence: {
+      hostname: os.hostname(),
+      pid: process.pid,
+      platform: process.platform,
+      arch: process.arch,
+      nodeVersion: process.version,
+    },
+    writerLeaseTokenHash,
+    reason,
+    handback: null,
+  }, {
+    validateEvent: (event, context) => validateStoredTaskHandoffEvent(event, task, context.file, context.line),
+  });
+  validateTaskHandoffHistory([...events, prepared.event], task);
+  return { event: structuredClone(prepared.event), postimage: Buffer.from(prepared.content, 'utf8') };
+}
+
+export function defaultTaskWorkerActor(taskId: string): string {
+  if (!/^TASK-[0-9A-HJKMNP-TV-Z]{26}$/.test(taskId)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Cannot derive a C1 Worker actor from invalid Task ID ${taskId}.`);
+  }
+  return `agent:worker:${taskId.toLowerCase()}`;
+}
+
+export function readTaskHandoffEvents(
+  store: FileStateStore,
+  task: TaskState,
+): TaskHandoffEvent[] {
+  const sidecarPath = path.join(resolveAlpha6TaskRoot(store, task), HANDOFF_SIDECAR);
+  assertNoSymlinkPathComponents(sidecarPath, { label: 'Task handoff sidecar path', requireLeaf: true });
+  if (!existsSync(sidecarPath)) return [];
+  const events = parseTaskHandoffEvents(readFileSync(sidecarPath, 'utf8'), task, sidecarPath);
+  validateTaskHandoffHistory(events, task);
+  return events;
+}
+
+export function readTaskC1Posture(
+  store: FileStateStore,
+  task: TaskState,
+): TaskC1Posture {
+  const events = readTaskHandoffEvents(store, task);
+  const latestEvent = events.at(-1) ?? null;
+  if (!latestEvent) return { state: 'none', latestEvent: null };
+  if (latestEvent.eventType === 'handoff') {
+    return {
+      state: 'pending',
+      latestEvent,
+      targetActor: latestEvent.targetActor!,
+    };
+  }
+  if (latestEvent.eventType === 'claim' || latestEvent.eventType === 'credential-replace') {
+    return {
+      state: 'claimed',
+      latestEvent,
+      claimant: latestEvent.actor.trim(),
+      writerLeaseTokenHash: latestEvent.writerLeaseTokenHash,
+    };
+  }
+  return { state: 'none', latestEvent };
+}
+
+export function appendTaskHandoff(
+  store: FileStateStore,
+  task: TaskState,
+  input: PrepareTaskHandoffInput,
+  now: Date,
+): { event: TaskHandoffEvent; bundle: TaskHandoffBundle } {
+  assertTaskSupportsC1Handoff(task);
+  const normalizedActor = normalizeActor(input.actor, 'Handoff actor');
+  const normalizedTargetActor = normalizeActor(input.targetActor, 'Handoff target actor');
+  if (normalizedActor === normalizedTargetActor) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'C1 handoff target must differ from the current actor.', {
+      taskId: task.id,
+      actor: normalizedActor,
+      targetActor: normalizedTargetActor,
+    });
+  }
+  const normalizedReason = normalizeReason(input.reason);
+  const expiresAt = normalizeFutureExpiry(input.expiresAt, now);
+  const posture = readTaskC1Posture(store, task);
+  if (posture.state === 'pending') {
+    if (!input.replacePending) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} already has a pending C1 handoff.`, {
+        taskId: task.id,
+        targetActor: posture.targetActor,
+        eventId: posture.latestEvent.eventId,
+      });
+    }
+    if (
+      normalizedActor !== posture.latestEvent.actor.trim()
+      || normalizedTargetActor !== posture.targetActor
+      || input.grantId !== posture.latestEvent.grantId
+    ) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Pending C1 handoff ${posture.latestEvent.handoffId} may only replace its lost credential without changing authority.`, {
+        taskId: task.id,
+        handoffId: posture.latestEvent.handoffId,
+        requiredActor: posture.latestEvent.actor,
+        requiredTargetActor: posture.targetActor,
+        requiredGrantId: posture.latestEvent.grantId,
+      });
+    }
+  } else if (input.replacePending) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} does not have a pending C1 handoff credential to replace.`, {
+      taskId: task.id,
+      posture: posture.state,
+    });
+  }
+  if (posture.state === 'claimed' && posture.claimant !== normalizedActor) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Only claimant ${posture.claimant} may initiate a new handoff for Task ${task.id}.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+      actor: normalizedActor,
+    });
+  }
+  const leaseTokenHash = input.writerToken ? sha256Hex(input.writerToken) : null;
+  if (posture.state === 'claimed' && posture.writerLeaseTokenHash !== leaseTokenHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} handoff requires the claimant's bound writer lease token.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+      expectedWriterLeaseTokenHash: posture.writerLeaseTokenHash,
+      actualWriterLeaseTokenHash: leaseTokenHash,
+    });
+  }
+  const claimToken = randomBytes(32).toString('base64url');
+  const handoffId = `THO-${createUlid(now.getTime())}`;
+  const context = {
+    handoffId,
+    milestoneId: task.milestoneId,
+    milestoneDisplayNumber: input.milestoneDisplayNumber,
+    taskDisplayNumber: input.taskDisplayNumber,
+    briefHash: task.briefHash,
+    planHash: task.planHash,
+    knowledgeMapRevision: task.knowledgeMapRevision,
+    knowledgeMapHash: task.knowledgeMapHash,
+    dependencyBinding: input.dependencyBinding,
+    expectedNext: normalizeReason(input.expectedNext),
+    delegate: normalizedTargetActor,
+    grantId: input.grantId,
+    claimTokenHash: sha256Hex(claimToken),
+    expiresAt,
+  };
+  const event = appendTaskHandoffEvent(store, task, {
+    eventType: 'handoff',
+    actor: normalizedActor,
+    targetActor: normalizedTargetActor,
+    writerLeaseTokenHash: leaseTokenHash,
+    reason: normalizedReason,
+    context,
+    handback: null,
+  }, now);
+  return {
+    event,
+    bundle: {
+      handoffId,
+      milestoneId: task.milestoneId,
+      milestoneDisplayNumber: input.milestoneDisplayNumber,
+      taskId: task.id,
+      taskDisplayNumber: input.taskDisplayNumber,
+      taskRevision: task.revision,
+      briefHash: task.briefHash,
+      planHash: task.planHash,
+      knowledgeMapRevision: task.knowledgeMapRevision,
+      knowledgeMapHash: task.knowledgeMapHash,
+      dependencyBinding: input.dependencyBinding,
+      expectedNext: context.expectedNext,
+      delegate: normalizedTargetActor,
+      grantId: input.grantId,
+      claimToken,
+      createdAt: now.toISOString(),
+      expiresAt,
+      prompt: buildTaskHandoffPrompt(task, context.expectedNext, normalizedTargetActor),
+    },
+  };
+}
+
+export function appendTaskClaim(
+  store: FileStateStore,
+  task: TaskState,
+  actor: string,
+  claimToken: string,
+  writerToken: string | null,
+  now: Date,
+  expectedDependencyBinding?: MilestoneDependencyBinding | null,
+): TaskHandoffEvent {
+  if (writerToken === null) {
+    const normalizedActor = normalizeActor(actor, 'Claim actor');
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} claim requires a bound writer lease token.`, {
+      taskId: task.id,
+      actor: normalizedActor,
+    });
+  }
+  const posture = assertTaskClaimAllowed(store, task, actor, claimToken, now, expectedDependencyBinding);
+  const normalizedActor = normalizeActor(actor, 'Claim actor');
+  return appendTaskHandoffEvent(store, task, {
+    eventType: 'claim',
+    actor: normalizedActor,
+    targetActor: null,
+    writerLeaseTokenHash: sha256Hex(writerToken),
+    reason: `Claimed pending C1 handoff from ${posture.latestEvent.actor}.`,
+    context: contextFromEvent(posture.latestEvent),
+    handback: null,
+  }, now);
+}
+
+export function appendTaskWriterCredentialReplacement(
+  store: FileStateStore,
+  task: TaskState,
+  actor: string,
+  writerToken: string,
+  now: Date,
+): TaskHandoffEvent {
+  const posture = readTaskC1Posture(store, task);
+  const normalizedActor = normalizeActor(actor, 'Writer credential replacement actor');
+  if (posture.state !== 'claimed' || posture.claimant !== normalizedActor) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} writer credential replacement requires the exact active claimant.`, {
+      taskId: task.id,
+      posture: posture.state,
+      claimant: posture.state === 'claimed' ? posture.claimant : null,
+      actor: normalizedActor,
+    });
+  }
+  if (!writerToken) throw new WorkflowError('INVALID_ARGUMENT', 'Replacement writer credential is required.');
+  return appendTaskHandoffEvent(store, task, {
+    eventType: 'credential-replace',
+    actor: normalizedActor,
+    targetActor: null,
+    writerLeaseTokenHash: sha256Hex(writerToken),
+    reason: 'Replaced an unavailable active writer credential.',
+    context: contextFromEvent(posture.latestEvent),
+    handback: null,
+  }, now);
+}
+
+/**
+ * Validates every deterministic Task/handoff blocker without mutating the writer lease or sidecars.
+ * Callers may then acquire/renew a lease and use appendTaskClaim as a defensive race re-check.
+ */
+export function assertTaskClaimAllowed(
+  store: FileStateStore,
+  task: TaskState,
+  actor: string,
+  claimToken: string,
+  now: Date,
+  expectedDependencyBinding?: MilestoneDependencyBinding | null,
+): Extract<TaskC1Posture, { state: 'pending' }> {
+  assertTaskSupportsC1Handoff(task);
+  const normalizedActor = normalizeActor(actor, 'Claim actor');
+  const posture = readTaskC1Posture(store, task);
+  if (posture.state !== 'pending') {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} does not have a pending C1 handoff to claim.`, {
+      taskId: task.id,
+      posture: posture.state,
+    });
+  }
+  if (posture.targetActor !== normalizedActor) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Only handoff target ${posture.targetActor} may claim Task ${task.id}.`, {
+      taskId: task.id,
+      targetActor: posture.targetActor,
+      actor: normalizedActor,
+    });
+  }
+  if (
+    posture.latestEvent.taskRevision !== task.revision
+    || posture.latestEvent.briefHash !== task.briefHash
+    || posture.latestEvent.planHash !== task.planHash
+    || posture.latestEvent.knowledgeMapRevision !== task.knowledgeMapRevision
+    || posture.latestEvent.knowledgeMapHash !== task.knowledgeMapHash
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `C1 handoff ${posture.latestEvent.handoffId} is stale for the current Task context.`, {
+      taskId: task.id,
+      handoffId: posture.latestEvent.handoffId,
+      handoffTaskRevision: posture.latestEvent.taskRevision,
+      currentTaskRevision: task.revision,
+    });
+  }
+  if (
+    expectedDependencyBinding !== undefined
+    && !dependencyBindingsEqual(posture.latestEvent.dependencyBinding ?? null, expectedDependencyBinding)
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `C1 handoff ${posture.latestEvent.handoffId} has a stale Milestone dependency binding.`, {
+      diagnosticCode: 'MILESTONE_DEPENDENCY_BINDING_STALE',
+      taskId: task.id,
+      handoffId: posture.latestEvent.handoffId,
+      handoffDependencyBinding: posture.latestEvent.dependencyBinding ?? null,
+      currentDependencyBinding: expectedDependencyBinding,
+      requiredAction: 'Prepare a new C1 handoff from the current Milestone Plan.',
+    });
+  }
+  const handoffExpiresAt = Date.parse(posture.latestEvent.expiresAt);
+  if (!Number.isFinite(handoffExpiresAt)) {
+    throw new WorkflowError('STATE_CORRUPT', `C1 handoff ${posture.latestEvent.handoffId} expiry is malformed.`, {
+      taskId: task.id,
+      handoffId: posture.latestEvent.handoffId,
+      expiresAt: posture.latestEvent.expiresAt,
+    });
+  }
+  if (handoffExpiresAt <= now.getTime()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `C1 handoff ${posture.latestEvent.handoffId} has expired.`, {
+      taskId: task.id,
+      handoffId: posture.latestEvent.handoffId,
+      expiresAt: posture.latestEvent.expiresAt,
+    });
+  }
+  if (!claimToken || sha256Hex(claimToken) !== posture.latestEvent.claimTokenHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `C1 handoff ${posture.latestEvent.handoffId} claim token is invalid.`, {
+      taskId: task.id,
+      handoffId: posture.latestEvent.handoffId,
+    });
+  }
+  return posture;
+}
+
+export function appendTaskHandback(
+  store: FileStateStore,
+  task: TaskState,
+  actor: string,
+  reason: string,
+  writerToken: string | null,
+  limitations: readonly string[],
+  recommendedNext: string,
+  now: Date,
+): TaskHandoffEvent {
+  const normalizedActor = normalizeActor(actor, 'Handback actor');
+  const normalizedReason = normalizeReason(reason);
+  const posture = readTaskC1Posture(store, task);
+  if (posture.state !== 'claimed') {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} does not have an active C1 claim to hand back.`, {
+      taskId: task.id,
+      posture: posture.state,
+    });
+  }
+  if (posture.claimant !== normalizedActor) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Only claimant ${posture.claimant} may hand back Task ${task.id}.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+      actor: normalizedActor,
+    });
+  }
+  const leaseTokenHash = writerToken ? sha256Hex(writerToken) : null;
+  if (posture.writerLeaseTokenHash !== leaseTokenHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} handback requires the claimant's bound writer lease token.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+      expectedWriterLeaseTokenHash: posture.writerLeaseTokenHash,
+      actualWriterLeaseTokenHash: leaseTokenHash,
+    });
+  }
+  if (task.status !== 'merged' && task.status !== 'cancelled') {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} handback requires a terminal Task status.`, {
+      taskId: task.id,
+      taskStatus: task.status,
+      terminalStatuses: ['merged', 'cancelled'],
+    });
+  }
+  const handback: TaskHandbackRecord = {
+    status: task.status,
+    mergedCommit: task.mergedCommit,
+    planHash: task.planHash,
+    resultHash: task.resultHash,
+    evidenceHash: task.evidenceHash,
+    reviewAttestationHash: task.review.status === 'pending'
+      ? null
+      : sha256Hex(JSON.stringify(task.review)),
+    knowledgeMapRevision: task.knowledgeMapRevision,
+    knowledgeMapHash: task.knowledgeMapHash,
+    limitations: normalizeStringList(limitations, 'C1 handback limitations'),
+    recommendedNext: normalizeReason(recommendedNext),
+  };
+  return appendTaskHandoffEvent(store, task, {
+    eventType: 'handback',
+    actor: normalizedActor,
+    targetActor: null,
+    writerLeaseTokenHash: leaseTokenHash,
+    reason: normalizedReason,
+    context: contextFromEvent(posture.latestEvent),
+    handback,
+  }, now);
+}
+
+export function assertTaskMutationAllowedByC1(
+  store: FileStateStore,
+  task: TaskState,
+  authority: TaskMutationAuthority,
+): void {
+  const posture = readTaskC1Posture(store, task);
+  if (posture.state === 'none') return;
+  if (posture.state === 'pending') {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} has a pending C1 handoff and cannot be mutated until claim or handback.`, {
+      taskId: task.id,
+      targetActor: posture.targetActor,
+      eventId: posture.latestEvent.eventId,
+    });
+  }
+  const normalizedActor = normalizeActor(authority.actor, 'Mutation actor');
+  if (normalizedActor !== posture.claimant) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Only active claimant ${posture.claimant} may mutate Task ${task.id}.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+      actor: normalizedActor,
+    });
+  }
+  if (posture.writerLeaseTokenHash === null) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} claimed C1 posture is missing a bound writer lease token.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+    });
+  }
+  const actualLeaseTokenHash = authority.writerToken ? sha256Hex(authority.writerToken) : null;
+  if (posture.writerLeaseTokenHash !== actualLeaseTokenHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} mutation requires the claimant's bound writer lease token.`, {
+      taskId: task.id,
+      claimant: posture.claimant,
+      expectedWriterLeaseTokenHash: posture.writerLeaseTokenHash,
+      actualWriterLeaseTokenHash: actualLeaseTokenHash,
+    });
+  }
+}
+
+function appendTaskHandoffEvent(
+  store: FileStateStore,
+  task: TaskState,
+  input: {
+    eventType: TaskHandoffEventType;
+    actor: string;
+    targetActor: string | null;
+    writerLeaseTokenHash: string | null;
+    reason: string;
+    context: Pick<TaskHandoffEvent,
+      | 'handoffId'
+      | 'milestoneId'
+      | 'milestoneDisplayNumber'
+      | 'taskDisplayNumber'
+      | 'briefHash'
+      | 'planHash'
+      | 'knowledgeMapRevision'
+      | 'knowledgeMapHash'
+      | 'dependencyBinding'
+      | 'expectedNext'
+      | 'delegate'
+      | 'grantId'
+      | 'claimTokenHash'
+      | 'expiresAt'>;
+    handback: TaskHandbackRecord | null;
+  },
+  now: Date,
+): TaskHandoffEvent {
+  return store.appendSidecarEvent<TaskHandoffEvent>(
+    store.taskRoot(task.projectId, task.id),
+    HANDOFF_SIDECAR,
+    {
+      eventId: `HOF-${createUlid(now.getTime())}`,
+      recordedAt: now.toISOString(),
+      ...input.context,
+      taskId: task.id,
+      taskRevision: task.revision,
+      eventType: input.eventType,
+      coordinationLevel: COORDINATION_LEVEL,
+      actor: input.actor,
+      targetActor: input.targetActor,
+      machineEvidence: {
+        hostname: os.hostname(),
+        pid: process.pid,
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.version,
+      },
+      writerLeaseTokenHash: input.writerLeaseTokenHash,
+      reason: input.reason,
+      handback: input.handback,
+    },
+    {
+      validateEvent: (event, context) => validateStoredTaskHandoffEvent(event, task, context.file, context.line),
+    },
+  );
+}
+
+function validateStoredTaskHandoffEvent(
+  event: TaskHandoffEvent,
+  task: TaskState,
+  file: string,
+  line: number,
+): void {
+  assertExactTaskHandoffEventShape(event, task, file, line);
+  if (event.taskId !== task.id) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff event taskId does not match the current Task.', {
+      file,
+      line,
+      expectedTaskId: task.id,
+      actualTaskId: event.taskId,
+    });
+  }
+  if (!Number.isInteger(event.taskRevision) || event.taskRevision < 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff event taskRevision must be a positive integer.', {
+      file,
+      line,
+      taskId: task.id,
+      taskRevision: event.taskRevision,
+    });
+  }
+  assertNonEmptyStringField(event.handoffId, 'Task handoff handoffId is required.', { file, line, taskId: task.id });
+  if (!/^THO-[0-9A-HJKMNP-TV-Z]{26}$/u.test(event.handoffId)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff handoffId is invalid.', { file, line, taskId: task.id, handoffId: event.handoffId });
+  }
+  if (event.milestoneId !== task.milestoneId) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff milestone binding does not match the Task.', {
+      file, line, taskId: task.id, eventMilestoneId: event.milestoneId, taskMilestoneId: task.milestoneId,
+    });
+  }
+  assertStateCorruptHash64(event.briefHash, 'Task handoff briefHash is invalid.', { file, line, taskId: task.id });
+  if (event.planHash !== null) assertStateCorruptHash64(event.planHash, 'Task handoff planHash is invalid.', { file, line, taskId: task.id });
+  if (event.knowledgeMapHash !== null) {
+    assertStateCorruptHash64(event.knowledgeMapHash, 'Task handoff knowledgeMapHash is invalid.', { file, line, taskId: task.id });
+  }
+  validateDependencyBinding(event.dependencyBinding, event.milestoneId, task, file, line);
+  assertNullablePositiveInteger(event.milestoneDisplayNumber, 'Task handoff milestoneDisplayNumber is invalid.', { file, line, taskId: task.id });
+  assertNullablePositiveInteger(event.taskDisplayNumber, 'Task handoff taskDisplayNumber is invalid.', { file, line, taskId: task.id });
+  assertNullablePositiveInteger(event.knowledgeMapRevision, 'Task handoff knowledgeMapRevision is invalid.', { file, line, taskId: task.id });
+  if (event.milestoneId === null && (event.milestoneDisplayNumber !== null || event.taskDisplayNumber !== null)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Standalone Task handoff cannot declare Milestone display numbers.', {
+      file, line, taskId: task.id,
+    });
+  }
+  assertNonEmptyStringField(event.expectedNext, 'Task handoff expectedNext is required.', { file, line, taskId: task.id });
+  assertNonEmptyStringField(event.delegate, 'Task handoff delegate is required.', { file, line, taskId: task.id });
+  if (event.grantId !== null && (typeof event.grantId !== 'string' || !event.grantId.trim())) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff grantId must be null or a non-empty string.', { file, line, taskId: task.id });
+  }
+  assertStateCorruptHash64(event.claimTokenHash, 'Task handoff claimTokenHash is invalid.', { file, line, taskId: task.id });
+  if (!event.expiresAt || Number.isNaN(Date.parse(event.expiresAt))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff expiresAt must be an ISO timestamp.', { file, line, taskId: task.id });
+  }
+  if (!HANDOFF_EVENT_TYPES.has(event.eventType)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff eventType is invalid.', {
+      file,
+      line,
+      taskId: task.id,
+      eventType: event.eventType,
+    });
+  }
+  if (event.coordinationLevel !== COORDINATION_LEVEL) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff coordinationLevel is invalid.', {
+      file,
+      line,
+      taskId: task.id,
+      coordinationLevel: event.coordinationLevel,
+    });
+  }
+  if (!event.actor.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff actor is required.', {
+      file,
+      line,
+      taskId: task.id,
+    });
+  }
+  if (event.targetActor !== null && !event.targetActor.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff targetActor must be non-empty when present.', {
+      file,
+      line,
+      taskId: task.id,
+    });
+  }
+  if (!event.reason.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff reason is required.', {
+      file,
+      line,
+      taskId: task.id,
+    });
+  }
+  if (event.writerLeaseTokenHash !== null) {
+    assertStateCorruptHash64(event.writerLeaseTokenHash, 'Task handoff writerLeaseTokenHash is invalid.', {
+      file,
+      line,
+      taskId: task.id,
+      writerLeaseTokenHash: event.writerLeaseTokenHash,
+    });
+  }
+  if (event.eventType === 'handoff' && event.targetActor === null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff event must record targetActor.', {
+      file,
+      line,
+      taskId: task.id,
+      eventType: event.eventType,
+    });
+  }
+  if (event.eventType === 'handoff' && event.targetActor !== event.delegate) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff targetActor must equal its bound delegate.', {
+      file, line, taskId: task.id, targetActor: event.targetActor, delegate: event.delegate,
+    });
+  }
+  if ((event.eventType === 'claim' || event.eventType === 'credential-replace' || event.eventType === 'yield' || event.eventType === 'handback') && event.targetActor !== null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task claim/credential-replace/yield/handback events must not record targetActor.', {
+      file,
+      line,
+      taskId: task.id,
+      eventType: event.eventType,
+    });
+  }
+  if (event.eventType === 'handback' && event.handback === null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handback event must contain the terminal handback bundle.', {
+      file, line, taskId: task.id,
+    });
+  }
+  if (event.handback !== null) validateHandbackRecord(event.handback, task, file, line);
+  if (event.eventType === 'handback' && event.handback) {
+    const expectedReviewAttestationHash = task.review.status === 'pending'
+      ? null
+      : sha256Hex(JSON.stringify(task.review));
+    const currentBindings = {
+      status: task.status,
+      mergedCommit: task.mergedCommit,
+      planHash: task.planHash,
+      resultHash: task.resultHash,
+      evidenceHash: task.evidenceHash,
+      reviewAttestationHash: expectedReviewAttestationHash,
+      knowledgeMapRevision: task.knowledgeMapRevision,
+      knowledgeMapHash: task.knowledgeMapHash,
+    };
+    const eventBindings = {
+      status: event.handback.status,
+      mergedCommit: event.handback.mergedCommit,
+      planHash: event.handback.planHash,
+      resultHash: event.handback.resultHash,
+      evidenceHash: event.handback.evidenceHash,
+      reviewAttestationHash: event.handback.reviewAttestationHash,
+      knowledgeMapRevision: event.handback.knowledgeMapRevision,
+      knowledgeMapHash: event.handback.knowledgeMapHash,
+    };
+    if (JSON.stringify(currentBindings) !== JSON.stringify(eventBindings)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task handback bundle is stale or inconsistent with terminal Task state.', {
+        file, line, taskId: task.id, currentBindings, eventBindings,
+      });
+    }
+  }
+  if (event.eventType !== 'handback' && event.handback !== null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Only handback events may contain a handback bundle.', {
+      file, line, taskId: task.id, eventType: event.eventType,
+    });
+  }
+}
+
+function validateTaskHandoffHistory(events: readonly TaskHandoffEvent[], task: TaskState): void {
+  let posture: TaskC1Posture = { state: 'none', latestEvent: null };
+  let previousTaskRevision = 0;
+  for (const [index, event] of events.entries()) {
+    const previous: TaskC1Posture = posture;
+    if (event.taskRevision > task.revision) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task handoff event references a future Task revision.', {
+        taskId: task.id,
+        eventId: event.eventId,
+        taskRevision: task.revision,
+        eventTaskRevision: event.taskRevision,
+      });
+    }
+    if (event.taskRevision < previousTaskRevision) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task handoff event taskRevision must be nondecreasing through history.', {
+        taskId: task.id,
+        eventId: event.eventId,
+        previousTaskRevision,
+        eventTaskRevision: event.taskRevision,
+      });
+    }
+    switch (event.eventType) {
+      case 'handoff':
+        if (previous.state === 'pending') {
+          assertPendingHandoffReplacement(previous.latestEvent, event, task);
+        }
+        if (previous.state === 'claimed' && previous.claimant !== event.actor.trim()) {
+          throw new WorkflowError('STATE_CORRUPT', 'Only the active claimant may issue a new handoff.', {
+            taskId: task.id,
+            eventId: event.eventId,
+            claimant: previous.claimant,
+            actor: event.actor,
+          });
+        }
+        if (previous.state === 'claimed' && previous.writerLeaseTokenHash !== event.writerLeaseTokenHash) {
+          throw new WorkflowError('STATE_CORRUPT', 'Claimed handoff rewrite must preserve the bound lease token hash.', {
+            taskId: task.id,
+            eventId: event.eventId,
+            claimant: previous.claimant,
+            expectedWriterLeaseTokenHash: previous.writerLeaseTokenHash,
+            actualWriterLeaseTokenHash: event.writerLeaseTokenHash,
+          });
+        }
+        posture = { state: 'pending', latestEvent: event, targetActor: event.targetActor! };
+        break;
+      case 'claim':
+        if (previous.state !== 'pending') {
+          throw new WorkflowError('STATE_CORRUPT', 'Task claim requires a pending handoff.', {
+            taskId: task.id,
+            eventId: event.eventId,
+            previousState: previous.state,
+          });
+        }
+        if (previous.targetActor !== event.actor.trim()) {
+          throw new WorkflowError('STATE_CORRUPT', 'Task claim actor must equal the pending handoff target.', {
+            taskId: task.id,
+            eventId: event.eventId,
+            targetActor: previous.targetActor,
+            actor: event.actor,
+          });
+        }
+        assertSameHandoffContext(previous.latestEvent, event, task);
+        posture = {
+          state: 'claimed',
+          latestEvent: event,
+          claimant: event.actor.trim(),
+          writerLeaseTokenHash: event.writerLeaseTokenHash,
+        };
+        break;
+      case 'credential-replace':
+        if (previous.state !== 'claimed') {
+          throw new WorkflowError('STATE_CORRUPT', 'Task writer credential replacement requires the exact active claimant.', {
+            taskId: task.id,
+            eventId: event.eventId,
+            previousState: previous.state,
+          });
+        }
+        {
+          const claimedPrevious = previous as Extract<TaskC1Posture, { state: 'claimed' }>;
+          if (claimedPrevious.claimant !== event.actor.trim()) {
+            throw new WorkflowError('STATE_CORRUPT', 'Task writer credential replacement actor must equal the active claimant.', {
+              taskId: task.id,
+              eventId: event.eventId,
+              claimant: claimedPrevious.claimant,
+              actor: event.actor,
+            });
+          }
+          if (event.writerLeaseTokenHash === null || event.writerLeaseTokenHash === claimedPrevious.writerLeaseTokenHash) {
+            throw new WorkflowError('STATE_CORRUPT', 'Task writer credential replacement must bind a distinct non-null lease token hash.', {
+              taskId: task.id,
+              eventId: event.eventId,
+            });
+          }
+        }
+        assertSameHandoffContext(previous.latestEvent, event, task);
+        posture = {
+          state: 'claimed',
+          latestEvent: event,
+          claimant: event.actor.trim(),
+          writerLeaseTokenHash: event.writerLeaseTokenHash,
+        };
+        break;
+      case 'handback':
+      case 'yield':
+        if (previous.state !== 'claimed') {
+          throw new WorkflowError('STATE_CORRUPT', `Task ${event.eventType} requires an active claim.`, {
+            taskId: task.id,
+            eventId: event.eventId,
+            previousState: previous.state,
+          });
+        }
+        if (previous.claimant !== event.actor.trim()) {
+          throw new WorkflowError('STATE_CORRUPT', `Task ${event.eventType} actor must equal the active claimant.`, {
+            taskId: task.id,
+            eventId: event.eventId,
+            claimant: previous.claimant,
+            actor: event.actor,
+          });
+        }
+        if (previous.writerLeaseTokenHash !== event.writerLeaseTokenHash) {
+          throw new WorkflowError('STATE_CORRUPT', `Task ${event.eventType} must preserve the claimant lease-token binding.`, {
+            taskId: task.id,
+            eventId: event.eventId,
+            expectedWriterLeaseTokenHash: previous.writerLeaseTokenHash,
+            actualWriterLeaseTokenHash: event.writerLeaseTokenHash,
+          });
+        }
+        assertSameHandoffContext(previous.latestEvent, event, task);
+        if (event.eventType === 'yield' && event.handback !== null) {
+          throw new WorkflowError('STATE_CORRUPT', 'Task yield must not contain a terminal handback bundle.', {
+            taskId: task.id,
+            eventId: event.eventId,
+          });
+        }
+        posture = { state: 'none', latestEvent: event };
+        break;
+      default:
+        throw new WorkflowError('STATE_CORRUPT', 'Task handoff eventType is unknown during history validation.', {
+          taskId: task.id,
+          eventId: event.eventId,
+          eventType: event.eventType,
+        });
+    }
+    const expectedHash = computeSidecarEventHash(event);
+    if (expectedHash !== event.eventHash) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task handoff eventHash mismatch.', {
+        taskId: task.id,
+        eventId: event.eventId,
+        expectedEventHash: expectedHash,
+        actualEventHash: event.eventHash,
+      });
+    }
+    previousTaskRevision = event.taskRevision;
+  }
+}
+
+function assertPendingHandoffReplacement(
+  previous: TaskHandoffEvent,
+  replacement: TaskHandoffEvent,
+  task: TaskState,
+): void {
+  const fixedPrevious = {
+    taskId: previous.taskId,
+    taskRevision: previous.taskRevision,
+    milestoneId: previous.milestoneId,
+    milestoneDisplayNumber: previous.milestoneDisplayNumber,
+    taskDisplayNumber: previous.taskDisplayNumber,
+    briefHash: previous.briefHash,
+    planHash: previous.planHash,
+    knowledgeMapRevision: previous.knowledgeMapRevision,
+    knowledgeMapHash: previous.knowledgeMapHash,
+    expectedNext: previous.expectedNext,
+    delegate: previous.delegate,
+    grantId: previous.grantId,
+    actor: previous.actor.trim(),
+    targetActor: previous.targetActor,
+  };
+  const fixedReplacement = {
+    taskId: replacement.taskId,
+    taskRevision: replacement.taskRevision,
+    milestoneId: replacement.milestoneId,
+    milestoneDisplayNumber: replacement.milestoneDisplayNumber,
+    taskDisplayNumber: replacement.taskDisplayNumber,
+    briefHash: replacement.briefHash,
+    planHash: replacement.planHash,
+    knowledgeMapRevision: replacement.knowledgeMapRevision,
+    knowledgeMapHash: replacement.knowledgeMapHash,
+    expectedNext: replacement.expectedNext,
+    delegate: replacement.delegate,
+    grantId: replacement.grantId,
+    actor: replacement.actor.trim(),
+    targetActor: replacement.targetActor,
+  };
+  if (JSON.stringify(fixedPrevious) !== JSON.stringify(fixedReplacement)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Pending C1 handoff credential replacement changed its authority or Task context.', {
+      taskId: task.id,
+      previousEventId: previous.eventId,
+      replacementEventId: replacement.eventId,
+    });
+  }
+}
+
+function assertSameHandoffContext(
+  expected: TaskHandoffEvent,
+  actual: TaskHandoffEvent,
+  task: TaskState,
+): void {
+  const expectedContext = contextFromEvent(expected);
+  const actualContext = contextFromEvent(actual);
+  if (JSON.stringify(expectedContext) !== JSON.stringify(actualContext)) {
+    throw new WorkflowError('STATE_CORRUPT', 'C1 claim/handback changed its prepared handoff context.', {
+      taskId: task.id,
+      handoffId: expected.handoffId,
+      eventId: actual.eventId,
+    });
+  }
+}
+
+function parseTaskHandoffEvents(content: string, task: TaskState, file: string): TaskHandoffEvent[] {
+  if (content.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Task handoff sidecar must not be empty: ${file}`);
+  }
+  const rawLines = content.split('\n');
+  if (rawLines.at(-1) === '') rawLines.pop();
+  if (rawLines.some((line) => line.length === 0)) {
+    throw new WorkflowError('STATE_CORRUPT', `Task handoff sidecar contains a blank line: ${file}`);
+  }
+  const events: TaskHandoffEvent[] = [];
+  const eventIds = new Set<string>();
+  let previousEventHash: string | null = null;
+  for (const [index, rawLine] of rawLines.entries()) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawLine);
+    } catch (error) {
+      throw new WorkflowError('STATE_CORRUPT', `Invalid task handoff JSONL: ${file}`, {
+        line: index + 1,
+        cause: error instanceof Error ? error.message : String(error),
+      });
+    }
+    const event = parsed as TaskHandoffEvent;
+    validateStoredTaskHandoffEvent(event, task, file, index + 1);
+    if (eventIds.has(event.eventId)) {
+      throw new WorkflowError('STATE_CORRUPT', `Duplicate task handoff event id in ${file}`, {
+        line: index + 1,
+        eventId: event.eventId,
+      });
+    }
+    eventIds.add(event.eventId);
+    if (event.previousEventHash !== previousEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Broken task handoff chain in ${file}`, {
+        line: index + 1,
+        expectedPreviousEventHash: previousEventHash,
+        actualPreviousEventHash: event.previousEventHash,
+      });
+    }
+    const expectedEventHash = computeSidecarEventHash(event);
+    if (event.eventHash !== expectedEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Task handoff event hash mismatch in ${file}`, {
+        line: index + 1,
+        eventId: event.eventId,
+        expectedEventHash,
+        actualEventHash: event.eventHash,
+      });
+    }
+    previousEventHash = event.eventHash;
+    events.push(event);
+  }
+  return events;
+}
+
+function assertExactTaskHandoffEventShape(
+  event: TaskHandoffEvent,
+  task: TaskState,
+  file: string,
+  line: number,
+): void {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff event must be an object.', {
+      file,
+      line,
+      taskId: task.id,
+    });
+  }
+  const allowedKeys = new Set([
+    'eventId',
+    'previousEventHash',
+    'recordedAt',
+    'eventHash',
+    'handoffId',
+    'taskId',
+    'taskRevision',
+    'milestoneId',
+    'milestoneDisplayNumber',
+    'taskDisplayNumber',
+    'briefHash',
+    'planHash',
+    'knowledgeMapRevision',
+    'knowledgeMapHash',
+    'dependencyBinding',
+    'expectedNext',
+    'delegate',
+    'grantId',
+    'claimTokenHash',
+    'expiresAt',
+    'eventType',
+    'coordinationLevel',
+    'actor',
+    'targetActor',
+    'machineEvidence',
+    'writerLeaseTokenHash',
+    'reason',
+    'handback',
+  ]);
+  const extraKeys = Object.keys(event as unknown as Record<string, unknown>).filter((key) => !allowedKeys.has(key));
+  if (extraKeys.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff event contains unexpected fields.', {
+      file,
+      line,
+      taskId: task.id,
+      extraKeys,
+    });
+  }
+  assertNonEmptyStringField(event.eventId, 'Task handoff eventId must be a non-empty string.', {
+    file,
+    line,
+    taskId: task.id,
+    eventId: event.eventId,
+  });
+  if (event.previousEventHash !== null && typeof event.previousEventHash !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff previousEventHash must be null or a SHA-256 hash string.', {
+      file,
+      line,
+      taskId: task.id,
+      previousEventHash: event.previousEventHash,
+    });
+  }
+  if (event.previousEventHash !== null) {
+    assertStateCorruptHash64(event.previousEventHash, 'Task handoff previousEventHash must be a SHA-256 hash string.', {
+      file,
+      line,
+      taskId: task.id,
+      previousEventHash: event.previousEventHash,
+    });
+  }
+  assertNonEmptyStringField(event.eventHash, 'Task handoff eventHash must be a SHA-256 hash string.', {
+    file,
+    line,
+    taskId: task.id,
+    eventHash: event.eventHash,
+  });
+  assertStateCorruptHash64(event.eventHash, 'Task handoff eventHash must be a SHA-256 hash string.', {
+    file,
+    line,
+    taskId: task.id,
+    eventHash: event.eventHash,
+  });
+  assertNonEmptyStringField(event.taskId, 'Task handoff taskId must be a non-empty string.', {
+    file,
+    line,
+    taskId: task.id,
+    eventTaskId: event.taskId,
+  });
+  if (typeof event.eventType !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff eventType must be a string.', {
+      file,
+      line,
+      taskId: task.id,
+      eventType: event.eventType,
+    });
+  }
+  if (typeof event.coordinationLevel !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff coordinationLevel must be a string.', {
+      file,
+      line,
+      taskId: task.id,
+      coordinationLevel: event.coordinationLevel,
+    });
+  }
+  assertNonEmptyStringField(event.actor, 'Task handoff actor must be a non-empty string.', {
+    file,
+    line,
+    taskId: task.id,
+    actor: event.actor,
+  });
+  if (event.targetActor !== null && typeof event.targetActor !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff targetActor must be null or a non-empty string.', {
+      file,
+      line,
+      taskId: task.id,
+      targetActor: event.targetActor,
+    });
+  }
+  if (event.targetActor !== null && !event.targetActor.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff targetActor must be non-empty when present.', {
+      file,
+      line,
+      taskId: task.id,
+      targetActor: event.targetActor,
+    });
+  }
+  if (event.writerLeaseTokenHash !== null && typeof event.writerLeaseTokenHash !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff writerLeaseTokenHash must be null or a SHA-256 hash string.', {
+      file,
+      line,
+      taskId: task.id,
+      writerLeaseTokenHash: event.writerLeaseTokenHash,
+    });
+  }
+  assertNonEmptyStringField(event.reason, 'Task handoff reason must be a non-empty string.', {
+    file,
+    line,
+    taskId: task.id,
+    reason: event.reason,
+  });
+  if (typeof event.recordedAt !== 'string' || !event.recordedAt.trim() || Number.isNaN(Date.parse(event.recordedAt))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff recordedAt must be an ISO timestamp string.', {
+      file,
+      line,
+      taskId: task.id,
+      recordedAt: event.recordedAt,
+    });
+  }
+  if (!event.machineEvidence || typeof event.machineEvidence !== 'object' || Array.isArray(event.machineEvidence)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff machineEvidence is invalid.', {
+      file,
+      line,
+      taskId: task.id,
+    });
+  }
+  const machineEvidence = event.machineEvidence as unknown as Record<string, unknown>;
+  const allowedMachineKeys = new Set(['hostname', 'pid', 'platform', 'arch', 'nodeVersion']);
+  const extraMachineKeys = Object.keys(machineEvidence).filter((key) => !allowedMachineKeys.has(key));
+  if (extraMachineKeys.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff machineEvidence contains unexpected fields.', {
+      file,
+      line,
+      taskId: task.id,
+      extraMachineKeys,
+    });
+  }
+  if (
+    typeof machineEvidence.hostname !== 'string'
+    || !machineEvidence.hostname.trim()
+    || !Number.isInteger(machineEvidence.pid)
+    || (machineEvidence.pid as number) < 1
+    || typeof machineEvidence.platform !== 'string'
+    || !machineEvidence.platform.trim()
+    || typeof machineEvidence.arch !== 'string'
+    || !machineEvidence.arch.trim()
+    || typeof machineEvidence.nodeVersion !== 'string'
+    || !machineEvidence.nodeVersion.trim()
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff machineEvidence is invalid.', {
+      file,
+      line,
+      taskId: task.id,
+    });
+  }
+}
+
+function assertTaskSupportsC1Handoff(task: TaskState): void {
+  if (!NON_TERMINAL_TASK_STATUSES.has(task.status)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} does not support C1 handoff while ${task.status}.`, {
+      taskId: task.id,
+      taskStatus: task.status,
+    });
+  }
+}
+
+function normalizeActor(value: string, label: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} is required.`);
+  }
+  return value.trim();
+}
+
+function normalizeReason(value: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'C1 handoff reason is required.');
+  }
+  return value.trim();
+}
+
+function normalizeFutureExpiry(value: string, now: Date): string {
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime()) || parsed.getTime() <= now.getTime()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'C1 handoff expiresAt must be a future ISO timestamp.');
+  }
+  return parsed.toISOString();
+}
+
+function normalizeStringList(value: readonly string[], label: string): string[] {
+  if (!Array.isArray(value)) throw new WorkflowError('INVALID_ARGUMENT', `${label} must be an array.`);
+  const normalized = value.map((entry) => normalizeReason(entry));
+  if (new Set(normalized).size !== normalized.length) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must contain unique values.`);
+  }
+  return normalized;
+}
+
+function contextFromEvent(event: TaskHandoffEvent): Pick<TaskHandoffEvent,
+  | 'handoffId'
+  | 'milestoneId'
+  | 'milestoneDisplayNumber'
+  | 'taskDisplayNumber'
+  | 'briefHash'
+  | 'planHash'
+  | 'knowledgeMapRevision'
+  | 'knowledgeMapHash'
+  | 'dependencyBinding'
+  | 'expectedNext'
+  | 'delegate'
+  | 'grantId'
+  | 'claimTokenHash'
+  | 'expiresAt'> {
+  return {
+    handoffId: event.handoffId,
+    milestoneId: event.milestoneId,
+    milestoneDisplayNumber: event.milestoneDisplayNumber,
+    taskDisplayNumber: event.taskDisplayNumber,
+    briefHash: event.briefHash,
+    planHash: event.planHash,
+    knowledgeMapRevision: event.knowledgeMapRevision,
+    knowledgeMapHash: event.knowledgeMapHash,
+    dependencyBinding: event.dependencyBinding ?? null,
+    expectedNext: event.expectedNext,
+    delegate: event.delegate,
+    grantId: event.grantId,
+    claimTokenHash: event.claimTokenHash,
+    expiresAt: event.expiresAt,
+  };
+}
+
+function validateDependencyBinding(
+  binding: MilestoneDependencyBinding | null | undefined,
+  milestoneId: string | null,
+  task: TaskState,
+  file: string,
+  line: number,
+): void {
+  if (binding === undefined) return;
+  if (milestoneId === null) {
+    if (binding !== null) {
+      throw new WorkflowError('STATE_CORRUPT', 'Standalone Task handoff dependencyBinding must be null.', {
+        file, line, taskId: task.id,
+      });
+    }
+    return;
+  }
+  if (!binding || typeof binding !== 'object' || Array.isArray(binding)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone Task handoff dependencyBinding must be an object.', {
+      file, line, taskId: task.id,
+    });
+  }
+  const extraKeys = Object.keys(binding).filter((key) => ![
+    'milestoneRevision',
+    'membershipRevision',
+    'milestonePlanHash',
+  ].includes(key));
+  if (
+    extraKeys.length > 0
+    || !Number.isInteger(binding.milestoneRevision)
+    || binding.milestoneRevision < 1
+    || !Number.isInteger(binding.membershipRevision)
+    || binding.membershipRevision < 1
+    || !/^[0-9a-f]{64}$/u.test(binding.milestonePlanHash)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handoff dependencyBinding is invalid.', {
+      file, line, taskId: task.id, dependencyBinding: binding, extraKeys,
+    });
+  }
+}
+
+function dependencyBindingsEqual(
+  left: MilestoneDependencyBinding | null,
+  right: MilestoneDependencyBinding | null,
+): boolean {
+  if (left === null || right === null) return left === right;
+  return left.milestoneRevision === right.milestoneRevision
+    && left.membershipRevision === right.membershipRevision
+    && left.milestonePlanHash === right.milestonePlanHash;
+}
+
+function buildTaskHandoffPrompt(task: TaskState, expectedNext: string, delegate: string): string {
+  return [
+    `You are ${delegate}, the claimed executor for Task ${task.id}.`,
+    `Work only from Task revision ${task.revision} and Plan ${task.planHash ?? '<unset>'}.`,
+    `Expected next action: ${expectedNext}.`,
+    'Use the claim-bound writer lease for every mutation.',
+    'On completion, create a handback containing terminal status, result/evidence bindings, limitations, and recommended next action.',
+  ].join('\n');
+}
+
+function assertNonEmptyStringField(
+  value: unknown,
+  message: string,
+  context: Record<string, unknown>,
+): asserts value is string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', message, context);
+  }
+}
+
+function assertStateCorruptHash64(
+  value: string,
+  message: string,
+  context: Record<string, unknown>,
+): void {
+  if (!/^[0-9a-f]{64}$/u.test(value)) {
+    throw new WorkflowError('STATE_CORRUPT', message, context);
+  }
+}
+
+function assertNullablePositiveInteger(
+  value: unknown,
+  message: string,
+  context: Record<string, unknown>,
+): void {
+  if (value !== null && (!Number.isInteger(value) || Number(value) < 1)) {
+    throw new WorkflowError('STATE_CORRUPT', message, { ...context, value });
+  }
+}
+
+function validateHandbackRecord(
+  record: TaskHandbackRecord,
+  task: TaskState,
+  file: string,
+  line: number,
+): void {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handback bundle must be an object.', { file, line, taskId: task.id });
+  }
+  const allowedKeys = new Set([
+    'status', 'mergedCommit', 'planHash', 'resultHash', 'evidenceHash', 'reviewAttestationHash',
+    'knowledgeMapRevision', 'knowledgeMapHash', 'limitations', 'recommendedNext',
+  ]);
+  const extraKeys = Object.keys(record as unknown as Record<string, unknown>).filter((key) => !allowedKeys.has(key));
+  if (extraKeys.length > 0 || (record.status !== 'merged' && record.status !== 'cancelled')) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handback bundle has invalid shape or status.', {
+      file, line, taskId: task.id, extraKeys, status: record.status,
+    });
+  }
+  if (record.mergedCommit !== null && !/^[0-9a-f]{40,64}$/u.test(record.mergedCommit)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handback mergedCommit is invalid.', {
+      file, line, taskId: task.id, mergedCommit: record.mergedCommit,
+    });
+  }
+  for (const [label, value] of [
+    ['planHash', record.planHash],
+    ['resultHash', record.resultHash],
+    ['evidenceHash', record.evidenceHash],
+    ['reviewAttestationHash', record.reviewAttestationHash],
+    ['knowledgeMapHash', record.knowledgeMapHash],
+  ] as const) {
+    if (value !== null) assertStateCorruptHash64(value, `Task handback ${label} is invalid.`, { file, line, taskId: task.id });
+  }
+  assertNullablePositiveInteger(record.knowledgeMapRevision, 'Task handback knowledgeMapRevision is invalid.', { file, line, taskId: task.id });
+  if (!Array.isArray(record.limitations) || record.limitations.some((value) => typeof value !== 'string')) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task handback limitations must be a string array.', { file, line, taskId: task.id });
+  }
+  assertNonEmptyStringField(record.recommendedNext, 'Task handback recommendedNext is required.', { file, line, taskId: task.id });
+}
+
+function resolveAlpha6TaskRoot(store: FileStateStore, task: TaskState): string {
+  const projectRootLogical = store.projectRoot(task.projectId);
+  const trustedProjectRoot = existsSync(projectRootLogical) ? realpathSync(projectRootLogical) : path.resolve(projectRootLogical);
+  const tasksDirLogical = path.join(projectRootLogical, 'tasks');
+  const trustedTasksDir = existsSync(tasksDirLogical)
+    ? realpathSync(tasksDirLogical)
+    : path.join(trustedProjectRoot, 'tasks');
+  const taskRootLogical = store.taskRoot(task.projectId, task.id);
+  assertNoSymlinkPathComponents(trustedTasksDir, { label: 'Trusted tasks directory', requireLeaf: true });
+  if (existsSync(taskRootLogical) && lstatSync(taskRootLogical).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Task root must not be a symlink: ${taskRootLogical}`);
+  }
+  const resolvedTaskRoot = existsSync(taskRootLogical)
+    ? realpathSync(taskRootLogical)
+    : path.resolve(trustedTasksDir, task.id);
+  if (
+    resolvedTaskRoot !== trustedTasksDir
+    && !resolvedTaskRoot.startsWith(`${trustedTasksDir}${path.sep}`)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', `Task root escaped the trusted tasks directory: ${taskRootLogical}`, {
+      trustedTasksDir,
+      resolvedTaskRoot,
+    });
+  }
+  return resolvedTaskRoot;
+}