Merge remote-tracking branch 'origin/main' into feat/track-a-single-source-todo-task-class

Signed-off-by: song <22676124+songoow@users.noreply.github.com>

Author: songoow

docs/product/use-cases/README.md

@@ -7,3 +7,4 @@ They do not grant domain providers core control-plane authority.
 - [Issue and PR work](issue-pr/README.md)
 - [Cross-runtime implementation and review](cross-runtime/README.md)
 - [Office operations](office-operations/README.md)
+- [Steward: an owner sentence becomes a confirmed team](steward/README.md)

docs/product/use-cases/steward/README.md

@@ -0,0 +1,90 @@
+# Steward: An Owner Sentence Becomes A Confirmed Team
+
+Status: qualification case. It records what the local steward journey proves on
+the workspace today, which beats are still unproven, and how to reproduce both.
+It is product guidance, not a new capability, contract or scheduler.
+
+The case is grounded in one deterministic browser scenario
+(`examples/personal-workspace-browser/steward-journey.mjs`) that runs on synthetic
+data. The fixture substitutes the agent turn; everything the case describes is a
+fact the workspace surfaces render, not a claim about a live Goal.
+
+## When This Case Applies
+
+- an owner wants work to start from one sentence instead of a filled-in form;
+- the work needs more than one Agent or more than one lane, so staffing is
+  itself part of the answer;
+- the owner wants to keep confirming, correcting and reading results in one
+  place instead of relaying between Agent conversations.
+
+## The Journey
+
+| Beat | What the owner does | What the workspace shows | State |
+| --- | --- | --- | --- |
+| 1 | Looks at the first screen | Goal board lanes (needs you / running / observing / scheduled), each Goal card naming its Agent and its next sentence | Proven |
+| 2 | Asks the steward in the Goal conversation | The ask becomes an accepted Turn and the admitted team plan card lands in the same conversation | Proven |
+| 3 | Reads the card | Per lane: the Agent, the first bounded Todo with priority and action kind, the acceptance signal, and an explicitly unstaffed lane that keeps the work it did not staff; the quota envelope and stop condition; a statement that confirming is what creates the lanes | Proven |
+| 4 | Confirms | Exactly one apply and one durable write; the card reports that LoopX state will refresh | Proven, but see gap 2 |
+| 5 | Checks who can actually work | — | Gap 3 |
+| 6 | Corrects or pauses one lane | — | Gap 4 |
+| 7 | Waits for a lane to fail and asks who fixes it / judges completion | — | Gaps 5, 6 |
+
+Beats 5–7 are recorded by the scenario as typed gaps with the probe that looked
+for them. They are not "not implemented here" hand-waving: the scenario names
+the selectors and phrases it searched for and what it found instead.
+
+## Patterns
+
+1. **Ask for an outcome, not an org chart.** One sentence with the outcome and
+   the constraint produces a plan card; naming Agents before the outcome turns
+   coordination into the owner's job.
+2. **Read four facts before confirming.** Agent, first bounded Todo, acceptance
+   signal and staffing gap. A card that cannot show a gap is not yet reviewable.
+3. **Treat the gap lane as information, not failure.** An unstaffed lane keeps
+   the work it could not staff and names the reason, so the owner can decide to
+   drop it, staff it, or accept partial delivery.
+4. **Confirmation is a durable write.** Confirming sends exactly one apply and
+   performs one durable write; the surface must not claim a lane exists before
+   that write, and must say what the write produced afterwards.
+5. **Judge delivery by the returned result, not by the conversation.** A reply
+   or a message is not a completed lane. Until gap 6 closes, treat the
+   conversation as the request channel and the Goal's own state as the truth.
+6. **Correct in the conversation the work came from.** Steering an active run is
+   supported today; correcting a confirmed lane commitment is not yet, so avoid
+   confirming a plan whose lanes may need to be withdrawn.
+
+## Reproduce
+
+```sh
+# development surfaces
+LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \
+  node examples/personal-workspace-browser-smoke.mjs
+
+# packaged workspace bundle
+LOOPX_PERSONAL_WORKSPACE_PACKAGED=1 \
+LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \
+  node examples/personal-workspace-browser-smoke.mjs
+```
+
+The run writes `steward-journey-report.json` (beats, gaps, probe evidence) and
+per-beat screenshots under `output/playwright/personal-workspace/`, which is
+gitignored. No live Goal, Agent, credential or local path is read or captured.
+
+## Recorded Gaps And Owners
+
+| # | Gap | Evidence the scenario recorded | Owner surface |
+| --- | --- | --- | --- |
+| 1 | The steward's bounded prompt set (`找下一步` / `看阻塞` / `查证据`) is defined in the client model but not reachable from the conversation | probe: no steward-prompt element, no prompt phrases before the owner types | workspace composer |
+| 2 | A confirmed plan does not distinguish committed / partial / all-gap / stale / rejected per lane | probe: the only outcome sentence is the generic applied notice | steward plan commit (roadmap R1 remainder) |
+| 3 | No per-lane readiness ladder (registered → bound → launchable → executing) | probe: no lane-readiness element or phrase | steward readiness (roadmap R2 / audit F6) |
+| 4 | No lane-level correction (pause or supersede a confirmed commitment) | probe: no lane-correction element; only run steering exists | shared alignment (roadmap R4) |
+| 5 | A failed lane does not name its blocker owner and next step | probe: no lane-blocker element or phrase | recovery/continuation (roadmap R3) |
+| 6 | Completion is not judged by the lane's returned result | probe: no lane-return element or phrase | return delivery (roadmap R3) |
+
+## What This Case Does Not Claim
+
+- It does not qualify a live steward conversation: the fixture substitutes the
+  agent turn, so the model/runtime behind the intake stays untested here.
+- It does not qualify Lark audiences or any cloud/remote worker.
+- It does not turn a passing smoke into product acceptance for a Goal whose
+  plan was confirmed with real consequences.

