refactor(runtime): delete dead controller-generation, sealed-refresh, re-finalization and recovery-authority code

[aviggiano]

Refs #921, #462

Problem

Native Smithers continuation (#961) removed every caller of three mechanisms:

• sealed controller refreshes: refreshedSmithersControllerSnapshot, prepareControllerGeneration and commitControllerGeneration;
• controller false-failure re-finalization: refinalizeControllerFailures, reached only through the removed --refinalize-controller-failures flag;
• retry-failed recovery dispositions: state.provenance.recovery, written only by the pre-fix(runtime): restore native Smithers continuation #961 resume --retry-failed.

Their code stayed behind, about 2,350 lines of runtime source, and parts of it still ran on hot paths:

• Every linked-evidence read called effectiveControllerGeneration. That covers status, sync, pause, cancel, replay, fork and the inspection commands. No run since fix(runtime): restore native Smithers continuation #961 has a controller-generation journal, so for every current run the call replayed the whole events.jsonl and read run.json and state.json again. It then returned the sealed control snapshot unchanged.
• Every sync ran reconcilePreparedRecoveryProvenance and recoveryAuthorizesTerminalAggregate over state.provenance.recovery. For every run in scope this was dead work. fix(runtime): restore native Smithers continuation #961 removed the last writer of a disposition, and resolved-config v4 (feat(runtime): default to best-effort runs with agent-written PARTIAL reports #1120), which every run in scope uses, came after fix(runtime): restore native Smithers continuation #961. The status flip this code can cause is therefore latent, and only a pre-fix(runtime): restore native Smithers continuation #961 state can trigger it. Given a retained prepared disposition (prior_status: "failed", recovered: false, no authenticated submission), finalRunStatus reported the run failed after every task had succeeded, with no diagnostic. Reproduced on origin/integration/wave1 (a48ad9c) with a hand-written fixture: the run ends failed. On this branch it ends succeeded.
• The complexity ceiling. synchronizeLinkedWorkflowRun (cyclomatic complexity 90) set the repository-wide ceiling. refinalizeControllerFailures (74) had no caller at all.

Root cause

#961 deleted the entry points but not the machinery behind them, or the read-side hooks that still consult its state. The removed entry points were:

• the refresh prepare/commit branch in start-run.ts;
• the re-finalization flag;
• the retry-failed recovery writer;
• the only allowMissingWorkflowRun: true sync call.

Change

Six commits:

1. Delete the controller false-failure re-finalization path. Removes refinalizeControllerFailures and three helpers from workflow-sync.ts (−568 lines). The node-controller-refinalization-* event variants stay in the event schema, so old journals parse.
2. Delete the sealed controller-refresh builder and the generation writers.
   • readLinkedWorkflowEvidence materializes the verified control snapshot directly.
   • LinkedWorkflowEvidence drops controllerGeneration and controllerSnapshot. For every run without a journal they equalled controlGeneration and verifiedControl.
   • materializeWorkflowExecutionSnapshot drops the refresh-only authorizedGenerations parameter.
   • Deleted from smithers.ts: refreshedSmithersControllerSnapshot and its helpers, about 450 lines. They included the module's only use of the TypeScript compiler.
   • Deleted from workflow-controller-generation.ts: the journal writers and the selection and projection code. The file goes from 1,203 to 532 lines.
   • Deleted from workflow-integrity.ts: the refresh-only helpers.
   • The live resume --refresh-controller path (renderCurrentSmithersController) is untouched.
3. Stop consulting retry-failed recovery provenance.
   • Deletes workflow-recovery-authority.ts, reconcilePreparedRecoveryProvenance, recoveryAuthorizesTerminalAggregate and the run-recovered emission.
   • Deletes the recovery options of finalRunStatus and unattributedTerminalWorkflowFailure, and the observedTaskEvidence map that only the authorization read.
   • Deletes the recovered branch of terminal reporting.
   • Run status now follows the runner's terminal state. A succeeded state whose workflow ended failed cannot publish a terminal report.
   • The optional recovery and recovery_history state fields and the run-recovered event variant stay in their schemas.
   • One sentence in docs/reference/artifacts-reports.md is updated.
4. Delete unused sync, integrity and retry-template plumbing.
   • WorkflowSynchronizationControl.allowMissingWorkflowRun and its branch. smithersSnapshotReportsMissingRun becomes module-private.
   • verifyWorkflowControlFiles and workflowControlGeneration.
   • The runtime's use of the retry-failure preamble. The generated workflow embedded it and then discarded it (void retryFailureTemplate). The renderer, the template placeholder and the lint globals all drop it.
5. Lower the complexity ceiling from 90 to 83. synchronizeLinkedWorkflowRun drops to 76. The new repository maximum is verifyCoverageProductionInventory (83) in artifact-gates.ts. docs/contributing.md is updated to match.
6. Delete the orphaned retry-failure preamble and redundant verifier re-checks (from review).
   • .ultrafuzz/prompts/_templates/agent-preamble/retry-failure.mdx, its loader entry in packages/prompts/src/render.ts, and its prompt-catalog row. The prompt catalog is regenerated and now lists 9 composition templates. After commit 4 nothing in production loaded the file. Its test's "inserted values are data" and missing-variable assertions move to topology-runtime-context, the one preamble that production renders with variables.
   • The generation-format check in materializeWorkflowExecutionSnapshot. It stood in for sortedUniqueGenerations, which had to validate generations read from the journal. The selected generation is now always the SHA-256 of the seal (verifyWorkflowControlSnapshot), and reconcileStaleSnapshotPublications still checks it before any write. A read-only call with a malformed generation would still fail, on the snapshot-root or not-published check, before it reads a snapshot file.
   • In the kept verifyCommittedControllerGenerationAuthority: the re-checks of the journal head (manifest root, manifest identity, event authentication) and the default event replays that only the deleted writers used. verifyControllerGenerationJournalEvents already makes these checks for every entry, and every entry must be committed. The file goes from 532 to 497 lines.

Size: +142 / −3,962 lines (net −3,820).

Area	Added	Removed
Runtime sources	28	2,413
Tests	105	1,527
Prompt tree and prompts source	0	8
Docs and lint config	9	14

Removed from the @ultrafuzz/runtime index (17 names): refinalizeControllerFailures, ControllerFailureRefinalizationInput, ControllerFailureRefinalizationResult, refreshedSmithersControllerSnapshot, RefreshedSmithersControllerSnapshot, prepareControllerGeneration, commitControllerGeneration, commitPublishedPreparedControllerGeneration, effectiveControllerGeneration, PreparedControllerGeneration, EffectiveControllerGeneration, replaceBunStartupControlsForControllerRefresh, reconcileStaleWorkflowExecutionSnapshotPublications, isBunStartupControlPath, smithersSnapshotReportsMissingRun, verifyWorkflowControlFiles and workflowControlGeneration. @ultrafuzz/prompts loses the "retry-failure" member of AgentPreambleTemplateName.

Deliberately not built

• No dedicated refusal for runs that carry a controller-generation journal, although the spec allowed one.

  • Only a run refreshed before fix(runtime): restore native Smithers continuation #961 has a journal. Every such run was sealed before resolved-config v4, and feat(runtime): default to best-effort runs with agent-written PARTIAL reports #1120 put those runs out of scope.
  • On the base, synchronizing such a run already fails. Since feat(runtime): default to best-effort runs with agent-written PARTIAL reports #1120, every sync parses the sealed resolved config against a schema whose schemaVersion is const: "ultrafuzz.resolved-config.v4" (by reading the code; not run).
  • On this branch its journal is no longer read. Its refreshed snapshot generation now fails every linked-evidence read with workflow execution snapshots contain an unexpected generation (see Verification).
  • A dedicated check would add a fail-closed gate for runs that cannot finish anyway.

• Kept verifyCommittedControllerGenerationAuthority and the journal and manifest readers it needs: the 497 remaining lines of workflow-controller-generation.ts. Its only caller is the Modal per-node cloud handoff (packages/modal/src/node-provider.ts). Draft v04 deletes that caller but not this file. Once v04 lands, the whole file and its verifyCommittedControllerGenerationAuthority export have no caller. They should be deleted then, in v04 or right after it.

• Kept the old schema entries, so old state.json, run.json and events.jsonl still parse:

  • the controller-generation and recovery fields of state.json and run.json;
  • the workflow-controller-generation-recorded, node-controller-refinalization-* and run-recovered event variants.

  artifact-gates.ts still prefers controllerExecutionSnapshot when a pre-fix(runtime): restore native Smithers continuation #961 state has one.

• Left two smithers.ts candidates from the compiler map: the predecessor-patch upgrade paths and the ensureSmithersDependencies repair branches. They sit in the Smithers patch registry and controller-install code that v01 and v10 are changing.

Verification

Base for comparisons: origin/integration/wave1 at a48ad9c, in a separate worktree.

• Discriminating tests (fail on the base, pass here):
  • syncRun follows the runner past a retry-failed recovery a pre-#961 build left prepared. The base ends the run failed with an empty diagnostics list. This branch ends it succeeded.
  • linked workflow evidence does not read a leftover controller-generation journal. The base fails all reads with WORKFLOW_CONTROL_EVIDENCE_INVALID: controller generation journal is invalid. This branch succeeds in the default, observeOnly and tolerateControlDivergence modes. The base was run with the same assertions, under the test's earlier name and with a non-null assertion that was later replaced for strict lint.
  • agent preamble MDX > treats inserted values as data (moved in commit 6). The rendered value names another bound variable. Against a renderer changed to expand a second time, the test fails. The change was a temporary experiment and was reverted.
• Converted and characterization tests (pass on both):
  • syncRun publishes a report after a resumed report agent succeeds. It is rewritten from the hand-built recovery-disposition fixture to the native same-ID resume shape. It also passes on the base, so it is not evidence of the change.
  • terminal reporting refuses a succeeded run whose workflow ended failed. It keeps the refusal that the ten deleted invalid-recovery variants asserted.
• Deleted tests. Each exercised only deleted code:
  • six sealed-refresh tests in runtime.test.ts;
  • one in dynamic-lifecycle.test.ts;
  • thirteen recovery-authorization tests in verified-output.test.ts;
  • workflow-completion-policy.test.ts, whose four tests transpiled slices of workflow-sync.ts source;
  • the retry-failure byte pin in agent-preamble.test.ts.
• Uncommitted experiments (not part of the diff):
  • For the out-of-scope case, a launched run got an extra 64-hex directory beside its sealed generation, standing in for the snapshot a pre-fix(runtime): restore native Smithers continuation #961 refresh left behind. readLinkedWorkflowEvidence in all three modes, and getRunHealth, then returned WORKFLOW_CONTROL_EVIDENCE_INVALID: workflow execution snapshots contain an unexpected generation.
  • For commit 6's verifier trim, the Modal tamper test was extended to change only the journal head's event: its payload, its event_id, and the event's removal. All three are still rejected with controller generation event does not authenticate its journal entry.
• Test runs on the final tree:

  • runtime.test.ts, targeted: 23/23 pass. The pattern covered:

    • the two new tests and the converted report test;
    • every remaining controller refresh test;
    • every snapshot … materialization, recovery and anchoring test, and publishing an execution snapshot flushes each file once.

    Two of the 23 first failed at launch with the known host race workflow execution file dependencies/packages/…/<file> changed while reading (see below), and both passed when rerun alone.

  • verified-output, pinned-submodules and task-workflow-identity: 59/59 pass.

  • dynamic-lifecycle.test.ts, targeted: 8/8 pass. The pattern covered every refreshed controller and controller-refresh test, current-controller rendering, and the two published-controls readability tests.

  • @ultrafuzz/prompts agent-preamble and scaffold-catalog: 7/7 pass.

  • Modal node-provider.test.ts -t "controller-generation|controller generations" (the kept verifier): 4/4 pass.

  • Earlier, before commit 6: all of dynamic-lifecycle.test.ts passed except dynamic state materialization checks the synchronization deadline before publication. That test failed once under host load, then passed four reruns here and one on the base. Its 500 ms deadline also bounds the fake runner's inspection subprocess, because inspectionExecutionControl passes deadlineMs − now as the timeout. That is the likely cause (inferred, not proven).

• Gates: all pass on the final tree.
  • pnpm -w build, pnpm -w typecheck, pnpm -w knip and pnpm -w docs:check;
  • npx prettier --check and npx eslint on the changed files;
  • CI=1 ESLINT_PLUGIN_DIFF_COMMIT=origin/integration/wave1 pnpm -w lint:strict:ci;
  • pnpm -w lint. A repo-wide complexity scan puts the maximum at 83, down from 90 on the base.
• Resume ABI. A resumed run's old generated workflow still loads against this build. The check covered every distinct version of workflow.tsx on origin/integration/wave1: 98 blobs, from git rev-list origin/integration/wave1 -- <path>. None of the 19 deleted exports appears anywhere in any of them (whole-file word match). The 19 are the 17 index names plus the two recovery-authority functions.
• Not run to completion: a full four-shard run of runtime.test.ts. It was interrupted after about 11 minutes and is not evidence either way. Its three failures were:
  • twice, the known host race workflow execution file dependencies/packages/…/LICENSE changed while reading, which trips when other processes run pnpm on the host;
  • the torn-ledger test described below.

Risk / compatibility

• Runs sealed since fix(runtime): restore native Smithers continuation #961. They never carry a journal or a recovery disposition, so their behaviour is unchanged. The only difference is one fewer full events.jsonl replay per linked-evidence read (by reading the code; not timed).

• Runs from before fix(runtime): restore native Smithers continuation #961. These are pre-v4 and out of scope (feat(runtime): default to best-effort runs with agent-written PARTIAL reports #1120).

  • A refreshed one now fails status, pause, cancel, replay, fork and the inspection commands with the snapshot-generation error above. Plain resume does not read linked evidence and is unaffected (by reading).
  • A retained recovery disposition no longer changes run status.
  • A run that a pre-fix(runtime): restore native Smithers continuation #961 build recovered can no longer re-read its published terminal report (report, dashboard). Its state is succeeded, its last workflow-synced is failed, and it has recovered: true. loadCurrentFinalReportSnapshot repeats the stopped-state check on every read and now throws terminal reporting lacks consistent stopped workflow evidence (by reading; not run). Such reports are very likely unreadable on the base already. The saved receipt must match today's projection byte for byte, and the report projection has changed since fix(runtime): restore native Smithers continuation #961 (6fffcf4, 131ff3e, b964ae2).

• Generated workflows and prompts. Old generated workflows keep working: none references a deleted runtime name, and each already embeds its rendered preamble, so deleting retry-failure.mdx changes nothing for a sealed run. No digest covers the built-in prompt tree.

• API.

  • LinkedWorkflowEvidence loses two fields.
  • materializeWorkflowExecutionSnapshot loses one optional parameter.
  • renderAgentPreambleTemplate and loadAgentPreambleTemplate no longer accept "retry-failure".

  No workspace package used any of these; pnpm -w build passes.

• Merge overlap. A git merge-tree of this branch against every pushed wave-2 branch shows one conflict:

  • smithers.ts with v04. v04 edits refreshedSmithersControllerSnapshot and replaceInternalModuleFiles, which this branch deletes, and both branches trim the same import lines. To resolve it:
    • keep this branch's deletion of the refresh builder;
    • in the imports, take both removals. v04 drops isSensitiveSecretValue, whose last use it deletes. This branch drops assertExpandedGraphSchema and the typescript type import.

  No other pushed wave-2 branch adds a use of a deleted name. These overlaps merge cleanly:

  • workflow-sync.ts synchronizeTasks (v02's node-status transitions);
  • smithers.ts outside the deleted code (v01's Smithers patch registry);
  • packages/prompts/src/render.ts (v07);
  • the prompt catalog (v13);
  • the test-file deletions, including workflow-completion-policy.test.ts, which v09a may also target.

  v10 is not pushed, so it was not checked. It also changes the smithers.ts import block.

• Pre-existing failure, not fixed here. status keeps reporting runner health when run-state synchronization fails fails identically on the base. Its torn usage.jsonl no longer makes synchronization throw, because w02 (fix(runtime): attempt and usage ledgers never block run synchronization #1186) turned accounting failures into WORKFLOW_ACCOUNTING_FAILED warnings. The test still expects WORKFLOW_STATE_SYNC_FAILED.

Changelog entry

Removed three pieces of code that native continuation (#961) left without callers: the sealed controller-refresh (controller-generation journal) code, controller re-finalization, and retry-failed recovery. resume --refresh-controller is unchanged. status, sync, pause, cancel, replay and fork no longer replay the event journal to select a controller generation. Run status now follows the workflow runner instead of a retained recovery disposition. Two kinds of pre-#961 run are affected, and both were planned before resolved-config v4, so they are already out of scope. A run refreshed before #961 now fails these commands. A run recovered before #961 can no longer re-read its terminal report.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge within the current resolved-config v4 run contract.

Summary

Removes orphaned controller-generation, re-finalization, and retry-failed recovery machinery. Linked-evidence reads now use the verified seal directly, and synchronization follows the runner’s terminal state. The PR also removes the unused retry-failure preamble and lowers the complexity ceiling.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Verified workflow-control seal] --> B[Linked workflow evidence]
  B --> C[Single execution snapshot]
  C --> D[Lifecycle and inspection]
  D --> E[Runner and task evidence]
  E --> F[Run status]
  F --> G[Terminal report consistency check]

Loading

_{Reviews (1) · Last reviewed commit: "refactor: delete the orphaned retry-fail..."}