heggria · heggria · Jul 18, 2026 · Jul 18, 2026 · Jul 18, 2026 · Jul 18, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -10,14 +10,14 @@
   "plugins": [
     {
       "name": "taskflow",
-      "description": "Multi-phase subagent orchestration for Codex: 15 taskflow_* MCP tools (run/resume/version/list/show/verify/compile/peek/trace/replay/why_stale/recompute/reconcile_workspace/save/search) plus a routing skill. compile returns SVG + text outline. The server runs via npx (codex-taskflow).",
+      "description": "Multi-phase subagent orchestration for Codex: 16 taskflow_* MCP tools (run/runs/resume/version/list/show/verify/compile/peek/trace/replay/why_stale/recompute/reconcile_workspace/save/search) plus a routing skill. Background runs support status/wait/cancel; compile returns SVG + text outline. The server runs via npx (codex-taskflow).",
       "source": "./packages/codex-taskflow/plugin",
       "category": "developer-tools",
       "homepage": "https://github.com/heggria/taskflow"
     },
     {
       "name": "claude-taskflow",
-      "description": "Multi-phase subagent orchestration for Claude Code: 15 taskflow_* MCP tools (run/resume/version/list/show/verify/compile/peek/trace/replay/why_stale/recompute/reconcile_workspace/save/search) plus a routing skill. compile returns SVG + text outline. The server runs via npx (claude-taskflow).",
+      "description": "Multi-phase subagent orchestration for Claude Code: 16 taskflow_* MCP tools (run/runs/resume/version/list/show/verify/compile/peek/trace/replay/why_stale/recompute/reconcile_workspace/save/search) plus a routing skill. Background runs support status/wait/cancel; compile returns SVG + text outline. The server runs via npx (claude-taskflow).",
       "source": "./packages/claude-taskflow/plugin",
       "category": "developer-tools",
       "homepage": "https://github.com/heggria/taskflow"

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -26,7 +26,7 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           cache: "pnpm"
@@ -49,7 +49,7 @@ jobs:
       # in package.json, so every contributor and CI run use the same pnpm.
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ matrix.node }}
           registry-url: "https://registry.npmjs.org"
@@ -72,7 +72,7 @@ jobs:
 
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           registry-url: "https://registry.npmjs.org"
@@ -124,7 +124,7 @@ jobs:
 
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           registry-url: "https://registry.npmjs.org"
@@ -146,7 +146,7 @@ jobs:
 
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           registry-url: "https://registry.npmjs.org"
@@ -172,7 +172,7 @@ jobs:
 
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           cache: "pnpm"

diff --git a/.github/workflows/deploy-website.yml b/.github/workflows/deploy-website.yml
@@ -48,7 +48,7 @@ jobs:
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
 
       - name: Setup Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: 22
           cache: pnpm

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -48,7 +48,7 @@ jobs:
           fi
           echo "Verified $GITHUB_REF_NAME at $TAG_COMMIT is reachable from origin/main"
       - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           registry-url: "https://registry.npmjs.org"

