Why a Source-Recovery Pipeline Must Be Restartable

Source recovery is not one command followed by a finished repository.

It can involve capture, source-map admission, vendor identification, runtime observation, semantic cleanup, structural work, parity, and handoff. Some stages are deterministic. Others require operator review or bounded agent judgment. Real work is interrupted by failed checks, machine restarts, dependency changes, new donor captures, and ordinary human schedules.

A pipeline that can only move forward in one uninterrupted session is not operationally credible.

Restart is not “run everything again”

Re-running from the beginning can be wasteful, but blindly continuing is worse. The pipeline needs to know which prior claims still apply.

A useful checkpoint binds at least:

• the donor integrity root;
• the candidate source fingerprint;
• the active stage and configuration;
• the evidence artifacts accepted so far;
• the last green validator state;
• unresolved blockers and their owners;
• the exact next actions that remain valid.

If any of those inputs drift, the system should recompute or invalidate the affected advice. It should not infer continuity from the presence of an old report.

Candidate drift changes the question

Suppose a semantic-cleanup plan was prepared for one candidate hash. An engineer then edits the same files before the plan is applied.

The old plan may still sound reasonable, but its preconditions no longer match. Applying it can overwrite newer work, target moved spans, or certify decisions against evidence that describes a different program.

A restartable system detects that drift and chooses among explicit outcomes:

• regenerate the plan;
• adopt the new candidate state and reacquire evidence;
• resume from an earlier trusted checkpoint;
• retain the workspace for investigation;
• refuse to continue until the conflict is resolved.

“Best effort” is not an acceptable hidden policy for source mutation.

Evidence freshness is stage-specific

Not every change invalidates everything.

A documentation edit should not necessarily force a new runtime capture. A changed donor bundle should invalidate downstream source-map, vendor, and parity conclusions. A candidate-only rename may require local syntax and parity checks while leaving the donor seal intact.

The useful model is a dependency graph of claims. Each artifact names the state axes it depends on, and freshness is computed against those axes.

This lets the pipeline resume cheaply when it can and fail closed when it cannot.

Leases prevent duplicate authority

Restartability also matters when more than one process or agent is involved. Two workers should not apply the same cleanup brief, promote the same checkpoint, or publish competing stage outcomes concurrently.

Bounded leases and single-flight coordination turn “someone is working on it” into machine-visible state. A lease expires or is released; it does not become permanent ownership hidden in a chat transcript.

Repair should preserve the forensic trail

When a stage fails halfway through, cleanup should not erase the evidence needed to understand why.

A sound recovery workflow separates temporary files from durable receipts. It can roll back a partial promotion while retaining:

• the failed stage result;
• the preimage and intended postimage;
• validator diagnostics;
• the reason for rollback;
• the recommended repair path.

This is especially important for intermittent runtime or parity failures. Deleting the failed candidate may make the workspace clean while making the engineering problem opaque.

Restartability improves handoff

The same machinery that supports a restart also supports a new engineer joining the work.

Instead of reconstructing state from terminal history, the engineer can see the current donor, last trusted checkpoint, live blockers, stale artifacts, protected surfaces, and next bounded action.

That is a better definition of progress than “the previous agent said it was almost done.”

KodeBack treats restartability as part of recovery correctness. A pipeline that cannot explain where it is, what remains trustworthy, and how to resume has not preserved enough evidence to claim control of the work.