docs/product/use-cases/steward/README.zh-CN.md

@@ -0,0 +1,66 @@
+# 管家：一句话变成一个被确认的团队
+
+状态：qualification 案例。它记录本机管家旅程今天在工作台面上证明了什么、哪几拍还没有证明，以及如何复现两者。它是产品侧使用说明，不是新能力、新契约或新调度器。
+
+本文案的事实来源是一个确定性的浏览器场景（`examples/personal-workspace-browser/steward-journey.mjs`），全部跑在合成数据上。fixture 顶替了 agent turn；本文描述的每一句都是工作台面渲染出来的事实，不是对某个真实 Goal 的断言。
+
+## 什么情况下适用
+
+- 老板想用一句话启动工作，而不是填表；
+- 这项工作需要不止一个 Agent 或不止一条 lane，所以“有没有人干”本身就是答案的一部分；
+- 老板想在同一个地方确认、纠偏、看结果，而不是在多个 Agent 会话之间来回转发。
+
+## 旅程七拍
+
+| 拍 | 老板做什么 | 界面显示什么 | 状态 |
+| --- | --- | --- | --- |
+| 1 | 看首屏 | Goal 看板四条 lane（需要你/执行中/观察中/已安排），每张 Goal 卡给出 Agent 与下一步那句话 | 已证明 |
+| 2 | 在 Goal 对话里向管家提要求 | 这句话成为一个被接受的 Turn，被准入的团队计划卡落在同一个对话里 | 已证明 |
+| 3 | 阅读计划卡 | 每条 lane 的 Agent、第一刀 Todo（含优先级与 action kind）、验收信号，以及一条明确“未配齐”并保留未派工工作的 lane；配额包络与停止条件；以及“确认才会建 lane”的说明 | 已证明 |
+| 4 | 确认 | 恰好一次 apply、一次 durable write；卡片提示 LoopX 状态将刷新 | 已证明，但见缺口 2 |
+| 5 | 检查到底谁能干活 | — | 缺口 3 |
+| 6 | 暂停或撤销某条 lane | — | 缺口 4 |
+| 7 | 等某条 lane 失败，问谁负责修 / 用什么判定完成 | — | 缺口 5、6 |
+
+第 5–7 拍由场景以 typed gap 记录，并带上“探针找过什么”的证据：不是“这里先不做”的一句话，而是列出了查找的选择器和文本、以及实际找到什么。
+
+## 推荐姿势
+
+1. **说要结果，不要点将。** 一句话给出结果与约束，让计划卡来回答“谁来做”；先点名 Agent 会把协调变成老板的活。
+2. **确认前先看四件事**：Agent、第一刀 bounded Todo、验收信号、缺人情况。看不到缺口的卡片还不具备可评审性。
+3. **缺人 lane 是信息，不是失败。** 未配齐的 lane 会保留它没能派出去的工作并给出原因，老板可以选择砍掉、补人、或接受部分交付。
+4. **确认是一次落地的 durable 写入。** 确认只发一次 apply、只做一次 durable write；卡片不能在写入前声称 lane 已存在，写入后必须说明产生了什么。
+5. **用回传结果判定交付，不要用对话判定。** 一条回复不等于一条 lane 完成。在缺口 6 关闭前，把对话当请求通道，把 Goal 自身状态当事实。
+6. **在产生工作的那个对话里纠偏。** 对运行中的 Turn 纠偏今天已支持；对已确认 lane 承诺的纠偏还没有，所以不要确认一张可能需要撤回 lane 的计划。
+
+## 如何复现
+
+```sh
+# 开发态台面
+LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \
+  node examples/personal-workspace-browser-smoke.mjs
+
+# 打包态工作台
+LOOPX_PERSONAL_WORKSPACE_PACKAGED=1 \
+LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \
+  node examples/personal-workspace-browser-smoke.mjs
+```
+
+运行会在 `output/playwright/personal-workspace/`（已 gitignore）下写出 `steward-journey-report.json`（拍子、缺口、探针证据）与每拍截图。不读取、不截取任何真实 Goal、Agent、凭证或本地路径。
+
+## 已记录缺口与归属
+
+| # | 缺口 | 场景记录的证据 | 归属面 |
+| --- | --- | --- | --- |
+| 1 | 管家快捷提示（找下一步 / 看阻塞 / 查证据）只定义在客户端模型里，对话里点不到 | 探针：老板输入前既无 steward-prompt 元素，也无提示文本 | 工作台输入区 |
+| 2 | 确认后不区分 committed / partial / all-gap / stale / rejected | 探针：只有一条通用的“已应用”提示 | 管家计划落地（roadmap R1 剩余项） |
+| 3 | 没有 per-lane readiness 阶梯（registered → bound → launchable → executing） | 探针：无 lane-readiness 元素或文本 | 管家 readiness（roadmap R2 / 审计 F6） |
+| 4 | 没有 lane 级纠偏（暂停或撤销已确认承诺） | 探针：无 lane-correction 元素；只有运行中 Turn 的纠偏 | shared alignment（roadmap R4） |
+| 5 | lane 失败后不说明阻塞归属与下一步 | 探针：无 lane-blocker 元素或文本 | 恢复与继续（roadmap R3） |
+| 6 | 不用 lane 的回传结果判定完成 | 探针：无 lane-return 元素或文本 | 交付回收（roadmap R3） |
+
+## 本文案不主张什么
+
+- 它不资格化真实管家对话：fixture 顶替了 agent turn，因此接入背后的模型/运行时在这里仍未测试；
+- 它不资格化飞书受众，也不资格化任何云端/远端 worker；
+- 它不把一条通过的 smoke 当成“某个真实确认过的 Goal 已被产品验收”。

