fix(runtime): epic records carry sub-flow tasks and session ids; docs reconciled with the landed flow API

[futrime]

Unit 14 — final integration of the new flow API on feat/new-flow-api.

Epic records (engine ↔ runtime recorder)

• Sub-flow calls carry their task. LiveCall gains task (and resumable); the engine's Call keeps the task it was called with, and the runner's recorder writes both into the called/began records. tree(epic) now reads back each call's task.
• The resume journal carries real session ids. A session record is written once the CLI has named the session: at open where the id is known then (fakes), otherwise on the first spend the turn reports after naming (a _Naming sink, used only for an unnamed session's turns), with the turn's end as the fallback. One record per session, none for a session never named, and a failure to write it is logged rather than replacing the turn's outcome. FakeAgentDriver(names_late=True) stands in for a CLI that names late. The engine tells the recorder too (Recorder.named), so a late-named non-coganchor session goes into the epic by its id instead of "?".
• The recorder holds only open sessions. Recorder.closed(session) is new, and the run's spend now comes from the engine's own reckoning (Recorder.began(spent), the totals its budget is held to). So nothing is lost from a turn that is still accounting after its session closed. Run.agents is now the agents behind the open sessions, and Recorder.finished() freezes the total once the run ends.
• Epic.links(only) copied every session to link one, which made a run of n sessions O(n²). Found by the 10k-session test, which went from 4.6s to 1s.
• Tests:
  • A 10k-session loop on the fake kit, asserting that memory held by the recorder stays bounded and the usage totals are right.
  • Recorder-hears-everything (task, began, closed).
  • A late-named session journaled once, and journaled mid-turn.
  • Late-named fake sessions going into the epic by id.
  • The recorder's usage equals the engine's.
  • Sub-flow tasks in tree.
  • Session ids in resume.jsonl, via the stand-in claude.

Also fixed

• Failure reports had lost the flow context the old runtime registered, although telemetry.SENT (shown when consent is asked) still promises it. The runner registers it again: the flows running, their depth and how long they have run, plus each role's CLI, model, effort, account by name, permission and skills. It never includes the task. Covered by tests/integration/runtime/test_reported.py.
• coganchor/places.py, agents/pi.py and agents/config.py no longer point at flowing.checking/driving.

Left as is, on purpose

• The coganchor markers Needs, Goal, Remote, Isolated and AgentDefaults are dead as flow API. They are still declared in specs/coganchor/agents.md and exported from hmz.coganchor.agents, so removing them is not clean without a spec change the flow rewrite does not force.
• The TUI board: specs/tui.md still requires it ("MUST draw the board a flow and a person share…", key d). The code path is therefore kept even though a flow-API run never has one. The docs say so.
• Epic._sessions still keeps one small (backend, id) pair per session so that logs written late get linked when the run ends.

Docs

• CLI:
  • The real error lines, with argparse's usage line only for a line it cannot read.
  • Every environment is probed first.
  • Exit 0 for a run its budget stopped.
  • --resume, resume.jsonl and picked_up.
• SDK: Hmz.read/runner/run, Refused, fakes, and the whole of Run.
• Tracing records.
• The daemon demo and run.tape now read resume.jsonl, and tapes/stage.py is ported to today's Epic. GIFs were not re-rendered.
• HmzSurfaces uses the real SDK surface and gen-plan params.
• chat's roles, workspace and online=ALL.
• The flow catalogue now matches feat(flows)!: move the small flows and aot to the new flow API flowverse#34–fix(agents): a turn that failed closes on a failed rather than on nothing #39:
  • the role is orchestrator;
  • params and defaults;
  • BudgetExceeded and "three failures in a row" endings;
  • the rlcr quiz runs only when somebody is there;
  • humanize1 has no default flow;
  • the lane flows' scratch storage and shared lock;
  • new pages for aot, the agent-cleanup pair and recursive_lean_prover.
• TUI reference and user guide:
  • auto roles are not listed;
  • env rows are typed as -e specs;
  • the outworlder is answered at the prompt, and /afk makes it away;
  • a third ctrl+c calls Run.close();
  • /resume is described as implemented;
  • no board for a flow-API run.
• Imports of nonexistent modules (hmz.prices, hmz.providers, hmz.telemetry) are fixed.
• pnpm build and pnpm check:anchors pass.

Specs (only lines that conflicted)

• runtime/SPEC.md: the Recorder's began/named/closed/finished methods; a called flow's record says its task; the run holds no session past its close.
• runtime/flowing.md: the LiveCall fields, the Recorder protocol, and when a session journal record is written.
• runtime/doing.md: Run.agents means open sessions.

Verification

• uv run pre-commit run --all-files: all hooks pass.
• uv run pytest (all tiers, system tier without --run-agents): 4158 passed, 110 skipped.
• Docs: pnpm install --frozen-lockfile && pnpm build && pnpm check:anchors pass.
• The testing-flows page's test examples were extracted and run: 7 pass.
• E2E, with the stand-in claude on PATH and a flow that calls a subflow:
  • hmz exec -f demo -a worker=claude/claude-haiku-4-5:high -b cost=1 "…": the epic's called record carries the subflow's task, and both sessions are recorded by id.
  • The resumable demo:counts was stopped by -b output_tokens=4 (exit 0, hmz exec: stopped -- …). The journal holds session records with the CLI's ids, and state is {done: 2}.
  • --resume picked it up (picked_up recorded) and finished it with {done: 3}.

🤖 Generated with Claude Code