moar docs

docs/README.md

@@ -26,6 +26,8 @@ implementation plans are kept for context, not as active instructions.
   and current payload validation limits.
 - [`workflow_artifacts.md`](workflow_artifacts.md): saved workflow artifacts,
   deployments, dependency compatibility, and interrupt limitations.
+- [`durable_run_operations.md`](durable_run_operations.md): `run_deployment`,
+  `inspect_run`, bounded trace reads, and `resume_run` behavior.
 - [`workflow_drafts.md`](workflow_drafts.md): LLM/human draft authoring format
   above raw workflow plans.
 
@@ -75,13 +77,19 @@ implementation plans are kept for context, not as active instructions.
 - [`superpowers/specs/`](superpowers/specs/): design specs produced during
   planning sessions.
 
-## Future Runtime Work
+## Runtime References
 
-Two runtime features may come back after the platform/DX roadmap advances:
+Native subgraphs, concurrent foreach, lineage state, and durable stopped-run
+resume now have implemented foundations. Use the current roadmap and ADR/spec
+docs as the active references:
 
-- Native subgraph execution with child run state, interrupt bubbling, and resume
+- [`current_roadmap.md`](current_roadmap.md): active implementation status and
-  back into the child workflow.
+  next-work list.
-- Concurrent foreach with explicit scheduling, reducer/merge semantics, and
+- [`adr/0001-scheduler-foundation-before-concurrent-foreach.md`](adr/0001-scheduler-foundation-before-concurrent-foreach.md):
-  failure policy. Sync runtime can interleave item frames deterministically;
+  scheduler foundation decision.
-  async runtime can add simultaneous async node handler execution. Do not
+- [`adr/0002-concurrent-foreach-policy-and-barrier-commits.md`](adr/0002-concurrent-foreach-policy-and-barrier-commits.md):
-  implement this as plain `asyncio.gather` over sync handlers.
+  concurrent foreach policy and barrier commit semantics.
+- [`superpowers/specs/2026-05-24-native-subgraphs-design.md`](superpowers/specs/2026-05-24-native-subgraphs-design.md):
+  native subgraph design.
+- [`superpowers/specs/2026-05-26-durable-workflow-runs-and-resume-design.md`](superpowers/specs/2026-05-26-durable-workflow-runs-and-resume-design.md):
+  durable run/checkpoint design.

docs/durable_run_operations.md