examples/personal-workspace-browser-smoke.mjs

@@ -23,10 +23,11 @@ import {
 } from "./personal-workspace-browser/fixture.mjs";
 import { navigationSortingScenario } from "./personal-workspace-browser/navigation-sorting.mjs";
 import { progressiveLoadingScenario } from "./personal-workspace-browser/progressive-loading.mjs";
+import { stewardJourneyScenario } from "./personal-workspace-browser/steward-journey.mjs";
 import { teamPlanScenario } from "./personal-workspace-browser/team-plan.mjs";
 import { typedActionsScenario } from "./personal-workspace-browser/typed-actions.mjs";
 
-const scenarioCatalog = [navigationSortingScenario, chatRecoveryScenario, typedActionsScenario, teamPlanScenario, executionChipScenario, progressiveLoadingScenario];
+const scenarioCatalog = [navigationSortingScenario, chatRecoveryScenario, typedActionsScenario, teamPlanScenario, stewardJourneyScenario, executionChipScenario, progressiveLoadingScenario];
 const requestedScenario = process.env.LOOPX_PERSONAL_WORKSPACE_SCENARIO;
 const scenarios = requestedScenario
   ? scenarioCatalog.filter((scenario) => scenario.id === requestedScenario)

examples/personal-workspace-browser/execution-chip.mjs

