codex-workflow-v2 2.0.0-alpha.4 → 2.0.0-alpha.7

package/dist/src/alpha6/handoff.js

@@ -0,0 +1,981 @@
+import os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from '../errors.js';
+import { createUlid } from '../ulid.js';
+import { assertNoSymlinkPathComponents, computeSidecarEventHash, sha256Hex, } from './store-sidecars.js';
+const HANDOFF_SIDECAR = 'handoffs.jsonl';
+const NON_TERMINAL_TASK_STATUSES = new Set([
+    'planning',
+    'awaiting_execution_authorization',
+    'ready',
+    'in_progress',
+    'validating',
+    'blocked',
+    'needs_fix',
+    'awaiting_final_acceptance',
+    'ready_to_merge',
+    'merging',
+]);
+const HANDOFF_EVENT_TYPES = new Set(['handoff', 'claim', 'handback']);
+const COORDINATION_LEVEL = 'C1';
+export function defaultTaskWorkerActor(taskId) {
+    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, task) {
+    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, task) {
+    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') {
+        return {
+            state: 'claimed',
+            latestEvent,
+            claimant: latestEvent.actor.trim(),
+            writerLeaseTokenHash: latestEvent.writerLeaseTokenHash,
+        };
+    }
+    return { state: 'none', latestEvent };
+}
+export function appendTaskHandoff(store, task, input, now) {
+    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') {
+        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 (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,
+        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,
+            expectedNext: context.expectedNext,
+            delegate: normalizedTargetActor,
+            grantId: input.grantId,
+            claimToken,
+            createdAt: now.toISOString(),
+            expiresAt,
+            prompt: buildTaskHandoffPrompt(task, context.expectedNext, normalizedTargetActor),
+        },
+    };
+}
+export function appendTaskClaim(store, task, actor, claimToken, writerToken, now) {
+    assertTaskSupportsC1Handoff(task);
+    const normalizedActor = normalizeActor(actor, 'Claim actor');
+    if (writerToken === null) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} claim requires a bound writer lease token.`, {
+            taskId: task.id,
+            actor: normalizedActor,
+        });
+    }
+    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 (Date.parse(posture.latestEvent.expiresAt) <= 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 appendTaskHandoffEvent(store, task, {
+        eventType: 'claim',
+        actor: normalizedActor,
+        targetActor: null,
+        writerLeaseTokenHash: writerToken ? sha256Hex(writerToken) : null,
+        reason: `Claimed pending C1 handoff from ${posture.latestEvent.actor}.`,
+        context: contextFromEvent(posture.latestEvent),
+        handback: null,
+    }, now);
+}
+export function appendTaskHandback(store, task, actor, reason, writerToken, limitations, recommendedNext, now) {
+    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 = {
+        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, task, authority) {
+    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, task, input, now) {
+    return store.appendSidecarEvent(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, task, file, line) {
+    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 });
+    }
+    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 === 'handback') && event.targetActor !== null) {
+        throw new WorkflowError('STATE_CORRUPT', 'Task claim/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, task) {
+    let posture = { state: 'none', latestEvent: null };
+    let previousTaskRevision = 0;
+    for (const [index, event] of events.entries()) {
+        const previous = 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') {
+                    throw new WorkflowError('STATE_CORRUPT', 'Task handoff sidecar cannot stack pending handoffs.', {
+                        taskId: task.id,
+                        eventId: event.eventId,
+                        previousEventId: previous.latestEvent.eventId,
+                    });
+                }
+                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 'handback':
+                if (previous.state !== 'claimed') {
+                    throw new WorkflowError('STATE_CORRUPT', 'Task handback 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 handback 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 handback must preserve the claimant lease-token binding.', {
+                        taskId: task.id,
+                        eventId: event.eventId,
+                        expectedWriterLeaseTokenHash: previous.writerLeaseTokenHash,
+                        actualWriterLeaseTokenHash: event.writerLeaseTokenHash,
+                    });
+                }
+                assertSameHandoffContext(previous.latestEvent, event, task);
+                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 assertSameHandoffContext(expected, actual, task) {
+    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, task, file) {
+    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 = [];
+    const eventIds = new Set();
+    let previousEventHash = null;
+    for (const [index, rawLine] of rawLines.entries()) {
+        let parsed;
+        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;
+        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, task, file, line) {
+    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',
+        'expectedNext',
+        'delegate',
+        'grantId',
+        'claimTokenHash',
+        'expiresAt',
+        'eventType',
+        'coordinationLevel',
+        'actor',
+        'targetActor',
+        'machineEvidence',
+        'writerLeaseTokenHash',
+        'reason',
+        'handback',
+    ]);
+    const extraKeys = Object.keys(event).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;
+    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 < 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) {
+    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, label) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowError('INVALID_ARGUMENT', `${label} is required.`);
+    }
+    return value.trim();
+}
+function normalizeReason(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'C1 handoff reason is required.');
+    }
+    return value.trim();
+}
+function normalizeFutureExpiry(value, now) {
+    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, label) {
+    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) {
+    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,
+        expectedNext: event.expectedNext,
+        delegate: event.delegate,
+        grantId: event.grantId,
+        claimTokenHash: event.claimTokenHash,
+        expiresAt: event.expiresAt,
+    };
+}
+function buildTaskHandoffPrompt(task, expectedNext, delegate) {
+    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, message, context) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowError('STATE_CORRUPT', message, context);
+    }
+}
+function assertStateCorruptHash64(value, message, context) {
+    if (!/^[0-9a-f]{64}$/u.test(value)) {
+        throw new WorkflowError('STATE_CORRUPT', message, context);
+    }
+}
+function assertNullablePositiveInteger(value, message, context) {
+    if (value !== null && (!Number.isInteger(value) || Number(value) < 1)) {
+        throw new WorkflowError('STATE_CORRUPT', message, { ...context, value });
+    }
+}
+function validateHandbackRecord(record, task, file, line) {
+    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).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],
+    ]) {
+        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, task) {
+    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;
+}
+//# sourceMappingURL=handoff.js.map