review: fail probe:capture when a multi-turn scenario cannot resume; document Host Test on the examples pages; releasable changeset

Author: ScriptedAlchemy

.changeset/claude-orchestration-lineage-evidence.md

@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Record the live Claude Code 2.1.259 orchestration session (2026-09-03) on the Claude capability table's `lineage.*` rows: two `Agent` spawns issued in one message arrive serialised so each child binds to its own spawn call, an `Explore` subagent carries the same lineage fields and reaches the plugin's MCP tools, `PostToolUseFailure` inside a subagent carries the subagent's `agent_id`, the root `session_id` survives `--resume` and a manual `/compact`, and `claudecode/toolUseId` matched at depth 0, 1, and 2 (fixtures `fixtures/host-lineage/claude-2.1.259-orchestration{,.stream}.ndjson`). Emitted host output and `adapterRevision` are unchanged.
+Extend the Claude host capability table (`claude-2.1.250.json`, rendered on the hosts reference page) with live Claude Code 2.1.259 evidence on the `lineage.subagent-events`, `lineage.root`, `lineage.parent`, `lineage.depth`, and `lineage.mcp-correlation` rows: two `Agent` spawns issued in one message bind to their own spawn calls, `Explore` subagents carry the same lineage fields as `general-purpose` ones, `PostToolUseFailure` carries the subagent's `agent_id`, the root `session_id` survives `--resume` and `/compact`, and `claudecode/toolUseId` correlates MCP calls at depth 0, 1, and 2. Emitted host output and `adapterRevision` are unchanged. (#455)

examples/host-test/scripts/probe.mjs

