codex-workflow-v2 2.0.0-beta.12.5 → 2.0.0-beta.12.7

package/README.md

@@ -24,6 +24,10 @@ automation do not import anything from the parent V1 project.
 - read-only update preflight for clean checkout, running-Step, and writer-lease blockers;
 - beta.10 bounded recovery for one exact dependency-only HEAD, including retained product commits
   proven by intact passed strict-review and reviewer-attestation chains;
+- beta.12.6 active-downstream-proof update bridge: one exact dependency-only Task HEAD can be
+  registered while the already-classified proof work remains dirty and its Step remains active;
+- beta.12.7 stranded-replan recovery: an accidental post-recovery Knowledge rebind cannot resurrect
+  the rejected Plan, and exact dirty bytes can be adopted by one newly authorized owning Step;
 - bounded first-failure Plan-integrity recovery for legacy/in-flight contradictions that could not
   be rejected by the current pre-authorization feasibility gate;
 - read-only Milestone progress projection with stable membership ordinals and replacement links;
@@ -43,7 +47,7 @@ cross-machine synchronization are not part of its contract.
 Node.js 22 or newer is required. Consumers pin the exact package version:
 
 ```bash
-npm install --save-dev --save-exact codex-workflow-v2@2.0.0-beta.12.5
+npm install --save-dev --save-exact codex-workflow-v2@2.0.0-beta.12.7
 npx codex-workflow gateway handshake --repo .
 npx codex-workflow doctor --repo .
 ```
@@ -222,6 +226,27 @@ C1, and returns the same Task to ordinary planning. A fresh replacement Plan, Pl
 execution authorization are required. Unrelated dirty files, non-predecessor ownership, unregistered
 history, or damaged invalidation evidence fail closed.
 
+If that exact condition is already present on an older package and therefore blocks the ordinary
+clean-checkout update, beta.12.6 provides a bounded compatibility bridge. Update the active
+Milestone base and Task branch with separate commits that each change only `package.json` and
+`package-lock.json`, install the exact package, and continue only when fresh `next` advertises
+`update downstream-proof-dependency-recover`. Its read-only preflight validates the candidate at
+`HEAD`, the previously recorded Task history at `HEAD^`, aligned runtime/declared/locked/installed/
+base versions, absence of leases and transactions, the exact active Step, predecessor ownership,
+and a SHA-256 binding of every dirty product file. Recovery registers only that dependency commit,
+does not touch product bytes or end the Step, and makes the existing `task downstream-proof-recover`
+route reachable. Unknown history, an unrelated dirty path, a non-dependency candidate, stale base,
+or changed authority remains a hard stop.
+
+If beta.12.6 already invalidated the predecessor but a later Project Knowledge approval rebound the
+rejected Plan, beta.12.7 exposes a separate exact compatibility route. Run the new package's read-only
+`update downstream-proof-replan-update-preflight` before changing dependencies. After the two
+dependency-only commits, follow fresh `next` through replan dependency registration and
+`task downstream-proof-replan-recover`. Knowledge refresh may follow, but it cannot replace the
+required `task plan-set`. Preserved dirty bytes are executable only when one replacement Step owns the
+entire path set and `next` reports `downstreamProofCarryover.state=validated`; normal checks, Core commit,
+and strict review remain mandatory.
+
 Docker socket `EPERM`/permission errors observed inside a sandbox are access-boundary evidence, not
 daemon-failure evidence. The gateway repeats the exact read-only probe or Plan check once with
 sandbox escalation without consuming a remediation/infra retry. Docker Desktop restart or image
@@ -315,11 +340,12 @@ alpha regressions that must not recur are tracked in the
 - [Chat-only development guide](docs/pdf/codex-workflow-v2-chat-only-guide-ru.pdf)
 - [Deep technical reference](docs/pdf/codex-workflow-v2-technical-reference-ru.pdf)
 
