docs(managed-agent): Stage H4/H5/H6 slice designs - #13499

@qwen-code /triage

@qwen-code /triage

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

— Qwen Code · sandboxed verification

Thanks for the PR!

Template looks good ✓ — every required heading is present, and the design-doc rule the template calls out (link both language versions, keep them synchronized) is satisfied: all three pairs exist with reciprocal links, and all 19 relative .md links in the six new files resolve at the head commit.

Problem: this isn't a bug fix, so there's no reproduction to ask for — the driver is the open tracker #12827, which assigns each Stage H capability its own admission/receipt/cancel/quota/recovery checks, and AGENTS.md requires a design doc for non-trivial work before the code lands. That's an observed, tracked need rather than theoretical hardening.

Direction: aligned. Stage H is an active roadmap item (#12827 is open and carries roadmap/multi-agent, roadmap/hooks-events, roadmap/background-automation), and these three docs sit squarely inside it. CHANGELOG gives a genuine supporting signal here: upstream is dense with fixes for exactly the failure class these designs target — subagents and scheduled tasks losing state across resume, compaction, restart and sleep, and background agents stalling after a host wake. The premise that an in-process callback, roster or PID is not a recovery credential is well corroborated by how often that breaks upstream.

Size: not applicable. All six files are new docs under docs/design/; no core paths are touched, so there are 0 production logic lines. The 1210 added lines are documentation, which the Stage 0 size gate deliberately does not count, and the author is a maintainer in any case.

Approach: the scope feels right, and — worth saying, because it's the less common direction — these docs actively narrow rather than expand. H4 defers independent worktrees, teams and the mailbox and admits only read_only_snapshot; H5 ports one reference adapter (email) instead of the twelve; H6 refuses webhook triggers at admission until their slice lands. Each capability gets explicit non-goals and per-slice exit gates, which is what makes a tracker like #12827 sliceable. Keeping the three in one PR is defensible since H6 consumes contracts from both H4 and H5.

I did verify the factual claims rather than take them on trust, and they hold up unusually well — the registered-but-not-enabled domain state, the absent record bodies for schedule/automation_run/channel_route/channel_delivery, the missing WakeIntent, the legacy scheduled-task-run.ts path, the public TaskKind enum, the two runtime-broker flags, the twelve-adapter inventory, and the email state store's exact bounds (33 pending / 64 outbound / 1024 dedupe / 256 routes) all read out of the tree as described. One stale item turned up in H4's current-state section; I've written it up in the review comment rather than here, since it's a code-review finding and not a gate concern.

Risk: no elevated risk signals — the Stage 1e high-risk path scan matched nothing.

Moving on to code review. 🔍

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 5001174978b55388ca52cc408051ee18d32013b6 · re-run with @qwen-code /triage}

Code review

Docs-only, so the review is about whether the documents are correct and self-consistent rather than whether code behaves. I read all six files at the head commit and checked the factual claims against the tree instead of taking them on trust — about twenty of them, including the ones that are easiest to get subtly wrong. They hold up remarkably well, and in a few places better than I expected: the email state store's bounds are quoted exactly right (pending ≤ 33, outboundPending 64, recent 1024, routes ≤ 256), the twelve-adapter inventory under packages/channels matches the directory listing entry for entry, and the claim that child_agent/automation_run are frozen in the public TaskKind is correct — it refers to the generated API contract's enum, not the unrelated internal TaskKind in agents/tasks/types.ts. The runtime-broker.trusted-local-reboot-recovery flag is real too; it lives as a Java property, not in the TypeScript tree.

One thing did turn up, and it's worth fixing before merge because of where it sits.

H4's current-state section is stale on child_run, and contradicts the same document. The "Domain index" bullet says that of child_run, child_acceptance and the four team_* names, "none of them has a record body in MANAGED_EXTENSION_RECORD_BODIES". On today's main that is false for child_run — it has a body at managed-extension-projection.ts:151, with taskKind: 'background_shell' and recordId = record.shellId. I checked both refs to be sure this is drift rather than an error: at the baseline the doc pins (5ddfacc9d4) the bodies were only the four MCP/Hook ones plus monitor_run, so the bullet was accurate when written; H3 landed the shell body afterwards. The document's own "Record bodies (H4a contract direction)" section then states the current fact correctly — "managed-child_run is already registered on main with the H3, single-kind body" — and the H3 module header it cites really does say "H4 extends the domain to the other child kinds under its own body version". So the file asserts both things, each true against a different commit.

That would be a harmless inconsistency in most sections, but the current-state section is precisely the part whose stated job is to stop later slices re-investigating — and the registered shell body is the single most consequential constraint on H4a. It is the whole reason H4a must define body version 2 as a kind-union with kind: 'shell' kept byte-identical, instead of writing a v1 body. A reader who trusts current state alone would design H4a the wrong way and break replay for every committed Shell. The Chinese twin carries the identical line (and the identical correct statement further down), so this is baseline drift in both languages rather than a translation-sync gap — the fix needs to land in both.

Two smaller items of the same kind:

