Flows: opt-in per-node resume (skip completed nodes on re-run)

[superWorldSavior]

Context

Claude Code's native Workflow tool supports deterministic resume: relaunch with resumeFromRunId, and the longest unchanged prefix of agent() calls returns cached results instantly — only edited/new calls (and everything downstream) run live. It's journaled per agent call.

acpx Flows already have most of the substrate for this:

• run artifacts persist under ~/.acpx/flows/runs/<runId>/
• runs are replayable for inspection (flow viewer)
• checkpoint() provides human/external pause-resume
• the runtime already owns persistence, retries, timeouts, routing

Gap

There's no way to re-run a flow and skip nodes that already completed. If a long flow (multi-step, 10–55 min) crashes near the end, or you edit a single downstream node, you re-run the whole graph.

Proposal

Opt-in, per-node memoization keyed on (node id + resolved input hash), persisted in the existing run dir. On acpx flow run --resume <runId> (name TBD): for each node whose key matches a completed record, short-circuit to the recorded outcome; the first changed/new node and everything downstream runs live.

The declared graph is what makes this clean — nodes have stable identities, unlike a dynamic/model-driven fan-out where "what changed" is a judgment, not a diff.

Important: must be opt-in / selective

Some nodes are nondeterministic by design and must stay fresh on every run — adversarial N-skeptic verify, loop-until-dry, "second opinion" passes. Memoization should be per-node (e.g. memoize: true, default off) so these are never cached. The value is in skipping deterministic labor, not in suppressing intentional re-sampling.

Prior art

Claude Code Workflow tool: resumeFromRunId + journaled agent-<id>.jsonl, "same script + same args → 100% cache hit."

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 31, 2026, 11:25 PM ET / 03:25 UTC.

Summary
Keep open: current main still starts a fresh flow run every time and has no flow-level resume or per-node memoization surface. The request fits acpx's robustness goals, but it adds new CLI/API and persistence semantics that need maintainer design before implementation.

Reproducibility: not applicable. this is a feature request, not a bug report. Source inspection does confirm the requested flow resume and per-node memoization surfaces are absent on current main.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
A repair PR should wait for maintainer direction on the public resume API, memoization contract, and persistence model.

Review details

Best possible solution:

Design a default-off flow resume mode with explicit per-node memoization metadata, stable cache-key semantics, and tests proving both fresh-run compatibility and resumed deterministic-node skipping.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a feature request, not a bug report. Source inspection does confirm the requested flow resume and per-node memoization surfaces are absent on current main.

Is this the best way to solve the issue?

Unclear; the proposal is directionally plausible, but the exact CLI flag, node field, cache key, and persistence semantics need maintainer product/API review before a fix PR should be attempted.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The cache key, downstream invalidation, run-directory mutation versus derived rerun bundle, and ACP session-binding replay semantics are not designed yet.
• Caching ACP nodes could suppress intentional re-sampling unless the default-off, per-node opt-in behavior is preserved clearly.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 1522159f9fd8.

Label changes

Label changes:

• add P2: This is a normal-priority flow robustness improvement with limited blast radius, not an urgent regression.
• add impact:session-state: The request concerns persisted flow run state and reusing prior node outcomes across reruns.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority flow robustness improvement with limited blast radius, not an urgent regression.
• impact:session-state: The request concerns persisted flow run state and reusing prior node outcomes across reruns.

Evidence reviewed

Acceptance criteria:

• pnpm run check
• pnpm run check:docs

What I checked:

• Repository policy applied: AGENTS.md was read fully; its flow guidance says workflow changes should preserve graph shape by default and persistent ACP flow sessions should resume the same underlying agent session instead of silently replacing it. (AGENTS.md:207, 1522159f9fd8)
• FlowRunner always creates a fresh run: FlowRunner.run creates a new run id, run directory, and empty outputs/results/steps state on every invocation; there is no path for loading a previous run before execution. (src/flows/runtime.ts:189, 1522159f9fd8)
• CLI has no flow resume flag: The registered flow run command exposes --input-json, --input-file, and --default-agent only. (src/cli/command-registration.ts:317, 1522159f9fd8)
• Flow node types do not model memoization: Current node definitions include timeout, heartbeat, status detail, ACP/session fields, run/exec/prompt/parse functions, and checkpoint metadata, but no typed memoize/cache key contract. (src/flows/types.ts:53, 1522159f9fd8)
• Docs describe replay-only immutable bundles: The flow docs say a run id is generated for each run and terminated bundles are immutable replay-viewer inputs, not reusable execution caches. (docs/flows.md:33, 1522159f9fd8)
• No existing implementation or canonical duplicate found: Source/docs/test search found only ordinary session resume surfaces, not flow run resume or memoization; GitHub issue search for flow resume and memoization returned this issue plus unrelated session/runtime items.

Likely related people:

• osolmaz: GitHub history ties osolmaz to the original flows runtime, trace replay bundles, flow run title API, defineFlow validation, and runtime embedding refactor that shape this request. (role: feature owner / recent area contributor; confidence: high; commits: 697ee1f2a659, 4008683d51f7, e75d471563af; files: src/flows/runtime.ts, src/flows/store.ts, src/flows/types.ts)
• steipete: Recent permission-policy work touched flow CLI/runtime/types, which are likely affected by any new flow resume flag or node metadata contract. (role: recent adjacent contributor; confidence: medium; commits: bd4eeb8b3d0e; files: src/flows/cli.ts, src/flows/runtime.ts, src/flows/types.ts)
• DaniAkash: Recent runtime status metadata work touched flow runtime support and the public runtime surfaces that a resumable flow execution mode may need to report accurately. (role: adjacent runtime contributor; confidence: low; commits: f6de6dd18aae; files: src/flows/runtime-support.ts, src/runtime/public/contract.ts, src/runtime/public/events.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.