Feature request: persist dynamic-workflow run state incrementally (and version the on-disk schema)

Open 💬 0 comments Opened Jul 5, 2026 by michaelandrewgamble

Problem

The workflow run record (~/.claude/projects/<proj>/<session>/workflows/wf_<id>.json) is written only at terminal status. While a run executes — precisely when visibility matters most — disk holds only the journal (content-addressed cache keys + agent IDs, no timestamps) and growing agent transcripts. Observable consequences for any tooling (and arguably for Claude Code's own surfaces):

  • No reliable liveness: running, paused, and crashed are indistinguishable externally; a run that dies without writing its record looks "maybe live" forever. Tools must infer state from file mtimes.
  • No run identity mid-flight: workflow name, phase plan, and expected agent count exist on disk only after completion (or via parsing the script copy, which is not always present).
  • No queue visibility: agents waiting beyond the concurrency cap exist only in runtime memory.
  • Resume-after-kill ambiguity: a killed run resumed in its owning session reuses the same runId/dir while the stale killed record sits beside live transcripts — external readers see a contradiction.

Ask

  1. Write the run record (or a lightweight sibling, e.g. wf_<id>.state.json) at run start and update it on phase/agent transitions: status: running|paused, current phase, agents started/done/queued, and update it on resume.
  2. Version the schema (a schemaVersion field). The journal already carries v2: cache-key prefixes, so the format is evolving — a version field would let ecosystem tools degrade gracefully instead of guessing.
  3. Ideally: document the run-record/journal formats as a (best-effort) contract. Even "unstable, but versioned and described" would be a large improvement over reverse-engineering.

Context

Everything above was established empirically while building workflows-conductor, which reconstructs /workflows-style observability from these artifacts across projects and surfaces. Its reader survives the current ambiguity via mtime heuristics, open status enums, and per-record compat tagging — but heuristics mislabel edge cases that incremental persistence would make exact. Related: #72292, and a separate request for an external run-control API.

View original on GitHub ↗