WIP: converge governed work inputs and packaged heartbeat consumers

CONTRIBUTING.md

@@ -189,6 +189,7 @@ touch, mention it in the PR instead of fixing it there.
 | `postgresql-integration.yml` | control-plane or npm lockfile paths | no | PostgreSQL authority store and service on a temporary instance |
 | `package-smoke.yml` | extension package paths | no | extension packages install, entrypoints, and example schemas |
 | `release-artifacts.yml` | `loopx/`, packaging, and lockfile paths | no | release identity and a release build from this source |
+| `runtime-snapshots.yml` | runtime artifact, installer, and updater paths | no | qualified, revision-addressed runtime archives and the main channel pointer |
 | `ark-turn.yml` | Turn driver and collaboration paths | no | optional Ark Turn package, stdio MCP, and DSH parity |
 | `memt-turn.yml` | optional MemT package, Turn driver, lock, and packaging paths | no | explicit optional dependency installation, complete adapter workflow, stdio MCP, and driver binding |
 | `dsh-plugin.yml` | DSH plugin and distribution workflow paths | no | Linux/Windows package install and uninstall, typed host contracts, and Linux real LoopX/web runtime admission |

README.md

@@ -23,19 +23,24 @@ A local-first [semantic control plane](https://loopx-project.github.io/loopx/blo
 
 ## Start in two steps
 
-With Python 3.11+ and Node.js 22.22.3+ (24 LTS recommended), install once:
+**1. Install LoopX and its Agent skills.** Requires Python 3.11+ and
+Node.js 22.22.3+ (24 LTS recommended).
 
 ```bash
 python3 -m pip install --upgrade loopx && loopx workflow-skills --install
 ```
 
-Restart your Agent host, open your project, then give Codex a concrete task:
+[Install options and upgrades](docs/guides/installing-loopx.md)
+
+**2. Give your Agent a concrete task.** Restart your Agent host, open your
+project, then send this in Codex:
 
 ```text
 $loopx speed up this project's slowest workflow; compare approaches and verify the gains
 ```
 
-Claude Code uses `/loopx <complex task>`. [Other hosts, install options and upgrades ↓](#try-loopx)
+Claude Code uses `/loopx <complex task>`; see [host setup](#start-from-your-agent)
+for other runtimes. Prefer a guided first run? [Choose a task below](#try-loopx).
 
 ## 📰 News
 
@@ -80,7 +85,7 @@ protected actions.
 
 | What you want to do | Start here |
 | --- | --- |
-| Keep a coding or research agent working across sessions | [Install and start](#try-loopx) |
+| Keep a coding or research agent working across sessions | [Install and start](#quick-start) |
 | Manage personal projects, schedules and decisions in one place | [Personal Agent Workspace](#meet-the-personal-agent-workspace) |
 | Let agents collaborate and deliver verifiable results | [Agent collaboration guide](docs/product/use-cases/cross-runtime/README.md) |
 
@@ -204,35 +209,34 @@ from this reproducible workspace. [Scenarios and replay instructions](demo/works
 
 ## Try LoopX
 
-Install once:
+Choose a walkthrough with a result you can inspect:
 
-```bash
-python3 -m pip install --upgrade loopx && loopx workflow-skills --install
-```
+| Start with | What you'll do |
+| --- | --- |
+| [Your first bug-fixing loop](docs/guides/first-bugfix-loop.md) | Reproduce two bugs in a small Python project, let the Agent fix them, then check the tests and patch. |
+| [Long-running coding work](docs/guides/long-running-coding-agents.md) | Fix an issue or keep improving your own repository, with review, evidence and recovery across sessions. |
+| [Personal Agent Workspace (中文)](docs/guides/personal-workspace-user-guide.md) | Follow the illustrated guide to manage projects, conversations, tasks and delivered results in the App. |
 
 ### Start From Your Agent
 
-Restart your Agent host, then start from a session opened on your project:
+After the [two-step setup](#quick-start), use the entry for your host in a
+session opened on your project:
 
-| Host | Type |
+| Host | Start and confirm continuation |
 | --- | --- |
-| Codex App, Codex CLI | `$loopx <complex task>` |
-| Claude Code | `/loopx <complex task>` |
+| Codex App | `$loopx <complex task>`; confirm the [heartbeat automation is saved](docs/guides/first-bugfix-loop.md#confirm-that-it-actually-started). |
+| Codex CLI | `$loopx <complex task>`; activate the generated [native `/goal`](docs/product/runtimes/codex-cli/codex-cli-packaged-install.md#current-user-path) in the same session. |
+| Claude Code | `/loopx <complex task>`; follow the [loop driver setup](docs/guides/newcomer-command-path.md#choose-the-loop-driver) for recurring work. |
 | DeepSeek Harness | Install the [native DSH plugin](packages/dsh-loopx-plugin/README.md), select the `loopx` skill, then describe the task |
 
-For example, give your Agent a concrete outcome:
-
-```text
-$loopx speed up this project's slowest workflow; compare approaches and verify the gains
-```
-
 LoopX reuses existing project state or connects the project, plans the work as
-Todos and sets up the host's loop. `loopx status` shows the goal, any decision
-waiting for you and the next Todo; `loopx doctor` diagnoses the install.
+Todos and guides host activation. Ask your Agent to confirm the active Goal,
+next Todo and continuation mechanism; a setup packet alone is not an active loop.
+Keep the host available for continued work. `loopx status` shows the Goal,
+decisions waiting for you and the next Todo; `loopx doctor` diagnoses the install.
 
-Requires Python 3.11+ and Node.js 22.22.3+ (24 LTS recommended).
-[Installing LoopX](docs/guides/installing-loopx.md) covers native Windows,
-`pipx`, upgrades, rollback and uninstall.
+[Installing LoopX](docs/guides/installing-loopx.md) covers native Windows, `pipx`,
+upgrades, rollback and uninstall.
 
 **Upgrading from 1.x?** Read the [2.0 migration and recovery guide](docs/product/releases/v2.0.0.md) before continuing existing Goals.
 

README.zh-CN.md

@@ -23,19 +23,22 @@
 
 ## 两步开始
 
-准备好 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS），安装一次：
+**1. 安装 LoopX 和 Agent 技能。** 需要 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS）。
 
 ```bash
 python3 -m pip install --upgrade loopx && loopx workflow-skills --install
 ```
 
-重启 Agent 宿主，打开项目，再给 Codex 一个具体任务：
+[其他安装方式与升级说明](docs/guides/installing-loopx.md)
+
+**2. 给 Agent 一个具体任务。** 重启 Agent 宿主，打开项目，再在 Codex 对话中输入：
 
 ```text
 $loopx 优化这个项目最慢的流程，对比方案并验证性能提升
 ```
 
-Claude Code 使用 `/loopx <复杂任务>`。[其他宿主、安装方式与升级说明 ↓](#试用-loopx)
+Claude Code 使用 `/loopx <复杂任务>`；其他运行时见[宿主接入](#从你已经在用的-agent-启动)。
+想跟着教程试一次？[选择一个入门任务](#试用-loopx)。
 
 ## 📰 最新动态
 
@@ -72,7 +75,7 @@ Claude Code 使用 `/loopx <复杂任务>`。[其他宿主、安装方式与升
 
 | 你想做什么 | 从这里开始 |
 | --- | --- |
-| 让编程或研究 Agent 跨会话持续干活 | [安装并开始](#试用-loopx) |
+| 让编程或研究 Agent 跨会话持续干活 | [安装并开始](#快速开始) |
 | 在一个入口管理个人项目、定时任务与待决事项 | [个人 Agent 工作区](#认识个人-agent-工作区) |
 | 让多个 Agent 分工协作，交付可验收的结果 | [Agent 协作指南](docs/product/use-cases/cross-runtime/README.md#中文指南) |
 
@@ -178,33 +181,31 @@ App 为 ad-hoc 签名，尚未 notarize。Windows 预览版目前手动更新，
 
 ## 试用 LoopX
 
-先安装一次：
+选一个能检查实际成果的教程：
 
-```bash
-python3 -m pip install --upgrade loopx && loopx workflow-skills --install
-```
+| 从哪里开始 | 你会完成什么 |
+| --- | --- |
+| [查 bug 入门教程](docs/guides/first-bugfix-loop.zh-CN.md) | 在小型 Python 项目中复现两个 bug，让 Agent 修复，再检查测试和补丁。 |
+| [长程编程任务指南（English）](docs/guides/long-running-coding-agents.md) | 修复 issue 或持续改进自己的仓库，保留评审、证据和跨会话恢复。 |
+| [图文工作区手册](docs/guides/personal-workspace-user-guide.md) | 跟着截图在 App 中管理项目、对话、任务和交付结果。 |
 
 ### 从你已经在用的 Agent 启动
 
-重启 Agent 宿主，在打开了你项目的会话里开始：
+完成上面的[两步启动](#快速开始)后，在打开了你项目的会话里使用对应入口：
 
-| 宿主 | 输入 |
+| 宿主 | 启动并确认续跑 |
 | --- | --- |
-| Codex App、Codex CLI | `$loopx <复杂任务>` |
-| Claude Code | `/loopx <复杂任务>` |
+| Codex App | `$loopx <复杂任务>`；确认 [heartbeat 自动化已保存](docs/guides/first-bugfix-loop.zh-CN.md#确认它真的开始执行)。 |
+| Codex CLI | `$loopx <复杂任务>`；在同一会话中激活生成的[原生 `/goal`](docs/product/runtimes/codex-cli/codex-cli-packaged-install.md#current-user-path)。 |
+| Claude Code | `/loopx <复杂任务>`；按 [loop driver 接入说明](docs/guides/newcomer-command-path.md#choose-the-loop-driver)设置周期性续跑。 |
 | DeepSeek Harness | 安装 [DSH 原生 Plugin](packages/dsh-loopx-plugin/README.md)，在技能选择器中选 `loopx`，然后直接描述任务 |
 
-例如，给 Agent 一个具体成果要求：
-
-```text
-$loopx 优化这个项目最慢的流程，对比方案并验证性能提升
-```
-
-LoopX 会复用项目已有状态或连接项目，把工作规划成 Todo，并设置宿主的循环。
-`loopx status` 显示目标、等你处理的决策和下一条 Todo；`loopx doctor` 诊断安装。
+LoopX 会复用项目已有状态或连接项目，把工作规划成 Todo，并引导宿主激活。
+让 Agent 回报当前 Goal、下一条 Todo 和实际续跑机制；生成 setup packet 不等于循环已经启动。
+持续工作需要宿主保持可用。`loopx status` 显示目标、等你处理的决策和下一条 Todo；
+`loopx doctor` 诊断安装。
 
-需要 Python 3.11+ 与 Node.js 22.22.3+（推荐 24 LTS）。原生 Windows、`pipx`、
-升级、回滚与卸载见 [Installing LoopX](docs/guides/installing-loopx.md)。
+原生 Windows、`pipx`、升级、回滚与卸载见[安装指南](docs/guides/installing-loopx.md)。
 
 **从 1.x 升级？** 继续既有 Goal 前，先读 [2.0 迁移与恢复指南](docs/product/releases/v2.0.0.md#中文指南)。
 

apps/presentation/dashboard/smoke/delegation-search-browser-smoke.mjs

@@ -86,6 +86,22 @@ try {
     await page.screenshot({path: resolve(output, 'read-failure.png')});
     await fixture('recover'); await dialog.getByRole('button', {name: '重试', exact: true}).click(); await settled();
     await rows(4);
+    await fixture('local-source-unavailable');
+    const denied = await fetch(`${ready.origin}/api/chat/request-inventory?session_id=${ready.session_id}`);
+    assert.equal(denied.status, 400);
+    assert.equal((await denied.json()).error_code, 'request_inventory_unavailable');
+    await dialog.getByRole('button', {name: '刷新委派', exact: true}).click(); await settled();
+    await dialog.getByRole('alert').waitFor(); await rows(0);
+    assert.equal(await trigger.getAttribute('aria-label'), '委派，— 条待跟进');
+    assert.equal(await dialog.locator('.conversation-requests-pagination').count(), 0);
+    // Changing the filter must not turn the same missing source into a new
+    // empty workspace, nor may an unsuccessful retry lose that distinction.
+    await search('builder'); await settled(); await dialog.getByRole('alert').waitFor();
+    await dialog.getByRole('button', {name: '重试', exact: true}).click(); await settled();
+    await dialog.getByRole('alert').waitFor(); await rows(0);
+    await fixture('local-source-recover');
+    await dialog.getByRole('button', {name: '重试', exact: true}).click(); await settled(); await rows(9);
+    await search('reviewer'); await rows(4);
     assert.equal((await fixture('inspect')).source_unchanged, true);
     await fixture('deliver'); await search('复核迁移说明中的示例'); await settled();
     await dialog.getByText('未找到匹配的委派。', {exact: true}).waitFor();
@@ -126,9 +142,20 @@ try {
     await fixture('source-recover'); await page.getByRole('button', {name: 'Retry history', exact: true}).click();
     await page.getByRole('button', {name: /Delegations,.*awaiting follow-up/}).click();
     await page.getByRole('searchbox', {name: 'Search delegations'}).waitFor();
+    const english = page.getByRole('dialog', {name: 'Delegations', exact: true});
+    await english.getByRole('button', {name: 'All records', exact: true}).click(); await rows(12);
+    // A real return changes ordering and the snapshot while More is reading.
+    // Rebuild from the beginning, but fulfill this click's requested extent;
+    // the parent message refresh must not replace it with the old page count.
+    await fixture('report-window');
+    const nextPage = english.getByRole('button', {name: 'More records', exact: true});
+    await nextPage.focus(); await page.keyboard.press('Enter'); await rows(13);
+    assert.equal(await english.getByRole('button', {name: 'More records', exact: true}).count(), 0);
+    assert.equal(await page.evaluate(() => document.activeElement?.textContent), '13 / 13 shown');
+    await english.getByRole('button', {name: 'Awaiting follow-up', exact: true}).click(); await rows(11);
     assert.equal(writes.some(path => /request-(?:inventory|control)|team-work/.test(path)), false);
     assert.deepEqual(errors, []);
-    console.log('PASS: packaged search, pre-pagination match, count, original conversation, clear/paging, failure/retry, returned history, stale response, Escape/focus, workspace isolation, narrow layout, English, source refusal/recovery and read-only receipts.');
+    console.log('PASS: packaged search, pre-pagination match, count, original conversation, clear/paging, failure/retry, returned history, stale response, Escape/focus, workspace isolation, narrow layout, English, source refusal/recovery, changed-snapshot More and read-only receipts.');
   }
 } catch (error) {
   if (page) {await page.screenshot({path: resolve(output, 'failure.png')}).catch(() => {}); await writeFile(resolve(output, 'failure.txt'), await page.locator('body').innerText());}

apps/presentation/dashboard/src/data/conversation-requests.ts

@@ -21,8 +21,9 @@ const inventorySchema = z.object({ok: z.literal(true), session_id: z.string(), r
 export type ConversationRequest = z.infer<typeof rowSchema>;
 export type ConversationRequestInventory = z.infer<typeof inventorySchema>;
 
-export async function fetchConversationRequests(sessionId: string, history: boolean, offset = 0, signal?: AbortSignal, search = "") {
+export async function fetchConversationRequests(sessionId: string, history: boolean, offset = 0, signal?: AbortSignal, search = "", limit = 12) {
   const query = new URLSearchParams({session_id: sessionId, view: history ? "history" : "unfinished", offset: String(offset), search});
+  if (limit !== 12) query.set("limit", String(limit));
   const result = inventorySchema.parse(await requestJson<unknown>(`/api/chat/request-inventory?${query}`, {signal}));
   if (result.session_id !== sessionId) throw new Error("Conversation request scope changed.");
   return result;