diff --git a/.grok-plugin/marketplace.json b/.grok-plugin/marketplace.json
@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "taskflow",
-      "description": "Multi-phase subagent orchestration for Grok Build: 15 taskflow_* MCP tools (run/resume/version/list/show/verify/compile/peek/trace/replay/why_stale/recompute/reconcile_workspace/save/search) plus a routing skill. compile returns SVG + text outline. The server runs via npx (grok-taskflow).",
+      "description": "Multi-phase subagent orchestration for Grok Build: 16 taskflow_* MCP tools (run/runs/resume/version/list/show/verify/compile/peek/trace/replay/why_stale/recompute/reconcile_workspace/save/search) plus a routing skill. Background runs support status/wait/cancel; compile returns SVG + text outline. The server runs via npx (grok-taskflow).",
       "source": {
         "type": "local",
         "path": "./packages/grok-taskflow/plugin"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,26 @@
 
 All notable changes to taskflow are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [0.2.3] — 2026-07-18
+
+### Added
+
+- **Durable MCP background runs.** `taskflow_run` now accepts `mode: "background"` on Codex, Claude Code, OpenCode, and Grok Build, returning a durable `runId` immediately instead of tying a long DAG to one MCP request timeout. The new `taskflow_runs` tool lists background runs and supports `status`, bounded/repeatable `wait`, and explicit `cancel`; lists report the total active count and can filter `running` versus `terminal` runs. Detached runs persist their final output and trace, preserve incremental-cache and library-reuse behavior, detect orphaned processes, and use a file-backed cancellation control plane that survives MCP request and server boundaries. Starting a sixth concurrent background run emits an explicit resource-contention warning because Taskflow intentionally has no hidden global cross-host scheduler.
+
+### Changed
+
+- **Release maintenance rollup.** The 0.2 frontier assessment is now linked from both READMEs; Pi development peers move to 0.80.7, Fumadocs packages move to their mutually compatible 16.11.5/15.2.0 set, Biome moves to 2.5.4, and every workflow uses the verified `actions/setup-node` v7.0.0 tag commit. These changes absorb the independently opened maintenance PRs into the fully tested 0.2.3 release transaction.
+
+### Fixed
+
+- **Atomic terminal results.** The runtime now persists `finalOutput` and `outputSourcePhaseId` in the same terminal-state write, so a crash or immediate poll can never observe `completed` without its result.
+- **Detached-run ownership and cleanup.** Cancellation and process-heartbeat records now live in a user-private control directory keyed by canonical invocation root, preventing project symlinks and sibling worktrees from redirecting or cross-cancelling runs. Current workers carry a versioned instance identity; stale authenticated workers are killed before terminalization and their registered Host CLI process groups are reaped, inherited detached-runner environment variables cannot claim an outer run, the spawn-only worker consumes only user-owned private temp contexts, and ambiguous legacy runs fail closed for cancellation.
+- **Foreground/background parity.** MCP and Pi detached launches snapshot the same agent scope, model roles, global thinking, runner profile, incremental settings, and retention policy as the foreground invocation. Pi now uses fully detached stdio and transactionally reaps the worker plus its private launch context when post-spawn setup fails. Launch failures preserve their real cause, and post-spawn roster diagnostics can no longer misreport a successfully started run as a launch failure.
+- **Bounded run history and accurate rosters.** Retention now applies to every inactive state (`completed`, `failed`, `paused`, and `blocked`) while never pruning active runs. Cleanup is throttled independently per project, uses short fail-open lock waits, validates physical directories as well as indexed paths, and rechecks the selected snapshot under the run lock, preventing cross-project starvation, symlink traversal, and resume/delete races. Detached control records are removed only when their persisted cwd belongs to the run store being retained. MCP background lists compute counts from the complete project roster without the former 1000-run cap or per-row reload pattern.
+- **File-lock ownership.** Expired locks are stolen only when their recorded owner process is definitively dead, stale-lock stealers serialize on a generation claim, and release verifies both inode and a random owner token. A slow live writer can no longer overlap a replacement writer or unlink its successor's lock.
+- **Run-id and status compatibility.** Dot-leading flow names now produce persistable run IDs without weakening traversal guards. Background status ignores synthetic launch phases in progress totals and tolerates malformed legacy optional output instead of crashing the MCP request.
+- **Release surface synchronization.** Package/plugin versions, installation pins, built-dist MCP expectations, the 16-tool roster, background-run documentation, and English/Chinese host guides are synchronized for 0.2.3.
+
 ## [0.2.2] — 2026-07-14
 
 ### ⚠️ Breaking — migration required

diff --git a/README.md b/README.md
@@ -131,7 +131,7 @@ Save it as `.pi/taskflows/audit-api.json`, then run:
 /tf:audit-api dir=src/api
 ```
 
-On Codex, Claude Code, OpenCode, and Grok Build, run the same saved definition by name through `taskflow_run`.
+On Codex, Claude Code, OpenCode, and Grok Build, run the same saved definition by name through `taskflow_run`. For long DAGs, use `mode: "background"`, then manage the durable run with `taskflow_runs` (`list` / `status` / `wait` / `cancel`); list output reports active concurrency and can filter `running` or `terminal` runs.
 
 [Follow the full quickstart →](https://heggria.github.io/taskflow/en/docs/getting-started)
 
@@ -315,7 +315,7 @@ claude plugin install claude-taskflow@taskflow
 
 ```bash
 opencode mcp add taskflow -- \
-  npx -y -p opencode-taskflow@0.2.2 opencode-taskflow-mcp
+  npx -y -p opencode-taskflow@0.2.3 opencode-taskflow-mcp
 ```
 
 [OpenCode guide →](https://heggria.github.io/taskflow/en/docs/guides/opencode)
@@ -324,7 +324,7 @@ opencode mcp add taskflow -- \
 
 ```bash
 grok mcp add taskflow -- \
-  npx -y -p grok-taskflow@0.2.2 grok-taskflow-mcp
+  npx -y -p grok-taskflow@0.2.3 grok-taskflow-mcp
 ```
 
 Grok Build support is new in 0.2. Its CLI stream does not report token/cost usage, so budget-declaring flows are rejected rather than silently running without enforcement.
@@ -365,6 +365,7 @@ The test suite covers orchestration semantics, persistence and file-lock races,
 | [Host Guides](https://heggria.github.io/taskflow/en/docs/guides/) | Pi, Codex, Claude Code, OpenCode, and Grok setup |
 | [Reference](https://heggria.github.io/taskflow/en/docs/reference/) | Commands, shorthand, and exact tool surfaces |
 | [Showcase](https://heggria.github.io/taskflow/en/docs/showcase/) | Real flows and case studies |
+| [0.2.0 Frontier Assessment](./docs/taskflow-0.2.0-frontier-assessment.zh-CN.md) | Independent, evidence-based technical assessment (Chinese) |
 
 Also see [`examples/`](./examples), the [changelog](./CHANGELOG.md), and the [release guide](./RELEASE.md).
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -131,7 +131,7 @@ pi install npm:pi-taskflow
 /tf:audit-api dir=src/api
 ```
 
-在 Codex、Claude Code、OpenCode 和 Grok Build 上，通过 `taskflow_run` 按名称运行同一份保存定义。
+在 Codex、Claude Code、OpenCode 和 Grok Build 上，通过 `taskflow_run` 按名称运行同一份保存定义。长任务可使用 `mode: "background"`，再用 `taskflow_runs` 执行 `list` / `status` / `wait` / `cancel`，无需担心单次 MCP 调用超时；列表会显示当前并发数，并可筛选 `running` 或 `terminal` 运行。
 
 [查看完整快速开始 →](https://heggria.github.io/taskflow/zh-cn/docs/getting-started)
 
@@ -310,7 +310,7 @@ claude plugin install claude-taskflow@taskflow
 
 ```bash
 opencode mcp add taskflow -- \
-  npx -y -p opencode-taskflow@0.2.2 opencode-taskflow-mcp
+  npx -y -p opencode-taskflow@0.2.3 opencode-taskflow-mcp
 ```
 
 [OpenCode 指南 →](https://heggria.github.io/taskflow/zh-cn/docs/guides/opencode)
@@ -319,7 +319,7 @@ opencode mcp add taskflow -- \
 
 ```bash
 grok mcp add taskflow -- \
-  npx -y -p grok-taskflow@0.2.2 grok-taskflow-mcp
+  npx -y -p grok-taskflow@0.2.3 grok-taskflow-mcp
 ```
 
 Grok Build 支持在 0.2 首次加入。其 CLI stream 不返回 token/cost 用量，因此声明了预算的 flow 会被拒绝，而不是在无法执行预算约束时静默运行。
@@ -360,6 +360,7 @@ Grok Build 支持在 0.2 首次加入。其 CLI stream 不返回 token/cost 用
 | [宿主指南](https://heggria.github.io/taskflow/zh-cn/docs/guides/) | Pi、Codex、Claude Code、OpenCode、Grok 配置 |
 | [参考](https://heggria.github.io/taskflow/zh-cn/docs/reference/) | 命令、简写与精确工具接口 |
 | [Showcase](https://heggria.github.io/taskflow/zh-cn/docs/showcase/) | 真实 flow 与案例研究 |
+| [0.2.0 前沿性评估](./docs/taskflow-0.2.0-frontier-assessment.zh-CN.md) | 基于源码、竞品与采用数据的独立技术报告 |
 
 另见 [`examples/`](./examples)、[变更日志](./CHANGELOG.md)和[发版指南](./RELEASE.md)。
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -81,8 +81,8 @@ the matching annotated tag:
 ```sh
 git switch main
 git pull --ff-only origin main
-git tag -a v0.2.2 -m "Release v0.2.2"
-git push origin v0.2.2
+git tag -a v0.2.3 -m "Release v0.2.3"
+git push origin v0.2.3
 ```
 
 `.github/workflows/publish.yml` then performs the complete release transaction:
@@ -140,6 +140,6 @@ claude plugin install claude-taskflow@taskflow
 opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
 
 # Grok Build (published MCP package)
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.2 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.3 grok-taskflow-mcp
 # or: grok mcp add taskflow -- npx -y -p grok-taskflow grok-taskflow-mcp
 ```
diff --git a/docs/claude-mcp.md b/docs/claude-mcp.md
@@ -35,7 +35,7 @@ Verify:
 
 ```sh
 claude plugin list   # → claude-taskflow@taskflow  installed, enabled
-claude mcp list      # → taskflow … (npx -y -p claude-taskflow@0.2.2 claude-taskflow-mcp)
+claude mcp list      # → taskflow … (npx -y -p claude-taskflow@0.2.3 claude-taskflow-mcp)
 ```
 
 The bundled skill tells Claude Code *when* to reach for the tools (multi-phase
@@ -74,12 +74,14 @@ such as npm tokens, database URLs, and other-provider API keys are not inherited
 
 ## Long-running flows and the tool-call timeout
 
-`taskflow_run` returns only after the **whole DAG finishes** — intermediate
-phase outputs stay in the runtime, so from Claude Code's side it's a single tool
-call that can run for many minutes. If a flow is genuinely huge, consider
-splitting it into a few smaller `taskflow_run` calls so each returns promptly,
-or run it in the background from a plain shell (`claude -p … &`) and inspect the
-run afterward with `taskflow_peek`.
+Foreground `taskflow_run` returns only after the **whole DAG finishes**. For a
+long flow, pass `mode: "background"`: it returns a durable `runId` immediately
+and continues independently of that MCP request. Use `taskflow_runs` with
+`action: "status"`, `"wait"`, or `"cancel"`; `wait` is bounded by `timeoutMs`
+and can be called repeatedly until the persisted final output is ready.
+`action: "list"` reports total active concurrency and accepts
+`status: "running" | "terminal"`; starting a sixth active background run warns
+that no global cross-host concurrency/budget coordinator exists.
 
 ## Alternative: register the MCP server manually
 
@@ -113,7 +115,8 @@ subagent a flow spawns is itself a `claude -p` process — no pi process needed.
 
 | Tool | What it does |
 |------|--------------|
-| `taskflow_run` | Run a saved flow (`name`) or an inline `define` (full DAG or shorthand `{task}`/`{tasks}`/`{chain}`). Returns only the final phase output + a `runId`. |
+| `taskflow_run` | Run a saved or inline flow. Foreground returns the final output; `mode: "background"` returns a durable `runId` immediately. |
+| `taskflow_runs` | List background runs or `status` / `wait` / `cancel` one by `runId`. |
 | `taskflow_list` | List saved flows discoverable from the cwd, now with library metadata (`purpose`, `generality`, `reuseCount`) when available. |
 | `taskflow_show` | Show a saved flow as `{definition, library}` — the `library` object holds the sidecar metadata (`purpose`, `tags`, `generality`, `reuseCount`, `phaseSignature`, …). |
 | `taskflow_save` | Save a flow to the library with optional `purpose`, `tags`, and `notes`. Writes the flow JSON plus a sidecar `.meta.json`. |