@@ -94,6 +94,64 @@ async function chipText(page) {
   return (await page.locator(".personal-execution-chip").innerText()).replace(/\s+/g, " ").trim();
 }
 
+const pickerSelector = "div.personal-agent-select button.personal-select-trigger";
+
+async function readPickerLabel(page) {
+  return (await page.locator(pickerSelector).innerText()).replace(/\s+/g, " ").trim();
+}
+
+// What the page resolved, phrased so a failed CI run is diagnosable without a
+// local reproduction: the declared endpoint, the adapters the page actually
+// received and the label it rendered are the three facts that decide the label.
+async function pickerResolution(page) {
+  const capabilities = await page.evaluate(async () => {
+    try {
+      const response = await fetch("/api/chat/capabilities");
+      const body = await response.json();
+      return {
+        status: response.status,
+        declaredEndpoint: body.manager?.channel_binding?.executor_endpoint ?? null,
+        adapters: (body.adapters ?? []).map(
+          (adapter) => `${adapter.agent_id}:${adapter.available ? "available" : "unavailable"}`,
+        ),
+      };
+    } catch (error) {
+      return { status: "unavailable", declaredEndpoint: null, adapters: [], error: String(error) };
+    }
+  });
+  return [
+    `label=${await readPickerLabel(page)}`,
+    `declared=${capabilities.declaredEndpoint ?? "<none>"}`,
+    `adapters=[${capabilities.adapters.join(", ")}]`,
+    `capabilities=${capabilities.status}${capabilities.error ? ` (${capabilities.error})` : ""}`,
+  ].join(" ");
+}
+
+// The picker resolves from the same capabilities response that carries the
+// channel binding, and the execution chip only renders once that binding
+// lands. A single read therefore asserts on a state the page never promised was
+// settled, and it can still hold the pre-fetch Codex fallback. Wait for the
+// declared value instead, and name what the page really resolved if the wait
+// runs out.
+async function waitForPickerLabel(page, settled, timeoutMs = 15_000) {
+  const deadline = Date.now() + timeoutMs;
+  let label = await readPickerLabel(page);
+  while (!settled(label) && Date.now() < deadline) {
+    await page.waitForTimeout(100);
+    label = await readPickerLabel(page);
+  }
+  if (settled(label)) {
+    return label;
+  }
+  const resolution = await pickerResolution(page);
+  await page.screenshot({
+    animations: "disabled",
+    fullPage: false,
+    path: resolve(outputDir, "execution-chip-picker-unresolved.png"),
+  });
+  throw new Error(`Chat runtime picker never settled: ${resolution}`);
+}
+
 async function assertHairlineRow(page) {
   const headerBox = await page.locator(".personal-channel-header").boundingBox();
   const chipBox = await page.locator(".personal-execution-chip").boundingBox();
@@ -214,12 +272,10 @@ export const executionChipScenario = {
       collectCoverage,
     });
     try {
-      const pickerLabel = (await stewardPicker.page
-        .locator("div.personal-agent-select button.personal-select-trigger")
-        .innerText()).replace(/\s+/g, " ").trim();
-      if (!pickerLabel.includes("DeepSeek Harness (managed)")) {
-        throw new Error(`Chat runtime picker ignored the declared steward executor: ${pickerLabel}`);
-      }
+      const pickerLabel = await waitForPickerLabel(
+        stewardPicker.page,
+        (label) => label.includes("DeepSeek Harness (managed)"),
+      );
       if (pickerLabel.includes("Codex")) {
         throw new Error(`Chat runtime picker advertised a discovered CLI as the steward: ${pickerLabel}`);
       }
@@ -242,12 +298,9 @@ export const executionChipScenario = {
       collectCoverage,
     });
     try {
-      const pickerLabel = (await undeclaredSteward.page
-        .locator("div.personal-agent-select button.personal-select-trigger")
-        .innerText()).replace(/\s+/g, " ").trim();
-      if (pickerLabel !== "Chat Codex") {
-        throw new Error(`An undeclared steward executor no longer used the shipped default: ${pickerLabel}`);
-      }
+      // The shipped default is the settled value a machine with no declared
+      // steward executor must keep.
+      await waitForPickerLabel(undeclaredSteward.page, (label) => label === "Chat Codex");
     } finally {
       coverageEntries.push(...await undeclaredSteward.close());
     }