@henryqw/pi-subagent 18.0.1 → 22.0.0

package/dist/schema.js

@@ -0,0 +1,1236 @@
+import { isAbsolute } from "node:path";
+import { parseRoleName } from "./index.js";
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+export const RUN_STATE_VERSION = 5;
+export const MAX_TASKS = 8;
+export const MAX_EXECUTE_REQUEST_BYTES = 256 * 1024;
+export const MAX_PERSISTED_RUNTIME_TEXT_BYTES = 8 * 1024;
+export const MAX_POSSIBLE_RESOURCES = 32;
+const ID_PATTERN = "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$";
+const OID_PATTERN = "^(?:[0-9a-f]{40}|[0-9a-f]{64})$";
+const TOKEN_PATTERN = "^[A-Za-z0-9_-]{16,128}$";
+const IdSchema = Type.String({ minLength: 1, maxLength: 80, pattern: ID_PATTERN });
+const TextSchema = Type.String({ minLength: 1, maxLength: 32_000 });
+const RoleNameSchema = Type.String({ minLength: 1, maxLength: 32_000 });
+const RuntimeTextSchema = Type.String({ minLength: 1, maxLength: MAX_PERSISTED_RUNTIME_TEXT_BYTES });
+const OptionalRuntimeTextSchema = Type.Optional(Type.String({ maxLength: MAX_PERSISTED_RUNTIME_TEXT_BYTES }));
+const TimestampSchema = Type.Integer({ minimum: 0 });
+const ModelClassSchema = Type.Union([
+    Type.Literal("fast"),
+    Type.Literal("balanced"),
+    Type.Literal("frontier"),
+    Type.Literal("fav"),
+]);
+export const CheckCommandSchema = Type.Object({
+    command: TextSchema,
+    args: Type.Array(Type.String({ maxLength: 16_000 }), { maxItems: 128 }),
+}, { additionalProperties: false });
+export const JudgmentSchema = Type.Object({
+    role: RoleNameSchema,
+    modelClass: ModelClassSchema,
+    criterion: TextSchema,
+}, { additionalProperties: false });
+const TaskRequestBaseFields = {
+    role: RoleNameSchema,
+    modelClass: ModelClassSchema,
+    requirements: TextSchema,
+    deliverable: TextSchema,
+    dependsOn: Type.Array(IdSchema, { maxItems: MAX_TASKS }),
+    contextFrom: Type.Array(IdSchema, { maxItems: MAX_TASKS }),
+};
+const TextTaskRequestSchema = Type.Object({
+    id: IdSchema,
+    kind: Type.Literal("text"),
+    ...TaskRequestBaseFields,
+}, { additionalProperties: false });
+const ChangesetTaskRequestSchema = Type.Object({
+    id: IdSchema,
+    kind: Type.Literal("changeset"),
+    ...TaskRequestBaseFields,
+    checks: Type.Array(CheckCommandSchema, { minItems: 1, maxItems: 32 }),
+    judgment: Type.Optional(JudgmentSchema),
+}, { additionalProperties: false });
+export const TaskRequestSchema = Type.Union([TextTaskRequestSchema, ChangesetTaskRequestSchema]);
+export const ExecuteRequestSchema = Type.Object({
+    mode: Type.Literal("isolated"),
+    id: IdSchema,
+    goal: TextSchema,
+    tasks: Type.Array(TaskRequestSchema, { minItems: 1, maxItems: MAX_TASKS }),
+    finalChecks: Type.Optional(Type.Array(CheckCommandSchema, { maxItems: 32 })),
+    finalJudgment: Type.Optional(JudgmentSchema),
+}, { additionalProperties: false });
+export const IdOnlySchema = Type.Object({ id: IdSchema }, { additionalProperties: false });
+export const ResumeRequestSchema = Type.Union([
+    Type.Object({ id: IdSchema, action: Type.Literal("retry"), taskId: IdSchema }, { additionalProperties: false }),
+    Type.Object({ id: IdSchema, action: Type.Literal("verify"), taskId: IdSchema }, { additionalProperties: false }),
+    Type.Object({ id: IdSchema, action: Type.Literal("finalize") }, { additionalProperties: false }),
+]);
+const AllocationLifecycleFields = {
+    generation: Type.Integer({ minimum: 1, maximum: 2 }),
+    token: Type.String({ pattern: TOKEN_PATTERN }),
+    status: Type.Union([
+        Type.Literal("allocating"), Type.Literal("owned"), Type.Literal("absent"), Type.Literal("unknown"),
+    ]),
+    possibleResources: Type.Optional(Type.Array(RuntimeTextSchema, { maxItems: MAX_POSSIBLE_RESOURCES })),
+    failure: OptionalRuntimeTextSchema,
+};
+const WorktreeRecordSchema = Type.Object({
+    path: RuntimeTextSchema,
+    cwd: RuntimeTextSchema,
+    branch: RuntimeTextSchema,
+    repoRoot: RuntimeTextSchema,
+    baseCommit: Type.String({ pattern: OID_PATTERN }),
+}, { additionalProperties: false });
+const WorktreeAllocationIntentSchema = Type.Object({
+    kind: Type.Literal("worktree"),
+    ...AllocationLifecycleFields,
+    worktree: Type.Optional(WorktreeRecordSchema),
+}, { additionalProperties: false });
+const WorkspaceAllocationIntentSchema = Type.Object({
+    kind: Type.Literal("workspace"),
+    ...AllocationLifecycleFields,
+    label: RuntimeTextSchema,
+    worktreeCwd: RuntimeTextSchema,
+    mainRoot: RuntimeTextSchema,
+    repoKey: RuntimeTextSchema,
+    herdrRepoRoot: RuntimeTextSchema,
+    workspaceId: Type.Optional(RuntimeTextSchema),
+    rootTabId: Type.Optional(RuntimeTextSchema),
+    rootPaneId: Type.Optional(RuntimeTextSchema),
+}, { additionalProperties: false });
+const WorkerTabAllocationIntentSchema = Type.Object({
+    kind: Type.Literal("worker_tab"),
+    ...AllocationLifecycleFields,
+    label: RuntimeTextSchema,
+    workspaceId: RuntimeTextSchema,
+    workspaceRootTabId: RuntimeTextSchema,
+    workspaceRootPaneId: RuntimeTextSchema,
+    worktreeCwd: RuntimeTextSchema,
+    leasePath: RuntimeTextSchema,
+    tabId: Type.Optional(RuntimeTextSchema),
+    paneId: Type.Optional(RuntimeTextSchema),
+}, { additionalProperties: false });
+const AgentAllocationIntentSchema = Type.Object({
+    kind: Type.Literal("agent"),
+    ...AllocationLifecycleFields,
+    agentName: RuntimeTextSchema,
+    workspaceId: RuntimeTextSchema,
+    tabId: RuntimeTextSchema,
+    paneId: RuntimeTextSchema,
+    worktreeCwd: RuntimeTextSchema,
+    leasePath: RuntimeTextSchema,
+}, { additionalProperties: false });
+export const AllocationIntentSchema = Type.Union([
+    WorktreeAllocationIntentSchema,
+    WorkspaceAllocationIntentSchema,
+    WorkerTabAllocationIntentSchema,
+    AgentAllocationIntentSchema,
+]);
+export const CLEANUP_KINDS = ["worker_tab", "workspace", "worktree", "branch"];
+const WorkspaceSchema = Type.Object({
+    branch: RuntimeTextSchema,
+    head: Type.String({ pattern: OID_PATTERN }),
+    index: Type.String({ pattern: OID_PATTERN }),
+    tree: Type.String({ pattern: OID_PATTERN }),
+}, { additionalProperties: false });
+export const StageRequestSchema = Type.Object({
+    id: IdSchema,
+    action: Type.Union([Type.Literal("stage"), Type.Literal("resolve"), Type.Literal("reject"), Type.Literal("revise")]),
+    generation: Type.Integer({ minimum: 1, maximum: 32 }),
+    taskId: IdSchema,
+    attempt: Type.Integer({ minimum: 1, maximum: 2 }),
+    candidate: WorkspaceSchema,
+    expectedTip: WorkspaceSchema,
+    instruction: Type.Optional(TextSchema),
+}, { additionalProperties: false });
+export const IntegrationActionSchema = Type.Union([
+    Type.Object({
+        id: IdSchema,
+        generation: Type.Integer({ minimum: 1, maximum: 32 }),
+        action: Type.Literal("refresh"),
+        expectedTip: WorkspaceSchema,
+        expectedMain: WorkspaceSchema,
+        newMain: WorkspaceSchema,
+    }, { additionalProperties: false }),
+    Type.Object({
+        id: IdSchema,
+        generation: Type.Integer({ minimum: 1, maximum: 32 }),
+        action: Type.Union([Type.Literal("advance"), Type.Literal("validate"), Type.Literal("correct"), Type.Literal("promote"), Type.Literal("reconcile"), Type.Literal("cleanup")]),
+        expectedTip: WorkspaceSchema,
+    }, { additionalProperties: false }),
+    Type.Object({
+        id: IdSchema,
+        generation: Type.Integer({ minimum: 1, maximum: 32 }),
+        action: Type.Literal("release"),
+        expectedTip: WorkspaceSchema,
+        taskId: Type.Optional(IdSchema),
+        attempt: Type.Optional(Type.Integer({ minimum: 1, maximum: 2 })),
+    }, { additionalProperties: false }),
+]);
+export function parseIntegrationAction(value) {
+    if (!Check(IntegrationActionSchema, value))
+        throw schemaValidationError("subagent_integrate requires an exact generation and tip", Errors(IntegrationActionSchema, value));
+    return value;
+}
+export function parseStageRequest(value) {
+    if (!Check(StageRequestSchema, value))
+        throw schemaValidationError("subagent_stage request must match exact candidate and generation", Errors(StageRequestSchema, value));
+    return value;
+}
+const PromptRecordSchema = Type.Object({
+    kind: Type.Union([Type.Literal("initial"), Type.Literal("correction"), Type.Literal("followup")]),
+    status: Type.Union([Type.Literal("submitting"), Type.Literal("not_sent"), Type.Literal("settled"), Type.Literal("ambiguous")]),
+    preCandidate: WorkspaceSchema,
+    candidate: Type.Optional(WorkspaceSchema),
+    instruction: Type.Optional(TextSchema),
+    failure: OptionalRuntimeTextSchema,
+    at: TimestampSchema,
+}, { additionalProperties: false });
+const CommandEvidenceSchema = Type.Object({
+    command: TextSchema,
+    args: Type.Array(Type.String({ maxLength: 16_000 }), { maxItems: 128 }),
+    code: Type.Integer(),
+    killed: Type.Boolean(),
+    stdout: Type.String({ maxLength: MAX_PERSISTED_RUNTIME_TEXT_BYTES }),
+    stderr: Type.String({ maxLength: MAX_PERSISTED_RUNTIME_TEXT_BYTES }),
+}, { additionalProperties: false });
+const CheckBatchEvidenceSchema = Type.Object({
+    phase: Type.Union([Type.Literal("preliminary"), Type.Literal("final")]),
+    candidate: WorkspaceSchema,
+    identityAfter: WorkspaceSchema,
+    results: Type.Array(CommandEvidenceSchema, { maxItems: 32 }),
+    passed: Type.Boolean(),
+    at: TimestampSchema,
+}, { additionalProperties: false });
+const ReviewEvidenceSchema = Type.Object({
+    phase: Type.Union([Type.Literal("preliminary"), Type.Literal("final")]),
+    criterion: TextSchema,
+    base: WorkspaceSchema,
+    tip: WorkspaceSchema,
+    identityAfter: WorkspaceSchema,
+    verdict: Type.String({ maxLength: MAX_PERSISTED_RUNTIME_TEXT_BYTES }),
+    passed: Type.Boolean(),
+    at: TimestampSchema,
+}, { additionalProperties: false });
+const WorkerTerminationSchema = Type.Object({
+    status: Type.Union([Type.Literal("terminating"), Type.Literal("terminated"), Type.Literal("unknown")]),
+    workerId: RuntimeTextSchema,
+    candidate: WorkspaceSchema,
+    at: Type.Optional(TimestampSchema),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const ReadinessSchema = Type.Object({
+    candidate: WorkspaceSchema,
+    base: WorkspaceSchema,
+    at: TimestampSchema,
+}, { additionalProperties: false });
+const CleanupStepSchema = Type.Object({
+    kind: Type.Union([
+        Type.Literal("worker_tab"), Type.Literal("workspace"), Type.Literal("worktree"), Type.Literal("branch"),
+    ]),
+    status: Type.Union([Type.Literal("pending"), Type.Literal("running"), Type.Literal("completed")]),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const TaskAttemptSchema = Type.Object({
+    number: Type.Integer({ minimum: 1, maximum: 2 }),
+    waveNumber: Type.Integer({ minimum: 1 }),
+    waveBase: WorkspaceSchema,
+    correlationToken: Type.String({ pattern: TOKEN_PATTERN }),
+    allocationGeneration: Type.Integer({ minimum: 1, maximum: 2 }),
+    allocations: Type.Array(AllocationIntentSchema, { maxItems: 5 }),
+    prompts: Type.Array(PromptRecordSchema, { maxItems: 32 }),
+    candidate: Type.Optional(WorkspaceSchema),
+    candidateBase: Type.Optional(WorkspaceSchema),
+    preliminaryChecks: Type.Optional(CheckBatchEvidenceSchema),
+    readiness: Type.Optional(ReadinessSchema),
+    superseded: Type.Optional(Type.Literal(true)),
+    termination: Type.Optional(WorkerTerminationSchema),
+    preliminaryReview: Type.Optional(ReviewEvidenceSchema),
+    cleanup: Type.Array(CleanupStepSchema, { minItems: CLEANUP_KINDS.length, maxItems: CLEANUP_KINDS.length }),
+}, { additionalProperties: false });
+const ChangesetTaskStateSchema = Type.Object({
+    taskId: IdSchema,
+    kind: Type.Literal("changeset"),
+    status: Type.Union([
+        Type.Literal("pending"), Type.Literal("allocating"), Type.Literal("working"), Type.Literal("ready_to_integrate"),
+        Type.Literal("integrating"), Type.Literal("cleanup"), Type.Literal("completed"), Type.Literal("rejected"), Type.Literal("needs_attention"),
+    ]),
+    attempts: Type.Array(TaskAttemptSchema, { maxItems: 2 }),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const TextTaskOutputSchema = Type.Object({
+    text: RuntimeTextSchema,
+}, { additionalProperties: false });
+const TextTaskAttemptSchema = Type.Object({
+    number: Type.Integer({ minimum: 1, maximum: 2 }),
+    status: Type.Union([Type.Literal("running"), Type.Literal("completed"), Type.Literal("failed"), Type.Literal("superseded")]),
+    failure: OptionalRuntimeTextSchema,
+    output: Type.Optional(TextTaskOutputSchema),
+}, { additionalProperties: false });
+const TextTaskStateSchema = Type.Object({
+    taskId: IdSchema,
+    kind: Type.Literal("text"),
+    status: Type.Union([
+        Type.Literal("pending"), Type.Literal("running"), Type.Literal("completed"), Type.Literal("needs_attention"),
+    ]),
+    attempts: Type.Array(TextTaskAttemptSchema, { maxItems: 2 }),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const TaskStateSchema = Type.Union([TextTaskStateSchema, ChangesetTaskStateSchema]);
+const WaveStateSchema = Type.Object({
+    number: Type.Integer({ minimum: 1 }),
+    base: WorkspaceSchema,
+    taskIds: Type.Array(IdSchema, { minItems: 1, maxItems: MAX_TASKS }),
+    status: Type.Union([Type.Literal("dispatching"), Type.Literal("integrating"), Type.Literal("completed"), Type.Literal("needs_attention")]),
+}, { additionalProperties: false });
+const FinalGateSchema = Type.Object({
+    status: Type.Union([
+        Type.Literal("pending"), Type.Literal("running"), Type.Literal("interrupted"), Type.Literal("passed"),
+        Type.Literal("final_failed"), Type.Literal("superseded"),
+    ]),
+    identity: Type.Optional(WorkspaceSchema),
+    checks: Type.Optional(CheckBatchEvidenceSchema),
+    review: Type.Optional(ReviewEvidenceSchema),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const ExecutionPolicySnapshotSchema = Type.Object({
+    maxSubagents: Type.Integer({ minimum: 1 }),
+    maxTurns: Type.Integer({ minimum: 1 }),
+    maxTokens: Type.Optional(Type.Integer({ minimum: 1 })),
+    childIdleMs: Type.Number({ exclusiveMinimum: 0, maximum: 2_147_483_647 }),
+    childMaxMs: Type.Number({ exclusiveMinimum: 0, maximum: 2_147_483_647 }),
+    maxCorrections: Type.Integer({ minimum: 0 }),
+}, { additionalProperties: false });
+// Main-owned integration state binds each ready candidate to its retained attempt.
+const IntegrationCandidateSchema = Type.Object({
+    taskId: IdSchema,
+    attempt: Type.Integer({ minimum: 1, maximum: 2 }),
+    base: WorkspaceSchema,
+    tip: WorkspaceSchema,
+    checks: CheckBatchEvidenceSchema,
+    review: Type.Optional(ReviewEvidenceSchema),
+    worker: Type.Union([Type.Literal("retained"), Type.Literal("release_pending"), Type.Literal("released")]),
+    decision: Type.Optional(Type.Literal("rejected")),
+}, { additionalProperties: false });
+const IntegrationStageSchema = Type.Object({
+    taskId: IdSchema,
+    attempt: Type.Integer({ minimum: 1, maximum: 2 }),
+    source: WorkspaceSchema,
+    onto: WorkspaceSchema,
+    status: Type.Union([Type.Literal("pending"), Type.Literal("staging"), Type.Literal("staged"), Type.Literal("conflict")]),
+    tip: Type.Optional(WorkspaceSchema),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const PromotionSchema = Type.Object({
+    status: Type.Union([Type.Literal("promoting"), Type.Literal("promoted"), Type.Literal("unknown"), Type.Literal("failed")]),
+    expectedMain: WorkspaceSchema,
+    tip: WorkspaceSchema,
+    mainAfter: Type.Optional(WorkspaceSchema),
+    outcome: Type.Optional(Type.Literal("drift")),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+const IntegrationGenerationSchema = Type.Object({
+    number: Type.Integer({ minimum: 1, maximum: 32 }),
+    status: Type.Union([
+        Type.Literal("staging"), Type.Literal("conflict"), Type.Literal("validating"), Type.Literal("validation_failed"),
+        Type.Literal("ready"), Type.Literal("promoting"), Type.Literal("promoted"),
+        Type.Literal("promotion_unknown"), Type.Literal("promotion_failed"), Type.Literal("superseded"),
+    ]),
+    expectedMain: WorkspaceSchema,
+    integrationBase: WorkspaceSchema,
+    order: Type.Array(IdSchema, { maxItems: MAX_TASKS }),
+    stages: Type.Array(IntegrationStageSchema, { maxItems: MAX_TASKS }),
+    worktree: Type.Optional(WorktreeRecordSchema),
+    combinedTip: Type.Optional(WorkspaceSchema),
+    correction: Type.Optional(Type.Object({ from: WorkspaceSchema, to: WorkspaceSchema }, { additionalProperties: false })),
+    checks: Type.Optional(CheckBatchEvidenceSchema),
+    review: Type.Optional(ReviewEvidenceSchema),
+    promotion: Type.Optional(PromotionSchema),
+    supersededPromotion: Type.Optional(PromotionSchema),
+    cleanup: Type.Optional(Type.Array(CleanupStepSchema, { minItems: 2, maxItems: 2 })),
+    supersededFrom: Type.Optional(Type.Union([
+        Type.Literal("staging"), Type.Literal("conflict"), Type.Literal("validation_failed"),
+        Type.Literal("ready"), Type.Literal("promotion_failed"),
+    ])),
+    failure: OptionalRuntimeTextSchema,
+}, { additionalProperties: false });
+export const IntegrationStateSchema = Type.Object({
+    candidates: Type.Array(IntegrationCandidateSchema, { maxItems: MAX_TASKS * 2 }),
+    generations: Type.Array(IntegrationGenerationSchema, { maxItems: 32 }),
+    refresh: Type.Optional(Type.Object({
+        from: WorkspaceSchema,
+        to: WorkspaceSchema,
+        generation: Type.Integer({ minimum: 1, maximum: 32 }),
+        status: Type.Union([Type.Literal("pending"), Type.Literal("ready"), Type.Literal("unknown")]),
+        failure: OptionalRuntimeTextSchema,
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+const RunStateSchema = Type.Object({
+    version: Type.Literal(RUN_STATE_VERSION),
+    request: ExecuteRequestSchema,
+    policy: ExecutionPolicySnapshotSchema,
+    correctionCount: Type.Integer({ minimum: 0 }),
+    root: TextSchema,
+    requestStartMain: WorkspaceSchema,
+    main: WorkspaceSchema,
+    status: Type.Union([
+        Type.Literal("pending"), Type.Literal("running"), Type.Literal("needs_attention"), Type.Literal("completed"),
+        Type.Literal("final_failed"), Type.Literal("superseded"), Type.Literal("aborted"),
+    ]),
+    tasks: Type.Array(TaskStateSchema, { minItems: 1, maxItems: MAX_TASKS }),
+    waves: Type.Array(WaveStateSchema, { maxItems: MAX_TASKS }),
+    integration: IntegrationStateSchema,
+    final: FinalGateSchema,
+    recovery: Type.Optional(Type.Object({
+        kind: Type.Literal("resume"),
+        action: Type.Union([Type.Literal("retry"), Type.Literal("verify"), Type.Literal("finalize")]),
+        taskId: Type.Optional(IdSchema),
+    }, { additionalProperties: false })),
+    accepted: Type.Boolean(),
+    acceptedAt: Type.Optional(TimestampSchema),
+    createdAt: TimestampSchema,
+    updatedAt: TimestampSchema,
+}, { additionalProperties: false });
+function normalizeCheck(check, field) {
+    return {
+        command: normalizeText(check.command, `${field}.command`),
+        args: check.args.map((arg, index) => {
+            if (arg.includes("\0"))
+                throw new Error(`${field}.args[${index}] must not contain NUL bytes.`);
+            return arg;
+        }),
+    };
+}
+function normalizeText(value, field) {
+    const normalized = value.trim();
+    if (!normalized || value.includes("\0"))
+        throw new Error(`${field} must be non-empty text without NUL bytes.`);
+    return normalized;
+}
+function normalizeRole(value, field) {
+    return parseRoleName(value, field);
+}
+function normalizeJudgment(judgment, field) {
+    if (!judgment)
+        return;
+    return {
+        ...judgment,
+        role: normalizeRole(judgment.role, `${field}.role`),
+        criterion: normalizeText(judgment.criterion, `${field}.criterion`),
+    };
+}
+function normalizeTask(task, index) {
+    const fields = {
+        id: task.id,
+        role: normalizeRole(task.role, `tasks[${index}].role`),
+        modelClass: task.modelClass,
+        requirements: normalizeText(task.requirements, `tasks[${index}].requirements`),
+        deliverable: normalizeText(task.deliverable, `tasks[${index}].deliverable`),
+        dependsOn: [...task.dependsOn],
+        contextFrom: [...task.contextFrom],
+    };
+    if (task.kind === "text")
+        return { ...fields, kind: "text" };
+    return {
+        ...fields,
+        kind: "changeset",
+        checks: task.checks.map((check, checkIndex) => normalizeCheck(check, `tasks[${index}].checks[${checkIndex}]`)),
+        ...(task.judgment ? { judgment: normalizeJudgment(task.judgment, `tasks[${index}].judgment`) } : {}),
+    };
+}
+export function taskDependencies(task) {
+    return [...task.dependsOn, ...task.contextFrom];
+}
+export function validateGraph(tasks) {
+    const byId = new Map();
+    for (const task of tasks) {
+        if (byId.has(task.id))
+            throw new Error(`Duplicate task ID: ${task.id}.`);
+        byId.set(task.id, task);
+        const dependencies = new Set();
+        for (const dependency of task.dependsOn) {
+            if (dependency === task.id)
+                throw new Error(`Task ${task.id} cannot depend on itself.`);
+            if (dependencies.has(dependency))
+                throw new Error(`Task ${task.id} has duplicate dependency ${dependency}.`);
+            dependencies.add(dependency);
+        }
+        const context = new Set();
+        for (const source of task.contextFrom) {
+            if (source === task.id)
+                throw new Error(`Task ${task.id} cannot depend on itself.`);
+            if (context.has(source))
+                throw new Error(`Task ${task.id} has duplicate context source ${source}.`);
+            if (dependencies.has(source))
+                throw new Error(`Task ${task.id} has overlapping dependsOn and contextFrom edge ${source}.`);
+            context.add(source);
+        }
+    }
+    for (const task of tasks) {
+        for (const dependency of task.dependsOn) {
+            if (!byId.has(dependency))
+                throw new Error(`Task ${task.id} has unknown dependency ${dependency}.`);
+        }
+        for (const source of task.contextFrom) {
+            const sourceTask = byId.get(source);
+            if (!sourceTask)
+                throw new Error(`Task ${task.id} has unknown context source ${source}.`);
+            if (sourceTask.kind !== "text")
+                throw new Error(`Task ${task.id} context source ${source} must be a text task.`);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw new Error(`Task dependency cycle includes ${id}.`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of taskDependencies(byId.get(id)))
+            visit(dependency);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const task of tasks)
+        visit(task.id);
+}
+function schemaIssuePath(issue) {
+    const propertyKey = issue.keyword === "additionalProperties" ? "additionalProperties"
+        : issue.keyword === "required" ? "requiredProperties"
+            : undefined;
+    const properties = propertyKey ? issue.params?.[propertyKey] : undefined;
+    if (!Array.isArray(properties) || properties.length !== 1 || typeof properties[0] !== "string") {
+        return issue.instancePath;
+    }
+    const property = properties[0].replaceAll("~", "~0").replaceAll("/", "~1");
+    return `${issue.instancePath}/${property}`;
+}
+function schemaValidationError(label, issues) {
+    let selected;
+    for (const issue of issues) {
+        const path = schemaIssuePath(issue);
+        if (!selected || path.length > selected.path.length)
+            selected = { issue, path };
+    }
+    if (!selected)
+        return new Error(`${label}.`);
+    const rawDetail = ` at ${selected.path || "/"}: ${selected.issue.message}`;
+    const detail = rawDetail.length <= 512 ? rawDetail : `${rawDetail.slice(0, 509)}...`;
+    return new Error(`${label}${detail}.`);
+}
+export function parseExecuteRequest(value) {
+    if (!Check(ExecuteRequestSchema, value)) {
+        throw schemaValidationError("isolated delegate_task request must match the strict task schema", Errors(ExecuteRequestSchema, value));
+    }
+    const input = value;
+    const tasks = input.tasks.map(normalizeTask);
+    const finalChecks = (input.finalChecks ?? []).map((check, index) => normalizeCheck(check, `finalChecks[${index}]`));
+    if (tasks.some((task) => task.kind === "changeset") && finalChecks.length === 0) {
+        throw new Error("isolated changeset graphs require at least one final check.");
+    }
+    const request = {
+        ...input,
+        mode: "isolated",
+        goal: normalizeText(input.goal, "goal"),
+        tasks,
+        finalChecks,
+        ...(input.finalJudgment ? { finalJudgment: normalizeJudgment(input.finalJudgment, "finalJudgment") } : {}),
+    };
+    if (Buffer.byteLength(JSON.stringify(request), "utf8") > MAX_EXECUTE_REQUEST_BYTES) {
+        throw new Error(`isolated delegate_task normalized request exceeds ${MAX_EXECUTE_REQUEST_BYTES} bytes.`);
+    }
+    validateGraph(request.tasks);
+    return request;
+}
+export function parseIdOnly(value) {
+    if (!Check(IdOnlySchema, value)) {
+        throw schemaValidationError("subagent request ID must match the strict schema", Errors(IdOnlySchema, value));
+    }
+    return value;
+}
+export function parseResumeRequest(value) {
+    if (!Check(ResumeRequestSchema, value)) {
+        throw schemaValidationError("subagent_resume request must match one strict action", Errors(ResumeRequestSchema, value));
+    }
+    return value;
+}
+export function sameIdentity(left, right) {
+    return left.branch === right.branch && left.head === right.head && left.index === right.index && left.tree === right.tree;
+}
+export function isCleanCommitted(identity) {
+    return identity.index === identity.tree;
+}
+function sameCheck(left, right) {
+    return left.command === right.command
+        && left.args.length === right.args.length
+        && left.args.every((arg, index) => arg === right.args[index]);
+}
+function hasWorktreePlan(allocation) {
+    return allocation.worktree !== undefined;
+}
+function requireExactAllocationText(value, field) {
+    if (!value.trim() || value.trim() !== value || value.includes("\0")) {
+        throw new Error(`${field} must be exact non-empty text.`);
+    }
+}
+function requireAbsoluteAllocationPath(value, field) {
+    requireExactAllocationText(value, field);
+    if (!isAbsolute(value))
+        throw new Error(`${field} must be an absolute path.`);
+}
+function validateCheckBatchEvidence(evidence, checks, field) {
+    if (evidence.results.length !== checks.length
+        || evidence.results.some((result, index) => !sameCheck(result, checks[index]))) {
+        throw new Error(`${field} does not retain every exact declared command and argv.`);
+    }
+    const commandsPassed = evidence.results.every((result) => result.code === 0 && !result.killed);
+    const identityMatches = sameIdentity(evidence.candidate, evidence.identityAfter);
+    if (evidence.passed !== (commandsPassed && identityMatches)) {
+        throw new Error(`${field} has an inconsistent pass result.`);
+    }
+    let diagnosticIndex = evidence.passed
+        ? -1
+        : evidence.results.findIndex((result) => result.code !== 0 || result.killed);
+    if (diagnosticIndex < 0 && commandsPassed && !identityMatches)
+        diagnosticIndex = evidence.results.length - 1;
+    if (evidence.results.some((result, index) => index !== diagnosticIndex && (result.stdout !== "" || result.stderr !== ""))) {
+        throw new Error(`${field} retains non-diagnostic command output.`);
+    }
+}
+export function checkBatchPasses(evidence, checks, candidate) {
+    return Boolean(evidence
+        && evidence.passed
+        && sameIdentity(evidence.candidate, candidate)
+        && sameIdentity(evidence.identityAfter, candidate)
+        && evidence.results.length === checks.length
+        && evidence.results.every((result, index) => sameCheck(result, checks[index]) && result.code === 0 && !result.killed));
+}
+export function reviewEvidencePasses(evidence, phase, criterion, base, tip) {
+    return Boolean(evidence
+        && evidence.phase === phase
+        && evidence.passed
+        && evidence.verdict === "PASS"
+        && evidence.criterion === criterion
+        && sameIdentity(evidence.base, base)
+        && sameIdentity(evidence.tip, tip)
+        && sameIdentity(evidence.identityAfter, tip));
+}
+function requireRuntimeTextByteLength(value, field) {
+    if (Buffer.byteLength(value, "utf8") > MAX_PERSISTED_RUNTIME_TEXT_BYTES) {
+        throw new Error(`${field} exceeds ${MAX_PERSISTED_RUNTIME_TEXT_BYTES} UTF-8 bytes.`);
+    }
+}
+function validateTextTaskState(taskState) {
+    const latest = taskState.attempts.at(-1);
+    for (const [attemptIndex, attempt] of taskState.attempts.entries()) {
+        if (attempt.number !== attemptIndex + 1)
+            throw new Error(`Malformed text attempt order for ${taskState.taskId}.`);
+        if (attemptIndex !== taskState.attempts.length - 1) {
+            if (!['failed', 'superseded'].includes(attempt.status) || attempt.output) {
+                throw new Error(`Non-latest text attempt ${attempt.number} for ${taskState.taskId} must be failed or superseded with no output.`);
+            }
+        }
+        else if (attempt.status === "completed") {
+            if (!attempt.output)
+                throw new Error(`Completed text attempt ${attempt.number} for ${taskState.taskId} lacks output.`);
+        }
+        else if (attempt.output) {
+            throw new Error(`Text attempt ${attempt.number} for ${taskState.taskId} has output without completion.`);
+        }
+        if (attempt.output) {
+            requireRuntimeTextByteLength(attempt.output.text, `Text attempt ${attempt.number} for ${taskState.taskId} output`);
+        }
+        if (attempt.failure !== undefined) {
+            if (attempt.status !== "failed") {
+                throw new Error(`Text attempt ${attempt.number} for ${taskState.taskId} has failure without failure status.`);
+            }
+            requireRuntimeTextByteLength(attempt.failure, `Text attempt ${attempt.number} for ${taskState.taskId} failure`);
+        }
+    }
+    const expectedLatestStatus = taskState.status === "pending"
+        ? taskState.attempts.length ? "superseded" : undefined
+        : taskState.status === "running"
+            ? "running"
+            : taskState.status === "completed"
+                ? "completed"
+                : "failed";
+    if (latest?.status !== expectedLatestStatus) {
+        throw new Error(`Text task ${taskState.taskId} status ${taskState.status} has an incompatible latest attempt.`);
+    }
+    if ((taskState.failure !== undefined) !== (taskState.status === "needs_attention")) {
+        throw new Error(`Text task ${taskState.taskId} must retain a failure exactly when it needs attention.`);
+    }
+    if (taskState.failure !== undefined) {
+        requireRuntimeTextByteLength(taskState.failure, `Text task ${taskState.taskId} failure`);
+    }
+    if (taskState.status === "needs_attention" && latest?.failure !== taskState.failure) {
+        throw new Error(`Text task ${taskState.taskId} needs-attention failure must exactly match its latest attempt failure.`);
+    }
+}
+/** Check the persisted integration projection against the request before recovery or promotion. */
+export function parseIntegrationState(value, request) {
+    if (!Check(IntegrationStateSchema, value)) {
+        throw schemaValidationError("Malformed integration state", Errors(IntegrationStateSchema, value));
+    }
+    const state = value;
+    const tasks = new Map(request.tasks.filter((task) => task.kind === "changeset")
+        .map((task) => [task.id, task]));
+    const candidates = new Map();
+    const latestCandidates = new Map();
+    for (const candidate of state.candidates) {
+        const task = tasks.get(candidate.taskId);
+        const previous = latestCandidates.get(candidate.taskId);
+        const key = `${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`;
+        if (!task || candidates.has(key) || (previous && (candidate.attempt < previous.attempt
+            || candidate.attempt === previous.attempt && previous.decision !== "rejected")) || !isCleanCommitted(candidate.base)
+            || !isCleanCommitted(candidate.tip) || candidate.base.head === candidate.tip.head
+            || candidate.checks.phase !== "preliminary") {
+            throw new Error(`Invalid ready candidate for ${candidate.taskId}.`);
+        }
+        validateCheckBatchEvidence(candidate.checks, task.checks, `Ready checks for ${candidate.taskId}`);
+        if (!checkBatchPasses(candidate.checks, task.checks, candidate.tip)
+            || (task.judgment && !reviewEvidencePasses(candidate.review, "preliminary", task.judgment.criterion, candidate.base, candidate.tip))
+            || (!task.judgment && candidate.review !== undefined)) {
+            throw new Error(`Ready candidate ${candidate.taskId} lacks exact passing evidence.`);
+        }
+        candidates.set(key, candidate);
+        latestCandidates.set(candidate.taskId, candidate);
+    }
+    const refresh = state.refresh;
+    if (refresh && (!isCleanCommitted(refresh.from) || !isCleanCommitted(refresh.to)
+        || refresh.from.branch !== refresh.to.branch || refresh.from.head === refresh.to.head
+        || refresh.generation !== state.generations.length + (refresh.status === "pending" ? 1 : 0)
+        || (refresh.status === "ready" ? refresh.failure !== undefined : refresh.failure !== undefined && !refresh.failure.trim())
+        || (refresh.generation > 1 && (state.generations[refresh.generation - 2]?.status !== "superseded"
+            || !sameIdentity(state.generations[refresh.generation - 2].expectedMain, refresh.from))))) {
+        throw new Error("Refresh intent has invalid Main lineage or status.");
+    }
+    for (const [index, generation] of state.generations.entries()) {
+        if (generation.number !== index + 1 || (index > 0 && state.generations[index - 1].status !== "superseded")) {
+            throw new Error("Integration generations must be ordered and superseded before replacement.");
+        }
+        if (!isCleanCommitted(generation.expectedMain) || !isCleanCommitted(generation.integrationBase)
+            || generation.integrationBase.head !== generation.expectedMain.head
+            || generation.integrationBase.index !== generation.expectedMain.index
+            || generation.integrationBase.tree !== generation.expectedMain.tree) {
+            throw new Error(`Integration generation ${generation.number} has an invalid Main base.`);
+        }
+        if (generation.worktree) {
+            for (const path of [generation.worktree.path, generation.worktree.cwd, generation.worktree.repoRoot]) {
+                requireAbsoluteAllocationPath(path, `Generation ${generation.number} worktree path`);
+            }
+            if (generation.worktree.baseCommit !== generation.expectedMain.head
+                || generation.worktree.path !== generation.worktree.cwd
+                || generation.integrationBase.branch !== `refs/heads/${generation.worktree.branch}`) {
+                throw new Error(`Generation ${generation.number} has a mismatched integration worktree.`);
+            }
+        }
+        if (refresh?.generation === generation.number) {
+            if (!sameIdentity(generation.expectedMain, refresh.to)
+                || (refresh.status === "unknown" && (generation.order.length || generation.stages.length))
+                || refresh.status === "pending")
+                throw new Error("Refreshed generation does not match its durable intent.");
+        }
+        if (!generation.order.length && (!generation.worktree
+            || (generation.status !== "superseded" && (index !== state.generations.length - 1 || !refresh
+                || refresh.generation !== generation.number || generation.status !== "staging"))
+            || generation.stages.length || generation.combinedTip || generation.checks || generation.review || generation.promotion)) {
+            throw new Error("Empty integration generation requires an exact refreshed worktree.");
+        }
+        const chosen = new Set(generation.order);
+        if (chosen.size !== generation.order.length || generation.order.some((id) => !latestCandidates.has(id))
+            || generation.stages.length > generation.order.length) {
+            throw new Error(`Generation ${generation.number} must choose distinct ready candidates in explicit order.`);
+        }
+        let previous = generation.integrationBase;
+        let unfinished = false;
+        for (const [stageIndex, stage] of generation.stages.entries()) {
+            const candidate = candidates.get(`${stage.taskId}\0${stage.attempt}\0${stage.source.head}`);
+            if (!candidate || !sameIdentity(stage.source, candidate.tip)
+                || generation.order[stageIndex] !== stage.taskId || !sameIdentity(stage.onto, previous) || unfinished) {
+                throw new Error(`Stage ${stageIndex + 1} breaks generation ${generation.number} lineage.`);
+            }
+            if (generation.status !== "superseded" && (candidate !== latestCandidates.get(stage.taskId) || candidate.decision)) {
+                throw new Error(`Stage ${stageIndex + 1} does not use the latest ready attempt.`);
+            }
+            const definition = tasks.get(stage.taskId);
+            const predecessorIds = definition.dependsOn.filter((id) => tasks.has(id));
+            if (predecessorIds.some((id) => !generation.stages.slice(0, stageIndex).some((prior) => prior.taskId === id && prior.status === "staged"))) {
+                throw new Error(`Stage ${stageIndex + 1} is missing its staged changeset predecessor.`);
+            }
+            if (stage.status === "staged") {
+                if (!stage.tip || stage.failure !== undefined || !isCleanCommitted(stage.tip)
+                    || stage.tip.branch !== generation.integrationBase.branch) {
+                    throw new Error(`Stage ${stageIndex + 1} lacks a clean staged tip.`);
+                }
+                previous = stage.tip;
+            }
+            else {
+                if (stage.tip || (stage.status === "conflict" && !stage.failure?.trim())
+                    || (stage.status === "pending" && stage.failure !== undefined)) {
+                    throw new Error(`Stage ${stageIndex + 1} has inconsistent pending outcome evidence.`);
+                }
+                unfinished = true;
+                if (stageIndex !== generation.stages.length - 1)
+                    throw new Error("Unfinished stage must be last.");
+            }
+        }
+        const complete = !unfinished && generation.stages.length === generation.order.length;
+        if (generation.correction && (!complete || !isCleanCommitted(generation.correction.from)
+            || !isCleanCommitted(generation.correction.to) || !sameIdentity(generation.correction.from, previous)
+            || generation.correction.to.head === previous.head || generation.correction.to.branch !== previous.branch)) {
+            throw new Error(`Generation ${generation.number} has an invalid correction intent.`);
+        }
+        if (generation.combinedTip && (!complete || !sameIdentity(generation.combinedTip, generation.correction?.to ?? previous))) {
+            throw new Error(`Generation ${generation.number} combined tip breaks staged lineage.`);
+        }
+        if (generation.checks) {
+            if (generation.checks.phase !== "final")
+                throw new Error("Combined checks must be final-phase evidence.");
+            validateCheckBatchEvidence(generation.checks, request.finalChecks, "Combined checks");
+        }
+        if (generation.review && (generation.review.phase !== "final" || !request.finalJudgment
+            || generation.review.criterion !== request.finalJudgment.criterion
+            || !generation.combinedTip || !sameIdentity(generation.review.base, generation.expectedMain)
+            || !sameIdentity(generation.review.tip, generation.combinedTip)
+            || generation.review.passed !== (generation.review.verdict === "PASS"
+                && sameIdentity(generation.review.identityAfter, generation.combinedTip)))) {
+            throw new Error(`Generation ${generation.number} has invalid combined review evidence.`);
+        }
+        if ((generation.checks || generation.review || generation.promotion) && !generation.combinedTip) {
+            throw new Error(`Generation ${generation.number} has evidence without a complete tip.`);
+        }
+        if (generation.checks && !sameIdentity(generation.checks.candidate, generation.combinedTip)) {
+            throw new Error(`Generation ${generation.number} checks target another tip.`);
+        }
+        const passes = integrationGenerationPasses(generation, request);
+        const promotion = generation.promotion;
+        if (promotion && (!passes || generation.failure !== undefined
+            || !sameIdentity(promotion.expectedMain, generation.expectedMain)
+            || !sameIdentity(promotion.tip, generation.combinedTip))) {
+            throw new Error(`Generation ${generation.number} promotion has stale evidence or lineage.`);
+        }
+        if (promotion && (promotion.outcome !== undefined && (promotion.status !== "failed" || promotion.outcome !== "drift")
+            || (promotion.status === "promoting"
+                ? promotion.mainAfter !== undefined || promotion.failure !== undefined
+                : promotion.status === "promoted"
+                    ? !promotion.mainAfter || promotion.failure !== undefined
+                        || promotion.mainAfter.branch !== promotion.expectedMain.branch
+                        || promotion.mainAfter.head !== promotion.tip.head || !isCleanCommitted(promotion.mainAfter)
+                    : promotion.mainAfter !== undefined || !promotion.failure?.trim()))) {
+            throw new Error(`Generation ${generation.number} has inconsistent promotion outcome.`);
+        }
+        const expectedStatus = promotion?.status === "unknown" ? "promotion_unknown"
+            : promotion?.status === "failed" ? "promotion_failed" : promotion?.status;
+        if (generation.supersededPromotion && (generation.status !== "superseded" || generation.supersededFrom !== "promotion_failed"
+            || generation.supersededPromotion.status !== "failed" || generation.supersededPromotion.outcome !== "drift"
+            || generation.supersededPromotion.mainAfter || !generation.supersededPromotion.failure?.trim()
+            || !sameIdentity(generation.supersededPromotion.expectedMain, generation.expectedMain)
+            || !sameIdentity(generation.supersededPromotion.tip, generation.correction?.to ?? previous))) {
+            throw new Error("Superseded promotion lacks proven exact drift evidence.");
+        }
+        if (generation.status === "superseded") {
+            if (!generation.supersededFrom || !generation.failure?.trim() || generation.promotion
+                || generation.checks || generation.review || generation.combinedTip
+                || (generation.supersededFrom === "promotion_failed" ? !generation.supersededPromotion : generation.correction || generation.supersededPromotion)) {
+                throw new Error(`Superseded generation ${generation.number} retains usable evidence or lacks its reason.`);
+            }
+        }
+        else if (generation.supersededFrom !== undefined || (promotion ? generation.status !== expectedStatus
+            : generation.status === "ready" ? !passes || generation.failure !== undefined
+                : generation.status === "validating" ? !complete || !generation.combinedTip || generation.failure !== undefined
+                    : generation.status === "validation_failed" ? !complete || !generation.combinedTip
+                        || passes || !generation.failure?.trim()
+                        : generation.status === "conflict" ? generation.stages.at(-1)?.status !== "conflict" || !generation.failure?.trim()
+                            : generation.status !== "staging" || generation.checks !== undefined
+                                || generation.review !== undefined || generation.failure !== undefined)) {
+            throw new Error(`Generation ${generation.number} has inconsistent status or invalidated evidence.`);
+        }
+        if (generation.cleanup && (!['promoted', 'superseded'].includes(generation.status)
+            || generation.cleanup[0]?.kind !== "worktree" || generation.cleanup[1]?.kind !== "branch")) {
+            throw new Error("Integration checkout cleanup requires promotion or explicit supersession.");
+        }
+        if (index === state.generations.length - 1 && generation.status !== "promoted"
+            && state.candidates.some((candidate) => candidate.worker !== "retained" && candidate.decision !== "rejected")) {
+            throw new Error(`Generation ${generation.number} released an unpromoted worker.`);
+        }
+    }
+    if (refresh?.status === "pending" && state.generations.at(-1)?.status !== "superseded" && state.generations.length) {
+        throw new Error("Pending refresh must freeze the old generation.");
+    }
+    const promoted = state.generations.at(-1)?.status === "promoted";
+    if (state.candidates.some((candidate) => candidate.worker !== "retained" && candidate.decision !== "rejected" && (!promoted
+        || !state.generations.at(-1).stages.some((stage) => stage.taskId === candidate.taskId && stage.attempt === candidate.attempt)))) {
+        throw new Error("Worker release requires exact promoted inclusion.");
+    }
+    return state;
+}
+/** Passing final evidence is bound to the exact assembled identity, not any worker tip. */
+export function integrationGenerationPasses(generation, request) {
+    return Boolean(generation.combinedTip && isCleanCommitted(generation.combinedTip)
+        && generation.stages.length === generation.order.length
+        && generation.stages.every((stage, index) => stage.status === "staged" && stage.taskId === generation.order[index])
+        && generation.checks?.phase === "final"
+        && checkBatchPasses(generation.checks, request.finalChecks, generation.combinedTip)
+        && (!request.finalJudgment || reviewEvidencePasses(generation.review, "final", request.finalJudgment.criterion, generation.expectedMain, generation.combinedTip)));
+}
+export function parseRunState(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)
+        && "version" in value && value.version !== RUN_STATE_VERSION) {
+        throw new Error(`Unsupported pi-subagent state version ${String(value.version)}; expected ${RUN_STATE_VERSION}.`);
+    }
+    if (!Check(RunStateSchema, value)) {
+        const first = Errors(RunStateSchema, value)[0];
+        const detail = first ? ` at ${first.instancePath || "/"}: ${first.message}` : "";
+        throw new Error(`Unsupported or malformed pi-subagent v${RUN_STATE_VERSION} state${detail}.`);
+    }
+    const state = value;
+    const request = parseExecuteRequest(state.request);
+    parseIntegrationState(state.integration, request);
+    const refresh = state.integration.refresh;
+    if (refresh && (refresh.generation === 1 && !sameIdentity(refresh.from, state.requestStartMain)
+        || (state.integration.generations.at(-1)?.status !== "promoted" && !sameIdentity(refresh.to, state.main)))) {
+        throw new Error("Refreshed Main identity breaks recorded lineage.");
+    }
+    for (const wave of state.waves) {
+        for (const id of wave.taskIds) {
+            const definition = request.tasks.find((task) => task.id === id);
+            if (!definition)
+                throw new Error(`Wave has an unknown task ${id}.`);
+            const changesetParents = new Set();
+            const visit = (task) => {
+                for (const source of [...task.dependsOn, ...task.contextFrom]) {
+                    const predecessor = request.tasks.find((item) => item.id === source);
+                    if (predecessor.kind === "changeset")
+                        changesetParents.add(source);
+                    else
+                        visit(predecessor);
+                }
+            };
+            visit(definition);
+            if (changesetParents.size && !state.integration.generations.some((generation) => generation.stages.some((stage) => stage.status === "staged" && stage.tip
+                && sameIdentity(stage.tip, wave.base) && [...changesetParents].every((source) => generation.stages.some((prior) => prior.taskId === source && prior.status === "staged"))))) {
+                throw new Error(`Wave for ${id} lacks an exact staged dependency snapshot.`);
+            }
+        }
+    }
+    if (state.createdAt > state.updatedAt || state.correctionCount > state.policy.maxCorrections) {
+        throw new Error(`Malformed pi-subagent v${RUN_STATE_VERSION} timestamps or correction policy.`);
+    }
+    const recordedCorrections = state.tasks.reduce((count, task) => count + (task.kind === "changeset"
+        ? task.attempts.reduce((sum, attempt) => sum + attempt.prompts.filter((prompt) => prompt.kind === "correction").length, 0)
+        : 0), 0);
+    if (recordedCorrections !== state.correctionCount)
+        throw new Error("Malformed pi-subagent correction count.");
+    if (state.tasks.length !== request.tasks.length)
+        throw new Error(`Malformed pi-subagent v${RUN_STATE_VERSION} task count.`);
+    for (let index = 0; index < request.tasks.length; index += 1) {
+        const definition = request.tasks[index];
+        const taskState = state.tasks[index];
+        if (taskState.taskId !== definition.id)
+            throw new Error(`Malformed pi-subagent v${RUN_STATE_VERSION} task order.`);
+        if (definition.kind === "text") {
+            if (taskState.kind !== "text")
+                throw new Error(`Malformed task kind for ${definition.id}.`);
+            validateTextTaskState(taskState);
+            continue;
+        }
+        if (taskState.kind !== "changeset")
+            throw new Error(`Malformed task kind for ${definition.id}.`);
+        if (taskState.status === "pending" && taskState.attempts.length && !taskState.attempts.at(-1)?.superseded) {
+            throw new Error(`Pending task ${definition.id} lacks superseded attempt evidence.`);
+        }
+        for (const [attemptIndex, attempt] of taskState.attempts.entries()) {
+            if (attempt.number !== attemptIndex + 1)
+                throw new Error(`Malformed attempt order for ${definition.id}.`);
+            if (attempt.preliminaryChecks) {
+                if (attempt.preliminaryChecks.phase !== "preliminary")
+                    throw new Error(`Malformed preliminary check phase for ${definition.id}.`);
+                validateCheckBatchEvidence(attempt.preliminaryChecks, definition.checks, `Preliminary checks for ${definition.id}`);
+            }
+            if ((attempt.candidate === undefined) !== (attempt.candidateBase === undefined)) {
+                throw new Error(`Candidate and candidate base for ${definition.id} must be recorded together.`);
+            }
+            if (attempt.candidate && (!isCleanCommitted(attempt.candidate) || !isCleanCommitted(attempt.candidateBase))) {
+                throw new Error(`Candidate lineage for ${definition.id} must be clean and committed.`);
+            }
+            if (attempt.preliminaryReview && (!definition.judgment || !attempt.candidate || !attempt.candidateBase
+                || attempt.preliminaryReview.phase !== "preliminary"
+                || attempt.preliminaryReview.criterion !== definition.judgment.criterion
+                || !sameIdentity(attempt.preliminaryReview.base, attempt.candidateBase)
+                || !sameIdentity(attempt.preliminaryReview.tip, attempt.candidate))) {
+                throw new Error(`Preliminary review for ${definition.id} targets another candidate.`);
+            }
+            if (attempt.readiness) {
+                if (!attempt.candidate || !attempt.candidateBase
+                    || !sameIdentity(attempt.readiness.candidate, attempt.candidate)
+                    || !sameIdentity(attempt.readiness.base, attempt.candidateBase)
+                    || !checkBatchPasses(attempt.preliminaryChecks, definition.checks, attempt.candidate)) {
+                    throw new Error(`Readiness for ${definition.id} does not match exact passing preliminary evidence.`);
+                }
+            }
+            if (attempt.termination) {
+                const termination = attempt.termination;
+                const ownedAgent = [...attempt.allocations].reverse().find((allocation) => allocation.kind === "agent");
+                if (!ownedAgent || ownedAgent.status !== "owned" || termination.workerId !== ownedAgent.agentName) {
+                    throw new Error(`Worker termination for ${definition.id} does not match the exact owned agent.`);
+                }
+                if (termination.status === "terminated" ? termination.at === undefined || termination.failure !== undefined
+                    : termination.status === "terminating" ? termination.at !== undefined || termination.failure !== undefined
+                        : termination.at !== undefined || !termination.failure?.trim()) {
+                    throw new Error(`Worker termination for ${definition.id} has inconsistent status evidence.`);
+                }
+            }
+            const initialPrompt = attempt.prompts[0];
+            if (attempt.prompts.filter((prompt) => prompt.kind === "correction").length > 1) {
+                throw new Error(`Malformed repeated correction history for ${definition.id}.`);
+            }
+            if (initialPrompt && initialPrompt.kind !== "initial") {
+                throw new Error(`Malformed initial prompt history for ${definition.id}.`);
+            }
+            if (attempt.prompts.some((prompt) => !isCleanCommitted(prompt.preCandidate))
+                || (initialPrompt && initialPrompt.preCandidate.head !== attempt.waveBase.head)) {
+                throw new Error(`Prompt history for ${definition.id} lacks a clean exact pre-prompt candidate.`);
+            }
+            for (let promptIndex = 0; promptIndex < attempt.prompts.length; promptIndex += 1) {
+                const prompt = attempt.prompts[promptIndex];
+                if ((prompt.kind === "followup") !== (prompt.instruction !== undefined)) {
+                    throw new Error(`Follow-up prompt history for ${definition.id} has invalid instruction evidence.`);
+                }
+                if (prompt.instruction !== undefined) {
+                    requireExactAllocationText(prompt.instruction, `Follow-up prompt instruction for ${definition.id}`);
+                }
+                if (promptIndex === 0)
+                    continue;
+                if (prompt.kind === "initial")
+                    throw new Error(`Malformed repeated initial prompt for ${definition.id}.`);
+                const previous = attempt.prompts[promptIndex - 1];
+                if (!sameIdentity(prompt.preCandidate, previous.candidate ?? previous.preCandidate)) {
+                    throw new Error(`Prompt ${promptIndex + 1} for ${definition.id} breaks exact candidate lineage.`);
+                }
+            }
+            if (attempt.cleanup.some((step, cleanupIndex) => step.kind !== CLEANUP_KINDS[cleanupIndex])) {
+                throw new Error(`Malformed cleanup sequence for ${definition.id}.`);
+            }
+            if (attempt.allocations.filter((allocation) => allocation.status === "unknown").length > 1) {
+                throw new Error(`Attempt for ${definition.id} has more than one ambiguous allocation result.`);
+            }
+            for (const allocation of attempt.allocations) {
+                if (allocation.token !== attempt.correlationToken) {
+                    throw new Error(`${allocation.kind} allocation for ${definition.id} has the wrong correlation token.`);
+                }
+                if (allocation.status === "unknown") {
+                    if (!allocation.failure?.trim())
+                        throw new Error(`Unknown ${allocation.kind} allocation for ${definition.id} lacks a failure.`);
+                    for (const resource of allocation.possibleResources ?? []) {
+                        requireExactAllocationText(resource, `Unknown ${allocation.kind} allocation possible resource`);
+                    }
+                }
+                else if (allocation.possibleResources) {
+                    throw new Error(`Only unknown allocations may record possible resources for ${definition.id}.`);
+                }
+                if (allocation.kind === "worktree") {
+                    if (allocation.status === "owned" && !hasWorktreePlan(allocation)) {
+                        throw new Error(`Owned worktree allocation for ${definition.id} lacks exact plan fields.`);
+                    }
+                    if (hasWorktreePlan(allocation)) {
+                        requireAbsoluteAllocationPath(allocation.worktree.path, `Worktree allocation path for ${definition.id}`);
+                        requireAbsoluteAllocationPath(allocation.worktree.cwd, `Worktree allocation cwd for ${definition.id}`);
+                        requireAbsoluteAllocationPath(allocation.worktree.repoRoot, `Worktree allocation repository root for ${definition.id}`);
+                        requireExactAllocationText(allocation.worktree.branch, `Worktree allocation branch for ${definition.id}`);
+                        if (allocation.worktree.path !== allocation.worktree.cwd)
+                            throw new Error(`Worktree path and cwd for ${definition.id} must match exactly.`);
+                        if (allocation.worktree.baseCommit !== attempt.waveBase.head) {
+                            throw new Error(`Worktree plan for ${definition.id} does not match its recorded wave base.`);
+                        }
+                    }
+                    continue;
+                }
+                const worktree = attempt.allocations.find((candidate) => candidate.kind === "worktree" && candidate.status === "owned" && hasWorktreePlan(candidate));
+                if (!worktree)
+                    throw new Error(`${allocation.kind} allocation for ${definition.id} lacks its exact owned worktree parent.`);
+                if (allocation.kind === "workspace") {
+                    for (const [field, value] of Object.entries({
+                        label: allocation.label, worktreeCwd: allocation.worktreeCwd, mainRoot: allocation.mainRoot,
+                        repoKey: allocation.repoKey, herdrRepoRoot: allocation.herdrRepoRoot,
+                    }))
+                        requireExactAllocationText(value, `Workspace allocation ${field} for ${definition.id}`);
+                    for (const [field, value] of Object.entries({
+                        worktreeCwd: allocation.worktreeCwd, mainRoot: allocation.mainRoot,
+                        repoKey: allocation.repoKey, herdrRepoRoot: allocation.herdrRepoRoot,
+                    }))
+                        requireAbsoluteAllocationPath(value, `Workspace allocation ${field} for ${definition.id}`);
+                    if (allocation.worktreeCwd !== worktree.worktree.cwd || allocation.mainRoot !== worktree.worktree.repoRoot) {
+                        throw new Error(`Workspace allocation for ${definition.id} drifted from its exact worktree parent.`);
+                    }
+                    const results = [allocation.workspaceId, allocation.rootTabId, allocation.rootPaneId];
+                    if (allocation.status === "owned" && results.some((value) => value === undefined)) {
+                        throw new Error(`Owned workspace allocation for ${definition.id} lacks exact result fields.`);
+                    }
+                    if (allocation.status !== "owned" && results.some((value) => value !== undefined)) {
+                        throw new Error(`Unowned workspace allocation for ${definition.id} must not claim result fields.`);
+                    }
+                    for (const value of results)
+                        if (value !== undefined)
+                            requireExactAllocationText(value, `Workspace allocation result for ${definition.id}`);
+                    continue;
+                }
+                const workspace = attempt.allocations.find((candidate) => candidate.kind === "workspace" && candidate.status === "owned");
+                if (!workspace?.workspaceId || !workspace.rootTabId || !workspace.rootPaneId) {
+                    throw new Error(`${allocation.kind} allocation for ${definition.id} lacks its exact owned workspace parent.`);
+                }
+                if (allocation.kind === "worker_tab") {
+                    for (const [field, value] of Object.entries({
+                        label: allocation.label, workspaceId: allocation.workspaceId,
+                        workspaceRootTabId: allocation.workspaceRootTabId, workspaceRootPaneId: allocation.workspaceRootPaneId,
+                        worktreeCwd: allocation.worktreeCwd, leasePath: allocation.leasePath,
+                    }))
+                        requireExactAllocationText(value, `Worker-tab allocation ${field} for ${definition.id}`);
+                    if (allocation.workspaceId !== workspace.workspaceId
+                        || allocation.workspaceRootTabId !== workspace.rootTabId
+                        || allocation.workspaceRootPaneId !== workspace.rootPaneId
+                        || allocation.worktreeCwd !== worktree.worktree.cwd) {
+                        throw new Error(`Worker-tab allocation for ${definition.id} drifted from its exact parents.`);
+                    }
+                    const results = [allocation.tabId, allocation.paneId];
+                    if (allocation.status === "owned" && results.some((value) => value === undefined)) {
+                        throw new Error(`Owned worker-tab allocation for ${definition.id} lacks exact result fields.`);
+                    }
+                    if (allocation.status !== "owned" && results.some((value) => value !== undefined)) {
+                        throw new Error(`Unowned worker-tab allocation for ${definition.id} must not claim result fields.`);
+                    }
+                    for (const value of results)
+                        if (value !== undefined)
+                            requireExactAllocationText(value, `Worker-tab allocation result for ${definition.id}`);
+                    continue;
+                }
+                const workerTab = attempt.allocations.find((candidate) => candidate.kind === "worker_tab" && candidate.status === "owned");
+                if (!workerTab?.tabId || !workerTab.paneId)
+                    throw new Error(`Agent allocation for ${definition.id} lacks its exact owned worker-tab parent.`);
+                for (const [field, value] of Object.entries({
+                    agentName: allocation.agentName, workspaceId: allocation.workspaceId, tabId: allocation.tabId,
+                    paneId: allocation.paneId, worktreeCwd: allocation.worktreeCwd, leasePath: allocation.leasePath,
+                }))
+                    requireExactAllocationText(value, `Agent allocation ${field} for ${definition.id}`);
+                if (allocation.workspaceId !== workspace.workspaceId
+                    || allocation.tabId !== workerTab.tabId
+                    || allocation.paneId !== workerTab.paneId
+                    || allocation.worktreeCwd !== worktree.worktree.cwd
+                    || allocation.leasePath !== workerTab.leasePath) {
+                    throw new Error(`Agent allocation for ${definition.id} drifted from its exact parents.`);
+                }
+            }
+        }
+        if (taskState.status === "rejected" && (!taskState.attempts.length
+            || !state.integration.candidates.some((candidate) => candidate.taskId === definition.id
+                && candidate.decision === "rejected" && candidate.attempt === taskState.attempts.length)
+            || taskState.attempts.at(-1)?.termination?.status !== "terminated")) {
+            throw new Error(`Rejected task ${definition.id} lacks explicit decision and proven worker termination.`);
+        }
+        if (taskState.status === "completed") {
+            const promoted = state.integration.generations.at(-1);
+            const candidate = state.integration.candidates.find((item) => item.taskId === definition.id
+                && promoted?.stages.some((stage) => stage.taskId === definition.id && stage.attempt === item.attempt
+                    && sameIdentity(stage.source, item.tip)));
+            if (candidate && promoted?.status === "promoted") {
+                const attempt = taskState.attempts.at(-1);
+                if (candidate.worker === "released" && (attempt.termination?.status !== "terminated"
+                    || attempt.cleanup.some((step) => step.status !== "completed"))) {
+                    throw new Error(`Promoted task ${definition.id} claims unproved worker cleanup.`);
+                }
+            }
+            else
+                throw new Error(`Completed task ${definition.id} lacks a promoted Main-owned integration generation.`);
+        }
+    }
+    if (state.final.checks) {
+        if (state.final.checks.phase !== "final")
+            throw new Error("Malformed final check phase.");
+        validateCheckBatchEvidence(state.final.checks, request.finalChecks, "Final checks");
+    }
+    if (state.recovery) {
+        if (state.recovery.action === "finalize" ? state.recovery.taskId !== undefined : !state.recovery.taskId
+            || !state.tasks.some((task) => task.taskId === state.recovery.taskId)) {
+            throw new Error("Malformed resume recovery target.");
+        }
+    }
+    if (state.integration.candidates.length && state.integration.generations.at(-1)?.status !== "promoted"
+        && (state.accepted || state.status === "completed")) {
+        throw new Error("Unpromoted integration cannot complete a request.");
+    }
+    for (const candidate of state.integration.candidates) {
+        const task = state.tasks.find((item) => item.taskId === candidate.taskId);
+        const attempt = task?.kind === "changeset" ? task.attempts[candidate.attempt - 1] : undefined;
+        if (candidate.decision === "rejected") {
+            const selected = state.integration.generations.at(-1);
+            const releasedWithRevisedAttempt = selected?.status === "promoted" && selected.stages.some((stage) => stage.taskId === candidate.taskId && stage.attempt === candidate.attempt && !sameIdentity(stage.source, candidate.tip))
+                && attempt?.cleanup.every((step) => step.status === "completed");
+            const releasedAfterRejection = task?.status === "rejected" && attempt?.termination?.status === "terminated"
+                && (candidate.worker === "release_pending" || candidate.worker === "released"
+                    && attempt.cleanup.every((step) => step.status === "completed"));
+            if (!attempt || (candidate.worker !== "retained" && !releasedAfterRejection
+                && !(candidate.worker === "released" && releasedWithRevisedAttempt))) {
+                throw new Error(`Rejected candidate ${candidate.taskId} lost its exact worker accounting.`);
+            }
+            continue;
+        }
+        if (!attempt?.readiness || !sameIdentity(attempt.readiness.base, candidate.base)
+            || !sameIdentity(attempt.readiness.candidate, candidate.tip)
+            || (candidate.review !== undefined && JSON.stringify(candidate.review) !== JSON.stringify(attempt.preliminaryReview))
+            || (state.integration.generations.at(-1)?.status !== "promoted"
+                ? attempt.termination || task?.status !== "ready_to_integrate" || candidate.worker !== "retained"
+                : task?.status !== "ready_to_integrate" && task?.status !== "completed")) {
+            throw new Error(`Ready candidate ${candidate.taskId} is not the retained exact worker attempt.`);
+        }
+    }
+    if (state.status === "completed" && !state.accepted) {
+        throw new Error("A completed request must be accepted with exact final evidence.");
+    }
+    if (state.final.status === "passed" && !state.accepted) {
+        throw new Error("A passed final gate must belong to an accepted request.");
+    }
+    if (state.accepted) {
+        if (state.status !== "completed" || state.final.status !== "passed" || state.tasks.some((task) => task.status !== "completed" && task.status !== "rejected")) {
+            throw new Error(`Malformed accepted pi-subagent v${RUN_STATE_VERSION} state.`);
+        }
+        if (!state.final.identity || !isCleanCommitted(state.final.identity)) {
+            throw new Error("Accepted request lacks a clean final identity.");
+        }
+        const generation = state.integration.generations.at(-1);
+        const acceptedChecks = generation?.status === "promoted"
+            ? Boolean(generation.combinedTip && generation.combinedTip.head === state.final.identity.head
+                && generation.combinedTip.tree === state.final.identity.tree
+                && generation.promotion?.mainAfter && sameIdentity(generation.promotion.mainAfter, state.final.identity)
+                && JSON.stringify(generation.checks) === JSON.stringify(state.final.checks)
+                && integrationGenerationPasses(generation, request))
+            : checkBatchPasses(state.final.checks, request.finalChecks, state.final.identity);
+        if (!acceptedChecks)
+            throw new Error("Accepted request lacks passing final checks on its exact identity.");
+        if (request.finalJudgment && !(generation?.status === "promoted"
+            ? JSON.stringify(generation.review) === JSON.stringify(state.final.review)
+            : reviewEvidencePasses(state.final.review, "final", request.finalJudgment.criterion, state.requestStartMain, state.final.identity)))
+            throw new Error("Accepted request lacks an exact passing final review.");
+        if (state.integration.generations.length && state.integration.generations.at(-1)?.status !== "promoted") {
+            throw new Error("Accepted integration requires proven promotion.");
+        }
+        if (generation && (generation.stages.some((stage) => state.tasks.find((task) => task.taskId === stage.taskId)?.status !== "completed")
+            || state.integration.candidates.some((candidate) => !candidate.decision
+                && !generation.stages.some((stage) => stage.taskId === candidate.taskId && stage.attempt === candidate.attempt
+                    && sameIdentity(stage.source, candidate.tip))))) {
+            throw new Error("Accepted integration has an unselected candidate or uncompleted selected task.");
+        }
+        if (!sameIdentity(state.main, state.final.identity) || state.acceptedAt === undefined) {
+            throw new Error("Accepted request does not match its final-gate identity.");
+        }
+    }
+    else if (state.acceptedAt !== undefined) {
+        throw new Error("Unaccepted request cannot have acceptedAt.");
+    }
+    if (state.status === "final_failed" && state.final.status !== "final_failed")
+        throw new Error("Malformed final_failed state.");
+    if (state.status === "superseded" && state.final.status !== "superseded")
+        throw new Error("Malformed superseded state.");
+    return { ...state, request };
+}