-These beta.12.5 documents cover delegated Discovery, Milestone Autonomy Contract issuance,
+These beta.12.7 documents cover delegated Discovery, Milestone Autonomy Contract issuance,
 dependency-aware Task routing, C1 credential handling, external-sealed reviews, bounded
 Plan-integrity recovery, Task-local dependency provenance recovery, the human-confirmed legacy
 attempt-four stop override (including append-only multi-rebind, dependency-only HEAD continuation,
-and evidence-accounted post-audit recovery revisions), and the P04-A
+evidence-accounted post-audit recovery revisions), both downstream-proof update bridges, exact
+dirty-worktree carryover into a replacement Step, and the P04-A
 structural-replacement stop boundary. Their reviewable
 sources live in [`docs/pdf/sources`](docs/pdf/sources), and `npm run docs:pdf:check` proves the
 tracked binaries were generated from the current source and package version. The PDFs remain

package/dist/src/alpha6/downstream-proof.d.ts

@@ -1,4 +1,4 @@
-import type { DownstreamProofInvalidationEvent, TaskState } from '../contracts.js';
+import type { DownstreamProofInvalidationEvent, DownstreamProofReplanCompatibility, DownstreamProofReplanRecoveryEvent, TaskState } from '../contracts.js';
 import type { FileStateStore } from '../state/store.js';
 export interface DownstreamProofInvalidatedStep {
     stepId: string;
@@ -13,13 +13,38 @@ export interface DownstreamProofRecoveryAssessment {
     outsideActiveStepFiles: string[];
     invalidatedSteps: DownstreamProofInvalidatedStep[];
     preservedHeadCommit: string | null;
+    dirtyWorktreeHash: string | null;
     blockers: string[];
 }
 export interface PreparedDownstreamProofInvalidation {
     event: DownstreamProofInvalidationEvent;
     postimage: string;
 }
-export declare function assessDownstreamProofRecovery(store: FileStateStore, repositoryRoot: string, task: TaskState): DownstreamProofRecoveryAssessment;
+export interface DownstreamProofReplanRecoveryAssessment {
+    applicable: boolean;
+    eligible: boolean;
+    invalidation: DownstreamProofInvalidationEvent | null;
+    rebind: TaskState['knowledgeRebinds'][number] | null;
+    compatibility: DownstreamProofReplanCompatibility | null;
+    dependencyRecoveryCommit: string | null;
+    blockers: string[];
+}
+export interface PreparedDownstreamProofReplanRecovery {
+    event: DownstreamProofReplanRecoveryEvent;
+    postimage: string;
+}
+export interface DownstreamProofCarryoverAssessment {
+    applicable: boolean;
+    eligible: boolean;
+    dirtyFiles: string[];
+    dirtyWorktreeHash: string | null;
+    invalidationEventId: string | null;
+    blockers: string[];
+}
+export declare function assessDownstreamProofRecovery(store: FileStateStore, repositoryRoot: string, task: TaskState, options?: {
+    historyBoundary?: string;
+    preservedHeadCommit?: string;
+}): DownstreamProofRecoveryAssessment;
 export declare function prepareDownstreamProofInvalidation(store: FileStateStore, resultTask: TaskState, assessment: DownstreamProofRecoveryAssessment, input: {
     previousTaskRevision: number;
     actor: string;
@@ -27,3 +52,17 @@ export declare function prepareDownstreamProofInvalidation(store: FileStateStore
 }, now: Date): PreparedDownstreamProofInvalidation;
 export declare function readDownstreamProofInvalidations(store: FileStateStore, task: TaskState): DownstreamProofInvalidationEvent[];
 export declare function downstreamProofInvalidationSidecar(): string;
+export declare function assessDownstreamProofReplanRecovery(store: FileStateStore, repositoryRoot: string, task: TaskState, options?: {
+    historyBoundary?: string;
+    preservedHeadCommit?: string;
+    currentPlanRiskAuditExists?: boolean;
+}): DownstreamProofReplanRecoveryAssessment;
+export declare function prepareDownstreamProofReplanRecovery(store: FileStateStore, resultTask: TaskState, assessment: DownstreamProofReplanRecoveryAssessment, input: {
+    previousTaskRevision: number;
+    actor: string;
+    reason: string;
+}, now: Date): PreparedDownstreamProofReplanRecovery;
+export declare function readDownstreamProofReplanRecoveries(store: FileStateStore, task: TaskState): DownstreamProofReplanRecoveryEvent[];
+export declare function downstreamProofReplanRecoverySidecar(): string;
+export declare function assessDownstreamProofCarryover(store: FileStateStore, repositoryRoot: string, task: TaskState, stepId: string): DownstreamProofCarryoverAssessment;
+export declare function hashDirtyWorktree(repositoryRoot: string, dirtyFiles: readonly string[]): string;

package/dist/src/alpha6/downstream-proof.js

@@ -1,3 +1,6 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import path from 'node:path';
 import { WorkflowError } from '../errors.js';
 import { pathAllowed } from '../domain/validation.js';
 import { changedFiles, currentBranch, headCommit, } from '../repository.js';
@@ -6,21 +9,37 @@ import { createUlid } from '../ulid.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { prepareSidecarAppend } from './store-sidecars.js';
 const SIDECAR = 'downstream-proof-invalidations.jsonl';
+const REPLAN_RECOVERY_SIDECAR = 'downstream-proof-replan-recoveries.jsonl';
 const HASH_64 = /^[a-f0-9]{64}$/;
 const GIT_HASH = /^[a-f0-9]{40}$/;
 const EVENT_ID = /^DPI-[0-9A-HJKMNP-TV-Z]{26}$/;
-export function assessDownstreamProofRecovery(store, repositoryRoot, task) {
+const REPLAN_EVENT_ID = /^DPR-[0-9A-HJKMNP-TV-Z]{26}$/;
+export function assessDownstreamProofRecovery(store, repositoryRoot, task, options = {}) {
     readDownstreamProofInvalidations(store, task);
     const activeStep = task.steps.find((step) => step.status === 'in_progress') ?? null;
     if (task.status !== 'in_progress' || !activeStep)
         return emptyAssessment();
     const dirtyFiles = changedFiles(repositoryRoot).sort();
+    let dirtyWorktreeHash = null;
+    try {
+        dirtyWorktreeHash = hashDirtyWorktree(repositoryRoot, dirtyFiles);
+    }
+    catch (error) {
+        return {
+            ...emptyAssessment(),
+            applicable: true,
+            activeStepId: activeStep.id,
+            dirtyFiles,
+            blockers: [error instanceof Error ? error.message : String(error)],
+        };
+    }
     const outsideActiveStepFiles = dirtyFiles.filter((file) => !pathAllowed(file, activeStep.allowedWrites));
     if (outsideActiveStepFiles.length === 0) {
         return {
             ...emptyAssessment(),
             activeStepId: activeStep.id,
             dirtyFiles,
+            dirtyWorktreeHash,
         };
     }
     const blockers = [];
@@ -64,7 +83,7 @@ export function assessDownstreamProofRecovery(store, repositoryRoot, task) {
     if (invalidatedSteps.length === 0)
         blockers.push('No completed predecessor completion authority can be invalidated.');
     try {
-        validateTaskHistory(repositoryRoot, task);
+        validateTaskHistory(repositoryRoot, task, options.historyBoundary);
     }
     catch (error) {
         blockers.push(error instanceof Error ? error.message : String(error));
@@ -76,7 +95,8 @@ export function assessDownstreamProofRecovery(store, repositoryRoot, task) {
         dirtyFiles,
         outsideActiveStepFiles,
         invalidatedSteps,
-        preservedHeadCommit: headCommit(repositoryRoot),
+        preservedHeadCommit: options.preservedHeadCommit ?? headCommit(repositoryRoot),
+        dirtyWorktreeHash,
         blockers,
     };
 }
@@ -108,6 +128,7 @@ export function prepareDownstreamProofInvalidation(store, resultTask, assessment
             triggerFiles: [...step.triggerFiles],
         })),
         dirtyFiles: [...assessment.dirtyFiles],
+        dirtyWorktreeHash: assessment.dirtyWorktreeHash,
         preservedHeadCommit: assessment.preservedHeadCommit,
         actor,
         reason,
@@ -123,6 +144,254 @@ export function readDownstreamProofInvalidations(store, task) {
 export function downstreamProofInvalidationSidecar() {
     return SIDECAR;
 }
+export function assessDownstreamProofReplanRecovery(store, repositoryRoot, task, options = {}) {
+    const invalidations = readDownstreamProofInvalidations(store, task);
+    const recoveries = readDownstreamProofReplanRecoveries(store, task);
+    const invalidation = invalidations.at(-1) ?? null;
+    const rebind = task.knowledgeRebinds.at(-1) ?? null;
+    if (invalidation && recoveries.some((event) => event.invalidationEventId === invalidation.eventId
+        && event.resultTaskRevision <= task.revision)) {
+        return emptyReplanAssessment();
+    }
+    if (!invalidation || !rebind
+        || rebind.previousPlanHash !== invalidation.planHash
+        || rebind.reboundPlanHash !== task.planHash
+        || Date.parse(rebind.recordedAt) <= Date.parse(invalidation.recordedAt)) {
+        return emptyReplanAssessment();
+    }
+    const blockers = [];
+    const dirtyFiles = changedFiles(repositoryRoot).sort();
+    let dirtyWorktreeHash = null;
+    try {
+        dirtyWorktreeHash = hashDirtyWorktree(repositoryRoot, dirtyFiles);
+    }
+    catch (error) {
+        blockers.push(error instanceof Error ? error.message : String(error));
+    }
+    const sourceBinding = [...(task.dependencyProvenanceRecoveries ?? [])]
+        .reverse()
+        .map((record) => record.activeDownstreamProof)
+        .find((binding) => binding
+        && binding.planHash === invalidation.planHash
+        && binding.activeStepId === invalidation.activeStepId
+        && JSON.stringify([...binding.dirtyFiles].sort()) === JSON.stringify(invalidation.dirtyFiles)
+        && JSON.stringify([...binding.invalidatedStepIds].sort())
+            === JSON.stringify(invalidation.invalidatedSteps.map((step) => step.stepId).sort()))
+        ?? null;
+    if (!sourceBinding) {
+        blockers.push('No dependency provenance record preserves the exact active downstream-proof dirty-set binding.');
+    }
+    else if (dirtyWorktreeHash !== sourceBinding.dirtyWorktreeHash) {
+        blockers.push('Dirty file content changed after the downstream-proof invalidation boundary.');
+    }
+    if (JSON.stringify(dirtyFiles) !== JSON.stringify(invalidation.dirtyFiles)) {
+        blockers.push('Dirty files changed after the downstream-proof invalidation boundary.');
+    }
+    const registeredCompatibility = [...(task.dependencyProvenanceRecoveries ?? [])]
+        .reverse()
+        .find((record) => record.downstreamProofReplan?.invalidationEventId === invalidation.eventId
+        && record.downstreamProofReplan.reboundPlanHash === task.planHash) ?? null;
+    const sourceHead = options.preservedHeadCommit
+        ?? registeredCompatibility?.parentCommitSha
+        ?? headCommit(repositoryRoot);
+    if (sourceHead !== invalidation.preservedHeadCommit) {
+        blockers.push('The recovery history boundary no longer matches the downstream-proof preserved HEAD.');
+    }
+    if (task.workspaceOwner !== 'local')
+        blockers.push('Recovery requires the recorded local Task workspace.');
+    if (!task.taskBranch || currentBranch(repositoryRoot) !== task.taskBranch) {
+        blockers.push('Current branch must equal the recorded Task branch.');
+    }
+    if (task.status !== 'awaiting_execution_authorization') {
+        blockers.push('The legacy stranded Task must still be awaiting execution authorization.');
+    }
+    if (!task.planHash || task.planHash !== rebind.reboundPlanHash) {
+        blockers.push('The current Plan must be the exact mechanically rebound legacy Plan.');
+    }
+    if (task.knowledgeMapRevision !== rebind.toKnowledgeMapRevision
+        || task.knowledgeMapHash !== rebind.toKnowledgeMapHash) {
+        blockers.push('The current Project Knowledge binding must match the legacy rebind record.');
+    }
+    for (const invalidated of invalidation.invalidatedSteps) {
+        const step = task.steps.find((candidate) => candidate.id === invalidated.stepId);
+        if (!step || step.status !== 'planned' || step.evidence !== null
+            || !(task.invalidatedStepCommits ?? []).includes(invalidated.evidenceCommit)) {
+            blockers.push(`Invalidated predecessor ${invalidated.stepId} no longer has the preserved planned/no-evidence posture.`);
+        }
+    }
+    const activeStep = task.steps.find((step) => step.id === invalidation.activeStepId);
+    if (!activeStep || activeStep.status !== 'blocked' || activeStep.evidence !== null) {
+        blockers.push(`Former proof Step ${invalidation.activeStepId} no longer has the preserved blocked/no-evidence posture.`);
+    }
+    if (task.authorizations.some((authorization) => authorization.kind === 'execution'
+        && authorization.decision === 'approved'
+        && authorization.planHash === task.planHash)) {
+        blockers.push('The rebound Plan has already received execution authorization.');
+    }
+    if (options.currentPlanRiskAuditExists) {
+        blockers.push('The rebound Plan already has a recorded current Plan Risk Audit.');
+    }
+    const expectedRevision = invalidation.resultTaskRevision + (registeredCompatibility ? 2 : 1);
+    if (task.revision !== expectedRevision) {
+        blockers.push('Task revision contains changes beyond the exact invalidation, accidental rebind, and optional dependency registration sequence.');
+    }
+    if (registeredCompatibility) {
+        if (registeredCompatibility.commitSha !== headCommit(repositoryRoot)
+            || registeredCompatibility.downstreamProofReplan?.dirtyWorktreeHash !== dirtyWorktreeHash) {
+            blockers.push('The registered dependency compatibility record does not bind the current HEAD and dirty worktree.');
+        }
+    }
+    else if (!options.historyBoundary && headCommit(repositoryRoot) !== invalidation.preservedHeadCommit) {
+        blockers.push('Unregistered Git history exists after the downstream-proof invalidation boundary.');
+    }
+    try {
+        validateTaskHistory(repositoryRoot, task, options.historyBoundary);
+    }
+    catch (error) {
+        blockers.push(error instanceof Error ? error.message : String(error));
+    }
+    const compatibility = sourceBinding && dirtyWorktreeHash
+        ? {
+            invalidationEventId: invalidation.eventId,
+            activeStepId: invalidation.activeStepId,
+            sourcePlanHash: invalidation.planHash,
+            reboundPlanHash: rebind.reboundPlanHash,
+            knowledgeRebindRecordedAt: rebind.recordedAt,
+            dirtyFiles: [...invalidation.dirtyFiles],
+            dirtyWorktreeHash,
+            invalidatedStepIds: invalidation.invalidatedSteps.map((step) => step.stepId).sort(),
+        }
+        : null;
+    return {
+        applicable: true,
+        eligible: blockers.length === 0 && compatibility !== null,
+        invalidation,
+        rebind,
+        compatibility,
+        dependencyRecoveryCommit: registeredCompatibility?.commitSha ?? null,
+        blockers,
+    };
+}
+export function prepareDownstreamProofReplanRecovery(store, resultTask, assessment, input, now) {
+    if (!assessment.eligible || !assessment.invalidation || !assessment.rebind || !assessment.compatibility) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Downstream-proof replan compatibility assessment is not eligible.');
+    }
+    const actor = normalizeRequired(input.actor, 'Recovery actor');
+    const reason = normalizeRequired(input.reason, 'Recovery reason');
+    const events = readDownstreamProofReplanRecoveries(store, resultTask);
+    const prepared = prepareSidecarAppend(events, {
+        eventId: `DPR-${createUlid(now.getTime())}`,
+        recordedAt: now.toISOString(),
+        taskId: resultTask.id,
+        previousTaskRevision: input.previousTaskRevision,
+        resultTaskRevision: resultTask.revision,
+        invalidationEventId: assessment.invalidation.eventId,
+        invalidationPlanHash: assessment.invalidation.planHash,
+        reboundPlanHash: assessment.rebind.reboundPlanHash,
+        knowledgeRebindRecordedAt: assessment.rebind.recordedAt,
+        dirtyFiles: [...assessment.compatibility.dirtyFiles],
+        dirtyWorktreeHash: assessment.compatibility.dirtyWorktreeHash,
+        preservedHeadCommit: headCommit(resultTask.repositoryRoot),
+        dependencyRecoveryCommit: assessment.dependencyRecoveryCommit,
+        actor,
+        reason,
+        packageVersion: PACKAGE_VERSION,
+    }, {
+        validateEvent: (event) => validateReplanRecoveryEvent(event, resultTask),
+    });
+    return { event: prepared.event, postimage: prepared.content };
+}
+export function readDownstreamProofReplanRecoveries(store, task) {
+    return store.readSidecarEvents(store.taskRoot(task.projectId, task.id), REPLAN_RECOVERY_SIDECAR, { validateEvent: (event) => validateReplanRecoveryEvent(event, task) });
+}
+export function downstreamProofReplanRecoverySidecar() {
+    return REPLAN_RECOVERY_SIDECAR;
+}
+export function assessDownstreamProofCarryover(store, repositoryRoot, task, stepId) {
+    const invalidation = readDownstreamProofInvalidations(store, task).at(-1) ?? null;
+    if (!invalidation || !task.planHash || task.planHash === invalidation.planHash) {
+        return {
+            applicable: false,
+            eligible: false,
+            dirtyFiles: [],
+            dirtyWorktreeHash: null,
+            invalidationEventId: null,
+            blockers: [],
+        };
+    }
+    const recovery = [...readDownstreamProofReplanRecoveries(store, task)]
+        .reverse()
+        .find((event) => event.invalidationEventId === invalidation.eventId) ?? null;
+    const sourceBinding = [...(task.dependencyProvenanceRecoveries ?? [])]
+        .reverse()
+        .map((record) => record.activeDownstreamProof)
+        .find((binding) => binding?.planHash === invalidation.planHash
+        && JSON.stringify([...binding.dirtyFiles].sort()) === JSON.stringify(invalidation.dirtyFiles)) ?? null;
+    const expectedDirtyHash = recovery?.dirtyWorktreeHash
+        ?? invalidation.dirtyWorktreeHash
+        ?? sourceBinding?.dirtyWorktreeHash
+        ?? null;
+    const expectedHead = recovery?.preservedHeadCommit ?? invalidation.preservedHeadCommit;
+    const dirtyFiles = changedFiles(repositoryRoot).sort();
+    let dirtyWorktreeHash = null;
+    const blockers = [];
+    try {
+        dirtyWorktreeHash = hashDirtyWorktree(repositoryRoot, dirtyFiles);
+    }
+    catch (error) {
+        blockers.push(error instanceof Error ? error.message : String(error));
+    }
+    const step = task.steps.find((candidate) => candidate.id === stepId) ?? null;
+    if (!step || step.status !== 'planned' || step.evidence !== null) {
+        blockers.push('The replacement carryover Step must be planned and have no completion evidence.');
+    }
+    if (task.steps.some((candidate) => candidate.status === 'in_progress' || candidate.evidence !== null)) {
+        blockers.push('No replacement Plan Step may already be running or completed.');
+    }
+    if (JSON.stringify(dirtyFiles) !== JSON.stringify(invalidation.dirtyFiles)) {
+        blockers.push('Dirty files changed after downstream-proof recovery.');
+    }
+    if (!expectedDirtyHash) {
+        blockers.push('No hash-bound downstream-proof dirty-worktree evidence is available.');
+    }
+    else if (dirtyWorktreeHash !== expectedDirtyHash) {
+        blockers.push('Dirty file content changed after downstream-proof recovery.');
+    }
+    if (step && dirtyFiles.some((file) => !pathAllowed(file, step.allowedWrites))) {
+        blockers.push('The replacement Step does not own the complete preserved dirty set.');
+    }
+    if (headCommit(repositoryRoot) !== expectedHead) {
+        blockers.push('Git HEAD changed after downstream-proof recovery.');
+    }
+    if (task.workspaceOwner !== 'local' || !task.taskBranch || currentBranch(repositoryRoot) !== task.taskBranch) {
+        blockers.push('Carryover execution requires the unchanged recorded local Task branch.');
+    }
+    try {
+        validateTaskHistory(repositoryRoot, task);
+    }
+    catch (error) {
+        blockers.push(error instanceof Error ? error.message : String(error));
+    }
+    return {
+        applicable: true,
+        eligible: blockers.length === 0,
+        dirtyFiles,
+        dirtyWorktreeHash,
+        invalidationEventId: invalidation.eventId,
+        blockers,
+    };
+}
+function emptyReplanAssessment() {
+    return {
+        applicable: false,
+        eligible: false,
+        invalidation: null,
+        rebind: null,
+        compatibility: null,
+        dependencyRecoveryCommit: null,
+        blockers: [],
+    };
+}
 function emptyAssessment() {
     return {
         applicable: false,
@@ -132,9 +401,38 @@ function emptyAssessment() {
         outsideActiveStepFiles: [],
         invalidatedSteps: [],
         preservedHeadCommit: null,
+        dirtyWorktreeHash: null,
         blockers: [],
     };
 }
+export function hashDirtyWorktree(repositoryRoot, dirtyFiles) {
+    const hash = createHash('sha256');
+    for (const file of [...dirtyFiles].sort()) {
+        const absolute = path.resolve(repositoryRoot, file);
+        const relative = path.relative(repositoryRoot, absolute);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', `Dirty path escapes the repository boundary: ${file}`);
+        }
+        hash.update(`path\0${file}\0`);
+        if (!existsSync(absolute)) {
+            hash.update('deleted\0');
+            continue;
+        }
+        const stat = lstatSync(absolute);
+        if (stat.isSymbolicLink()) {
+            hash.update(`symlink\0${readlinkSync(absolute)}\0`);
+        }
+        else if (stat.isFile()) {
+            hash.update('file\0');
+            hash.update(readFileSync(absolute));
+            hash.update('\0');
+        }
+        else {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', `Dirty path is not a regular file or symlink: ${file}`);
+        }
+    }
+    return hash.digest('hex');
+}
 function transitivePredecessors(task, stepId, blockers) {
     const byId = new Map(task.steps.map((step) => [step.id, step]));
     const result = new Set();
@@ -179,13 +477,17 @@ function completedDependentClosure(task, seedIds, predecessorIds) {
     return result;
 }
 function validateInvalidationEvent(event, task) {
-    const expectedKeys = [
+    const requiredKeys = [
         'activeStepId', 'actor', 'dirtyFiles', 'eventHash', 'eventId', 'invalidatedSteps', 'packageVersion',
         'planHash', 'preservedHeadCommit', 'previousEventHash', 'previousTaskRevision', 'reason', 'recordedAt',
         'resultTaskRevision', 'taskId',
     ];
+    const actualKeys = Object.keys(event).sort();
+    const expectedLegacyKeys = [...requiredKeys].sort();
+    const expectedCurrentKeys = [...requiredKeys, 'dirtyWorktreeHash'].sort();
     if (!event || typeof event !== 'object' || Array.isArray(event)
-        || JSON.stringify(Object.keys(event).sort()) !== JSON.stringify(expectedKeys.sort())) {
+        || (JSON.stringify(actualKeys) !== JSON.stringify(expectedLegacyKeys)
+            && JSON.stringify(actualKeys) !== JSON.stringify(expectedCurrentKeys))) {
         throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation event contains unexpected fields.');
     }
     if (typeof event.eventId !== 'string' || !EVENT_ID.test(event.eventId)) {
@@ -220,6 +522,10 @@ function validateInvalidationEvent(event, task) {
         || JSON.stringify(event.dirtyFiles) !== JSON.stringify([...event.dirtyFiles].sort())) {
         throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation dirtyFiles are invalid.');
     }
+    if (event.dirtyWorktreeHash !== undefined
+        && (typeof event.dirtyWorktreeHash !== 'string' || !HASH_64.test(event.dirtyWorktreeHash))) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation dirtyWorktreeHash is invalid.');
+    }
     if (!Array.isArray(event.invalidatedSteps) || event.invalidatedSteps.length === 0) {
         throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation must identify invalidated Steps.');
     }
@@ -240,6 +546,55 @@ function validateInvalidationEvent(event, task) {
         stepIds.add(step.stepId);
     }
 }
+function validateReplanRecoveryEvent(event, task) {
+    const expectedKeys = [
+        'actor', 'dependencyRecoveryCommit', 'dirtyFiles', 'dirtyWorktreeHash', 'eventHash', 'eventId',
+        'invalidationEventId', 'invalidationPlanHash', 'knowledgeRebindRecordedAt', 'packageVersion',
+        'preservedHeadCommit', 'previousEventHash', 'previousTaskRevision', 'reason', 'reboundPlanHash',
+        'recordedAt', 'resultTaskRevision', 'taskId',
+    ];
+    if (!event || typeof event !== 'object' || Array.isArray(event)
+        || JSON.stringify(Object.keys(event).sort()) !== JSON.stringify(expectedKeys.sort())) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery event contains unexpected fields.');
+    }
+    if (typeof event.eventId !== 'string' || !REPLAN_EVENT_ID.test(event.eventId)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery eventId is invalid.');
+    }
+    if (event.taskId !== task.id
+        || !Number.isInteger(event.previousTaskRevision)
+        || event.previousTaskRevision < 1
+        || event.resultTaskRevision !== event.previousTaskRevision + 1
+        || event.resultTaskRevision > task.revision) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery Task/revision binding is invalid.');
+    }
+    if (typeof event.invalidationEventId !== 'string' || !EVENT_ID.test(event.invalidationEventId)
+        || typeof event.invalidationPlanHash !== 'string' || !HASH_64.test(event.invalidationPlanHash)
+        || typeof event.reboundPlanHash !== 'string' || !HASH_64.test(event.reboundPlanHash)
+        || typeof event.dirtyWorktreeHash !== 'string' || !HASH_64.test(event.dirtyWorktreeHash)
+        || typeof event.preservedHeadCommit !== 'string' || !GIT_HASH.test(event.preservedHeadCommit)
+        || (event.dependencyRecoveryCommit !== null
+            && (typeof event.dependencyRecoveryCommit !== 'string' || !GIT_HASH.test(event.dependencyRecoveryCommit)))) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery hash binding is invalid.');
+    }
+    if (!Number.isFinite(Date.parse(event.knowledgeRebindRecordedAt))) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery knowledge rebind timestamp is invalid.');
+    }
+    if (!Array.isArray(event.dirtyFiles) || event.dirtyFiles.length === 0
+        || event.dirtyFiles.some((file) => typeof file !== 'string' || !file.trim())
+        || new Set(event.dirtyFiles).size !== event.dirtyFiles.length
+        || JSON.stringify(event.dirtyFiles) !== JSON.stringify([...event.dirtyFiles].sort())) {
+        throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery dirtyFiles are invalid.');
+    }
+    for (const [value, label] of [
+        [event.actor, 'actor'],
+        [event.reason, 'reason'],
+        [event.packageVersion, 'packageVersion'],
+    ]) {
+        if (typeof value !== 'string' || !value.trim()) {
+            throw new WorkflowError('STATE_CORRUPT', `Downstream-proof replan recovery ${label} is required.`);
+        }
+    }
+}
 function normalizeRequired(value, label) {
     if (typeof value !== 'string' || !value.trim()) {
         throw new WorkflowError('INVALID_ARGUMENT', `${label} is required.`);