@@ -330,12 +330,14 @@ const captureClaude = () => {
       const envelopes = parseStream(result.stdout ?? '');
       sessionId ??= envelopes.find((envelope) => typeof envelope.session_id === 'string')?.session_id;
       log(`turn ${String(index + 1)}/${String(turns.length)}: exit ${String(result.status)}, session ${sessionId ?? 'unknown'}; ${describeStream(envelopes)}`);
-      results.push({ ...result, stdoutExtension: 'stream.ndjson' });
-      if (result.status !== 0) break;
-      if (sessionId === undefined && index + 1 < turns.length) {
-        log('the first turn reported no session_id, so the remaining turns cannot resume it');
+      if (result.status === 0 && sessionId === undefined && index + 1 < turns.length) {
+        // A multi-turn scenario without a session to resume is not the
+        // scenario: fail the turn so `capture()` refuses the partial run.
+        results.push({ ...result, failure: 'the first turn reported no session_id, so the remaining turns cannot resume it', stdoutExtension: 'stream.ndjson' });
         break;
       }
+      results.push({ ...result, stdoutExtension: 'stream.ndjson' });
+      if (result.status !== 0) break;
     }
   } finally {
     mock?.kill();
@@ -397,8 +399,10 @@ const capture = () => {
     writeFileSync(join(paths.captures, `${name}.${turn.stdoutExtension}`), turn.stdout ?? '');
     writeFileSync(join(paths.captures, `${name}.stderr.txt`), turn.stderr ?? '');
   }
-  // The session failed if any turn did.
-  const result = turns.find((turn) => turn.status !== 0) ?? turns[turns.length - 1];
+  // The session failed if any turn did, or if the driver could not run the
+  // whole scenario (`failure`).
+  const result = turns.find((turn) => turn.status !== 0 || turn.failure !== undefined) ?? turns[turns.length - 1];
+  const failed = result.status !== 0 || result.failure !== undefined;
   log(`host exit ${String(result.status)} over ${String(turns.length)} turn(s); transcript at ${join(paths.captures, `session-${stamp}.*`)}`);
   const appended = existsSync(logFile) ? readFileSync(logFile).subarray(startOffset).toString('utf8') : '';
   const records = appended.split('\n').filter(Boolean).map((line) => JSON.parse(line));
@@ -417,9 +421,9 @@ const capture = () => {
   // session nor a session that produced no hook AND no MCP evidence is a
   // capture: automation must see the failure.
   const missing = ['event', 'mcp'].filter((kind) => !kinds.has(kind));
-  if (result.status !== 0) {
-    log(`host session failed with exit ${String(result.status)}; captures above are partial evidence at best`);
-    process.exitCode = result.status ?? 1;
+  if (failed) {
+    log(`host session failed (${result.failure ?? `exit ${String(result.status)}`}); captures above are partial evidence at best`);
+    process.exitCode = result.status === 0 || result.status === null ? 1 : result.status;
   } else if (missing.length > 0) {
     log(`host session exited 0 but produced no ${missing.join(' and no ')} record; the scenario requires both`);
     process.exitCode = 1;

website/docs/en/examples/index.mdx

@@ -1,10 +1,10 @@
 ---
-description: 'The runnable agent-bundle examples: four walkthroughs from a Skills starter to a complete media-management plugin, plus two advanced composition references.'
+description: 'The runnable agent-bundle examples: four walkthroughs from a Skills starter to a complete media-management plugin, plus three advanced composition references.'
 ---
 
 # Examples
 
-The repository ships six examples, and they are products rather than fixtures. Each one uses
+The repository ships seven examples, and they are products rather than fixtures. Each one uses
 only public `agent-bundle` exports and `workspace:*` dependencies, each one builds and validates
 through the same public CLI you would use, and none of them needs an API key or a signed-in host
 to reach a useful state. Four have a walkthrough here:
@@ -16,13 +16,14 @@ to reach a useful state. Four have a walkthrough here:
 | [MCP App](./mcp-app.mdx) | A generated stdio MCP server plus an interactive MCP App resource. | `pnpm example:mcp-app` |
 | [Audiobook Curator](./audiobook-curator.mdx) | A complete route-tree application: MCP, projected CLI, providers, durable state. | `pnpm example:audiobook` |
 
-Two more are advanced composition references, documented by their own READMEs rather than
+Three more are advanced composition references, documented by their own READMEs rather than
 walked through here:
 
 | Example | What it proves |
 | --- | --- |
 | [Worktree Proximity](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/worktree-proximity) | One root task and two child agents in linked worktrees, coordinated through durable notices. |
 | [RSC Agent Runtime](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/rsc-agent-runtime) | An opt-in architecture experiment: one RSC runtime shared by hooks, MCP tools, and an MCP App timeline. Not a public API. |
+| [Host Test](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/host-test) | A probe plugin that records every hook payload and MCP call a host delivers, with the `request.lineage` each one resolved to. Its `probe:install` / `probe:capture` / `probe:uninstall` scripts drive a real host in an isolated home; `probe:capture <host> --scenario <file.json>` runs an ordered list of prompts as one multi-turn session (Claude: `claude -p --output-format stream-json`, later turns `--resume`d), saving the model's own tool-use stream beside the hook log. The Workbench walkthrough needs no signed-in host; the probe lifecycle does. |
 
 ## Running them
 
@@ -46,8 +47,8 @@ pnpm examples:check
 
 Each example package also exposes the same public commands directly, once the repository-level
 `pnpm build` has built the local `agent-bundle` workspace dependency. Every example has `validate`,
-`build`, and `check`; the four walkthrough examples and Worktree Proximity also have `dev`, while the
-RSC Agent Runtime demo is driven through its tests and `eval:hosts` instead:
+`build`, and `check`; the four walkthrough examples, Worktree Proximity, and Host Test also have `dev`,
+while the RSC Agent Runtime demo is driven through its tests and `eval:hosts` instead:
 
 ```sh
 cd examples/skills-starter

website/docs/zh/examples/index.mdx

@@ -1,10 +1,10 @@
 ---
-description: '可运行的 agent-bundle 示例：从 Skill 起步项目到完整媒体管理插件的四篇导览，外加两个进阶组合参考。'
+description: '可运行的 agent-bundle 示例：从 Skill 起步项目到完整媒体管理插件的四篇导览，外加三个进阶组合参考。'
 ---
 
 # 示例
 
-仓库中带有六个示例，它们是产品，而不是测试夹具。每个示例只使用公开的 `agent-bundle` 导出与
+仓库中带有七个示例，它们是产品，而不是测试夹具。每个示例只使用公开的 `agent-bundle` 导出与
 `workspace:*` 依赖，都通过你自己也会用的那套公开命令行来构建与校验，并且都不需要 API key 或已登录的
 宿主就能进入有意义的状态。其中四个在这里有导览：
 
@@ -15,12 +15,13 @@ description: '可运行的 agent-bundle 示例：从 Skill 起步项目到完整
 | [MCP App](./mcp-app.mdx) | 一个生成的 stdio MCP 服务器，加上一个交互式 MCP App 资源。 | `pnpm example:mcp-app` |
 | [有声书策展器](./audiobook-curator.mdx) | 一个完整的路由树应用：MCP、投影出的 CLI、提供者与持久状态。 | `pnpm example:audiobook` |
 
-另外两个是进阶组合参考，由各自的 README 说明，这里不做导览：
+另外三个是进阶组合参考，由各自的 README 说明，这里不做导览：
 
 | 示例 | 证明什么 |
 | --- | --- |
 | [Worktree Proximity](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/worktree-proximity) | 一个根任务与两个位于关联 worktree 中的子智能体，通过持久通知协调。 |
 | [RSC Agent Runtime](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/rsc-agent-runtime) | 一个可选启用的架构实验：一个 RSC 运行时同时服务钩子、MCP 工具与 MCP App 时间线。不是公开 API。 |
+| [Host Test](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/host-test) | 一个探针插件，记录宿主投递的每个钩子负载与 MCP 调用，以及各自解析出的 `request.lineage`。它的 `probe:install` / `probe:capture` / `probe:uninstall` 脚本在隔离的 home 中驱动真实宿主；`probe:capture <host> --scenario <file.json>` 把一组有序提示作为一个多轮会话运行（Claude 使用 `claude -p --output-format stream-json`，后续轮次以 `--resume` 续接），并把模型自身的工具调用流保存在钩子日志旁。Workbench 导览不需要已登录的宿主；探针生命周期则需要。 |
 
 ## 如何运行
 
@@ -41,8 +42,8 @@ pnpm examples:check
 ```
 
 在仓库级 `pnpm build` 构建过本地 `agent-bundle` 工作区依赖之后，每个示例包也直接暴露同样的公开命令。每个示例都有
-`validate`、`build` 与 `check`；四个导览示例与 Worktree Proximity 还有 `dev`，而 RSC Agent Runtime 演示则通过其测试与
-`eval:hosts` 驱动：
+`validate`、`build` 与 `check`；四个导览示例、Worktree Proximity 与 Host Test 还有 `dev`，而 RSC Agent Runtime
+演示则通过其测试与 `eval:hosts` 驱动：
 
 ```sh
 cd examples/skills-starter