@@ -0,0 +1,144 @@
+# Durable Run Operations
+
+This document describes the current operational contract for saved workflow
+runs exposed through `wf.workflow.*`. It is intentionally about the platform
+surface, not the lower-level scheduler internals.
+
+## Mental Model
+
+A deployment run is a stored execution attempt for one saved deployment.
+`run_deployment` starts the attempt and returns when the workflow either:
+
+- completes
+- fails
+- pauses at an interrupt
+- is blocked before resume because a pinned dependency is unavailable
+
+Every started deployment receives a stable `run_id`. That id is the handle for
+inspection, bounded trace reads, and interrupt resume.
+
+Durability is checkpointed at public stopped boundaries only. V1 does not
+checkpoint after every node, during an in-flight tool call, or in the middle of
+one scheduler tick.
+
+## Primary Tool Flow
+
+Use this flow for normal clients:
+
+```text
+wf.workflow.run_deployment
+  -> wf.workflow.inspect_run
+  -> wf.workflow.read_run_trace, only if debugging
+  -> wf.workflow.resume_run, only if interrupted
+```
+
+`run_deployment` is the stable front door. Do not rely on saved workflows being
+projected as newly-created MCP tools in the current session; many clients do
+not rebuild callable schemas after `tools/list` changes.
+
+## `run_deployment`
+
+Starts one deployment execution:
+
+```json
+{
+  "deployment_id": "echo.personal",
+  "workflow_input": {"text": "hello"}
+}
+```
+
+The compact response includes:
+
+- `run_id`: durable handle for this execution attempt
+- `status`: runtime status such as `completed`, `failed`, or `interrupted`
+- `outcome`: terminal workflow outcome when available
+- `output`: projected workflow output when available
+- `diagnostics`: dependency/runtime diagnostics
+- `trace_count`: total trace entry count
+- `latest_checkpoint_id`: latest stopped-state checkpoint when persisted
+
+Omit `trace_range` for normal calls. Trace entries can include resolved node
+inputs, outputs, and state changes, so they are debug payloads rather than
+summary data.
+
+## `inspect_run`
+
+Reads one stopped run by `run_id` without returning trace entries:
+
+```json
+{"run_id": "run_abc123"}
+```
+
+Use this when a client already has a `run_id` and needs the current durable
+summary: status, outcome/output if available, diagnostics, and checkpoint
+metadata.
+
+## `read_run_trace`
+
+Reads a bounded trace slice:
+
+```json
+{
+  "run_id": "run_abc123",
+  "trace_range": {"start": 0, "limit": 10}
+}
+```
+
+Keep ranges small. This is the intended path for debugging failed or surprising
+runs without bloating every run response.
+
+## `resume_run`
+
+Resumes an interrupted run:
+
+```json
+{
+  "run_id": "run_abc123",
+  "resume_payload": {"approved": true},
+  "resume_outcome": "submitted"
+}
+```
+
+Before applying the resume payload, the platform revalidates the pinned
+dependency environment captured for the run. If a required source or saved child
+artifact is missing, disabled, or incompatible, resume returns blocked readiness
+diagnostics and does not consume the payload or append a new execution
+checkpoint.
+
+Ordinary live execution failures are not pauses. If an upstream tool disconnects
+or raises during normal execution, the run fails and should be inspected/debugged
+like any other failed run.
+
+## Checkpoint Boundaries
+
+Current stopped checkpoints are written when public run operations return:
+
+- `run_deployment` returns completed, failed, or interrupted
+- `resume_run` returns completed, failed, or interrupted
+
+Blocked resume readiness is different: the execution state did not advance, so
+the previous checkpoint remains the latest execution checkpoint.
+
+This keeps the initial durable model simple and safe. Future protocol-native
+long-running work may add task/progress integration, but it should not change
+the core rule that external callers resume by `run_id`.
+
+## Debugging Rules For LLM Clients
+
+- Always capture `run_id` from `run_deployment`.
+- Prefer `inspect_run` before reading trace detail.
+- Use `read_run_trace` with explicit small ranges.
+- Treat `trace_count` as metadata, not an instruction to fetch the entire trace.
+- If `resume_run` is blocked, repair the reported dependency issue and retry
+  with the same `run_id`.
+- If the run failed because a live source errored during execution, do not retry
+  through `resume_run`; start a new run after repairing the source/problem.
+
+## Current Limits
+
+- No mid-call crash recovery.
+- No per-node checkpoint stream.
+- No protocol-native MCP Tasks integration yet.
+- No dynamic saved-workflow-as-tool projection requirement.
+- No automatic pause on disconnected sources; source failures are failed runs.
+

docs/wf_mcp_end_to_end_runbook.md

@@ -397,6 +397,12 @@ as the total original trace length and supports explicit ranged debug reads such
 as `"trace_range": {"start": 0, "limit": 10}`. Trace entries may contain
 resolved inputs, outputs, and state changes.
 
+Capture the returned `run_id`. Use `wf.workflow.inspect_run` to read the stored
+summary later, `wf.workflow.read_run_trace` for small debug slices, and
+`wf.workflow.resume_run` only when the run status is `interrupted`. The full
+operational contract lives in
+[`durable_run_operations.md`](durable_run_operations.md).
+
 ## 10. Rebind The Same Artifact Later
 
 If another compatible account appears:

docs/wf_mcp_operator_manual.md

@@ -369,6 +369,11 @@ be resumed after server/handler recreation; if a pinned source is missing or
 disabled, `resume_run` returns `resume_readiness="blocked"` without advancing
 the execution checkpoint.
 
+The detailed run contract is documented in
+[`durable_run_operations.md`](durable_run_operations.md). The short rule is:
+capture `run_id`, inspect summaries first, read bounded trace slices only when
+debugging, and resume only runs that are actually interrupted.
+
 ## Which Tool Do I Use?
 
 | I want to... | Use |

docs/workflow_artifacts.md

@@ -89,6 +89,8 @@ definitions so handler/server recreation does not invalidate the `run_id`.
 
 Durable run history is specified in
 [`2026-05-26-durable-workflow-runs-and-resume-design.md`](superpowers/specs/2026-05-26-durable-workflow-runs-and-resume-design.md).
+The operator-facing run contract is summarized in
+[`durable_run_operations.md`](durable_run_operations.md).
 The implemented surface is:
 
 - `run_deployment` starts or completes a run and returns `run_id`