工作区隔离

cwd: "temp"        →  /tmp/pi-tf-ws-<phase>-XXXXXX   （阶段完成后删除）
cwd: "dedicated"   →  <runs>/ws/<runId>/<phaseId>    （保留以供检查）
cwd: "worktree"    →  基于一次性分支的 git worktree  （阶段完成后删除）

{
  "id": "draft-patch",
  "type": "agent",
  "cwd": "temp",
  "task": "根据下面的描述编写补丁。\n{steps.analyze.output}"
}

{
  "id": "generate-report",
  "type": "agent",
  "cwd": "dedicated",
  "task": "根据审计数据生成完整的 HTML 报告。\n{steps.audit.json}"
}

{
  "id": "apply-migration",
  "type": "agent",
  "cwd": "worktree",
  "task": "应用上一步的数据库迁移方案。每个迁移文件单独 commit。"
}

workspace:temp — worktree requested but base cwd is not a git work tree; used a temp dir instead

1. phase.cwd 是关键字？
   否  → 在 deps.cwd（默认路径）中运行阶段。完毕。
   是  ↓
2. allocateWorkspace(keyword, {baseCwd, runId, phaseId, runsRoot})
   → Workspace { dir, kind, teardown, branch?, note? }
3. 将 deps.cwd 覆盖为 ws.dir 用于阶段的子代理
4. 执行阶段
5. 将工作区诊断信息附加到 PhaseState.warnings（如有降级）
6. 在 finally 块中调用 ws.teardown()（best-effort）

workspace — dedicated workspace alloc failed: EACCES: permission denied

阶段是否写入你在它完成后需要的文件？
  是 → dedicated
  否 ↓
阶段是否需要 git（commit、diff、分支）？
  是 → worktree
  否 → temp

{
  "name": "compare-approaches",
  "phases": [
    {
      "id": "approach-a",
      "type": "agent",
      "cwd": "temp",
      "task": "使用方案 A 实现该功能。"
    },
    {
      "id": "approach-b",
      "type": "agent",
      "cwd": "temp",
      "task": "使用方案 B 实现该功能。"
    },
    {
      "id": "judge",
      "type": "agent",
      "task": "比较：\nA: {steps.approach-a.output}\nB: {steps.approach-b.output}",
      "dependsOn": ["approach-a", "approach-b"],
      "final": true
    }
  ]
}

{
  "name": "refactor-tournament",
  "phases": [
    {
      "id": "variant-1",
      "type": "agent",
      "cwd": "worktree",
      "task": "使用策略模式重构 auth 模块。每个文件变更单独 commit。"
    },
    {
      "id": "variant-2",
      "type": "agent",
      "cwd": "worktree",
      "task": "使用中间件链重构 auth 模块。每个文件变更单独 commit。"
    },
    {
      "id": "judge",
      "type": "gate",
      "task": "审查两种重构方案。对更好的那个输出 VERDICT: PASS 并说明理由。",
      "dependsOn": ["variant-1", "variant-2"],
      "final": true
    }
  ]
}

{
  "name": "security-audit",
  "phases": [
    {
      "id": "scan",
      "type": "agent",
      "cwd": "dedicated",
      "task": "扫描代码库中的漏洞。将发现的所有问题写入 findings.json 文件。"
    },
    {
      "id": "report",
      "type": "agent",
      "task": "读取扫描结果：\n{steps.scan.output}\n写一份人类可读的摘要。",
      "dependsOn": ["scan"],
      "final": true
    }
  ]
}

workspace:temp at /tmp/pi-tf-ws-draft-patch-a1b2c3/
workspace:temp — worktree requested but base cwd is not a git work tree; used a temp dir instead
workspace — dedicated workspace alloc failed: EACCES: permission denied
workspace:worktree at /tmp/pi-tf-wt-apply-migration-x4y5z6/ (branch: tf/abc123/apply-migration-m3k2j1)

---

## meta.json Placement

Insert `concepts/workspace-isolation` after `concepts/context-isolation` in both meta.json files:

**`website/content/docs/en/meta.json`** — change:

to:

**`website/content/docs/zh-cn/meta.json`** — same change:

This places Workspace Isolation between Context Isolation (which covers the transcript-level isolation) and Resume (which references workspace behavior on re-run). The conceptual flow is: "your outputs are isolated → your filesystem can be isolated → and all of this survives across sessions."

## Risk Review

**Severity summary:** 0 critical, 0 high, 1 medium, 2 low findings. No issues block the documentation merge.

### Medium

**M1 — `dedicated` workspace is NOT idempotent across resume attempts (documentation accuracy risk).**
The doc states: *"A `dedicated` workspace accumulates across resume attempts."* This is technically correct per the code (`workspace.ts:131-137` — `mkdirSync({ recursive: true })` is idempotent, but never clears prior contents). However, the doc's warning about this could be stronger. If a `dedicated` phase writes a file that the next resume attempt reads and misinterprets as "already done," you get a silent data-integrity bug at the flow-author level. The doc addresses this with the Callout about idempotency, which is appropriate.

**Evidence:** `workspace.ts:134` — `fs.mkdirSync(dir, { recursive: true })` does not clear the directory.

### Low

**L1 — `worktree` branch name is not collision-proof on rapid sequential runs.**
The branch name `tf/<runId>/<phaseId>-<Date.now().toString(36)>` uses millisecond-resolution timestamps. Two rapid sequential runs (same runId, same phaseId, within 1ms) could theoretically collide, though in practice `runId` uniqueness prevents this. Not a documentation concern; just a code observation.

**Evidence:** `workspace.ts:149` — `branch = \`tf/${safeSegment(runId)}/${seg}-${Date.now().toString(36)}\``.