• "monitor_run has a body and still stays disabled until H3" — it does have a body and it is still absent from MANAGED_SESSION_ENABLED_DOMAINS, so both halves are right, but "until H3" now reads as though H3 were future work when H3 has landed.
• "a Flyway migration after main's V34" appears in all three validation plans (six places across both languages). V34 was the highest migration at the pinned baseline; main is at V46 now. Since these lines will be read when H4a/H5a/H6a actually land, the number understates by twelve. The historical citation in H4 ("O4 retirement (feat(managed-agent): Protect Session-owned tool output retirement #13084, V30) and collection (V34)") is fine as-is — that records what V34 did rather than instructing anyone.

The cheapest honest fix is to keep the pinned baseline and add a short note where the doc already speaks about "main" unscoped, so current state and the record-body section agree. Re-verifying and refreshing the baseline wholesale would also work but is more churn than the problem needs.

None of this blocks: there is no runtime surface here, every document is explicitly marked proposed-design with nothing implemented and no domain enabled, and the H4a body-version-2 design that the stale line obscures is itself correct and well reasoned. Structural requirements are all met — eleven sections per pair in identical order and heading levels across all three pairs, reciprocal language links, and all nineteen relative links resolving. The byte volumes also confirm the Chinese versions are full translations rather than summaries (17.5 KB against 19.9 KB, 17.9 against 20.2, 21.2 against 24.9 — the lopsided line counts are just the English being hard-wrapped at ~76 columns while the Chinese runs one line per paragraph), which is what the design README requires.

Testing evidence

This is an unattended CI run, so per the gate rules I did not build or execute anything from the PR — the evidence below is the PR's own CI, read through the API for the reviewed commit. Nothing in this diff is user-visible (six new Markdown files, no code, no TUI surface), so real-scenario terminal testing is N/A, and there is no behavioural claim for a sandboxed lane to settle — @qwen-code /verify and @qwen-code /tmux would have nothing to observe. Not verified: the documents' forward-looking design decisions (body version 2, the four-part ingress identity, the scanner lease) are proposals, so there is nothing to test yet; that is by design and the docs say so.

The PR's Qwen Code CI workflow run completed successfully, so no checks were pending at review time. The skips are the path-filtered jobs — macOS/Windows unit legs, CLI integration and the web-shell E2E smoke — which is the expected shape for a docs-only diff; the Linux unit and lint legs that do run are green. review-pr was still in progress, but that is bot orchestration on the comment event, not PR CI, and does not gate this.

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 5001174978b55388ca52cc408051ee18d32013b6 · re-run with @qwen-code /triage}

Confidence: 4/5 — accurate, well-scoped design groundwork that meets every structural requirement; the one real defect is a stale current-state line that is non-blocking and cheap to fix.

Before reading the diff I wrote down what I'd expect from a tracker-driven design slice: one document per capability, bilingual twins, a current-state section pinned to a named commit so nobody re-investigates, a slice plan with exit gates that actually gate, and non-goals that say what's being deferred. This PR matches all of that, and it exceeds my baseline in one respect I would not have anticipated — the H4a body-version-2 kind-union. Discovering that managed-child_run already carries an H3 single-kind body, and designing so that kind: 'shell' stays byte-identical while kind: 'child_agent' gets the new body with recordId = childRunId, is the most valuable thing in the diff. You only find that by reading the tree rather than the tracker, and it stops H4a from being designed in a way that would break replay for every committed Shell. The domain.committed payload version widening to 1 | 2 for that one domain only, with every other domain held at version == 1, is the right amount of care.

The scope discipline is what I'd point at as the reason this doesn't read as volume. Three capabilities could easily have become three speculative platform designs; instead H4 admits only read_only_snapshot and refuses the other two isolation names at admission until their slice lands, H5 ports one adapter out of twelve and names why email is the right first one (its legacy state already separates mailbox generation, event identity, in-flight uncertainty and reply routes — the four concepts the contracts need), and H6 refuses webhook triggers rather than half-designing them. Every doc says plainly that nothing in it is implemented and no domain is enabled. Six files, zero deletions, no drive-by edits, nothing unrelated — the diff is exactly the stated goal.

My reservation is the one I wrote up in the review: H4's current-state bullet still says child_run has no record body, which was true at the pinned baseline 5ddfacc9d4 and is false on main now that H3 has landed, while the same file's record-body section states the current fact correctly. I'd normally weight a self-contradiction more heavily, but here the mechanism is benign and the correction is two lines per language — and notably the section that's stale is stale in the safe direction, since the accurate section is the one that carries the design consequence. The monitor_run ... until H3 phrasing and the six "after main's V34" references are the same drift and want the same touch. Worth folding into whichever PR picks up H4a rather than respinning this one.

On the questions I'm supposed to ask myself: this is groundwork for an open, labelled roadmap tracker, so the "does anyone want this" test is answered by #12827 existing. In six months the pinned baselines are what will make these documents trustworthy rather than archaeological, which is exactly why the one stale line is worth naming. I checked whether I was being worn down by volume or approving for want of objections — I found a genuine defect, traced it to the commit where it became wrong, and it doesn't block, so the approval is a judgement rather than a shrug. CI is green on the reviewed commit with nothing pending.

Approving. The three staleness items above are non-blocking follow-ups, not conditions.

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 5001174978b55388ca52cc408051ee18d32013b6 · re-run with @qwen-code /triage}