**L2 — The `rmrf` containment check for `dedicated` workspaces relies on `runsRoot` being passed as an `allowedRoots` parameter.**
The `teardown` for `dedicated` is a no-op, so this is moot today. But if someone adds teardown later, the `rmrf` function at `workspace.ts:85-93` only checks `os.tmpdir()` by default. The `dedicated` path under `runsRoot/ws/` would NOT be in the allowed roots unless explicitly passed. Again, not a current bug — just a latent risk if teardown semantics change.

**Evidence:** `workspace.ts:136` — `teardown() {}` (no-op for dedicated).

### Passes

- **Fail-open documentation is accurate.** Every degradation path documented in the article matches the code: temp alloc failure → inherited (workspace.ts:122-125), dedicated alloc failure → inherited (workspace.ts:137-139), worktree non-git → temp (workspace.ts:144-147), worktree add failure → temp (workspace.ts:159-164), teardown errors → swallowed (runtime.ts:747-749).
- **Path containment documentation is accurate.** `safeSegment` sanitization (workspace.ts:80-83) and `rmrf` root restriction (workspace.ts:85-93) are correctly described.
- **Dynamic sub-flow restriction is accurately documented.** Schema validation blocks workspace keywords in dynamic flows (schema.ts:588-590).
- **Resume behavior is correctly described.** `temp`/`worktree` are re-allocated; `dedicated` is deterministic; cached phases skip allocation entirely (verified via runtime.ts:723-724 early return for non-keyword cwd, and the cached phase path never reaches workspace allocation).

### Recommendation: **Approved.**

The documentation is technically precise, matches the source code evidence, and correctly describes all failure modes, cleanup semantics, and resume behavior.

### Decisions

- Assumed the `<Callout>` MDX component and `<Cards>`/`<Card>` components are available project-wide (confirmed from existing concepts docs).
- Assumed frontmatter `title`/`description` is the correct schema (confirmed from existing docs).
- Did not verify whether the Chinese `zh-cn` docs are auto-translated or hand-maintained; wrote a full hand-translated Chinese version matching the style of `zh-cn/concepts/context-isolation.mdx` (which preserves technical English terms like `fail-open`, `opt-in`, `best-effort`, `transcript`).

---

### [3/5] risk-reviewer

Now I have all the evidence needed. Here are the two complete `.mdx` files:

---

## Risk Review

Not applicable to this task — this is a documentation authoring task, not a code change review. Proceeding with the deliverable.

---

## `meta.json` placement

Insert `guides/background-runs` **after `guides/tournament` and before the case studies**. Updated `pages` array section:

---

## FILE: `website/content/docs/en/guides/background-runs.mdx`

```mdx
---
title: Background Runs
description: Fire off a long-running flow and get your prompt back immediately. Poll status by runId.
---

A normal `taskflow` call blocks your session until every phase finishes. For a three-phase code audit that takes eight minutes, that is eight minutes your prompt is frozen.

Background runs fix this. Set `detach: true` and the MCP tool returns a `runId` in under a second. A child process picks up the work, persists progress after every phase, and writes the terminal state when it finishes — or crashes. You poll the run state from disk whenever you want a status update, and resume it later if it fails partway through.

This guide walks through the exact spawn mechanism, how to check on a background run, what happens to approval gates, and the limitations that come with running headless.

## The basic pattern

Ask the `taskflow` tool to run a flow with `detach: true`:

```json
{
  "action": "run",
  "name": "code-audit",
  "args": { "target": "src/auth" },
  "detach": true
}

Taskflow 'code-audit' started in background (pid: 48231). Run id: 20260706T143022-a1b2c3

/tf runs

{
  "id": "__detach__",
  "status": "failed",
  "error": "Detached runner exited with code 1: Failed to load runner module 'pi-taskflow/dist/runner.js'..."
}

output: "(auto-rejected: no interactive approver available)"
approval: { decision: "reject", auto: true }
gate: { verdict: "block" }

# Pseudocode for a CI step
RUN_ID=$(taskflow run --name code-audit --detach --json | jq -r '.runId')

while true; do
  STATUS=$(taskflow status --run-id "$RUN_ID" --json | jq -r '.status')
  case "$STATUS" in
    completed) exit 0 ;;
    failed|blocked) exit 1 ;;
    running) sleep 10 ;;
  esac
done

/tf runs          ← see progress

{
  "runId": "20260706T143022-a1b2c3",
  "defName": "code-audit",
  "args": { "target": "src/auth" },
  "cwd": "/Users/you/project",
  "runnerModule": "/Users/you/.pi/extensions/pi-taskflow/dist/runner.js",
  "runnerExport": "piSubagentRunner"
}

{
  "action": "resume",
  "runId": "20260706T143022-a1b2c3"
}

{
  "action": "run",
  "name": "code-audit",
  "detach": true,
  "incremental": true
}

Parent (host session)                    Child (detached runner)
│                                        │
├─ saveRun(state, detached:true)         │
├─ write context JSON to /tmp            │
├─ spawn(node, [runner, tmpFile])  ───►  ├─ readFileSync(contextPath)
│                                        ├─ loadRun(runId)
├─ child.on("exit", crashGuard)          ├─ import(runnerModule)
├─ child.unref()                         ├─ executeTaskflow(...)
├─ return { runId, pid }                 │   ├─ phase 1 → saveRun
│                                        │   ├─ phase 2 → saveRun
│   ... session continues ...            │   ├─ phase 3 → saveRun
│                                        │   └─ persist terminal state
│                                        └─ exit(0)
│
├─ (crash guard: exit code 0 → no-op)
└─ user polls /tf runs → sees "completed"