pi-onlyne 1.1.2 → 1.2.0

package/README.md

@@ -9,7 +9,7 @@ length-prefixed JSON codec, and the runtime has no npm dependencies.
 
 Outside an onlyne session the extension is inert. The client injects `ONLYNE_ROLE`,
 `ONLYNE_SESSION_ID` and `ONLYNE_TASK_ID` into every process it spawns
-(`crates/onlyne-client/src/dispatch.rs`). With any of the three missing, this is an
+(`crates/onlyne-client/src/session/dispatch.rs`). With any of the three missing, this is an
 ordinary pi session: the plugin registers nothing and opens nothing.
 
 ```
@@ -25,8 +25,10 @@ hello{protocol:1, plugin:"pi-onlyne", kind:"agent", capabilities:[…], mount:{r
   ├─ task text (+ image path) ──► pi user message (deliverAs:"followUp")
   ├─ assign_ack{accepted:true}
   ├─ report.heartbeat{running|idle} — per turn, and every 10s while a task is live
+  ├─ a turn that ends without `onlyne_complete` ──► the idle ladder: the same
+  │    message again (at most `idleReminders` times), then `failed` and out
   ├─ report.complete{outcome, head} — the ledger's terminal fact
-  │    └─ then one report.heartbeat{agent:"idle"} carrying the settled tuple
+  │    └─ then one report.heartbeat{agent:"idle"} stating the agent only
   │       └─ the client's answer is the handover: pi is asked to shut down, then detaches
   ├─ probe ──► one heartbeat
   ◀── recycle ──► complete (if unsettled) → stop → pi exits
@@ -102,9 +104,10 @@ pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 | --- | --- | --- |
 | `enabled` | `true` | `false` turns the extension off for this workspace |
 | `watch.autoStart` | `true` | `false` registers the tools but opens no socket until `/onlyne connect` |
+| `idleReminders` | `2` | how many times an idle turn end re-sends the assignment before the task fails (§4); 0 means the first idle without a completion fails it |
 
-A missing file means both defaults. A malformed file prints one warning on stderr and
-keeps both defaults: a typo must not silently disable a role. The client does not read
+A missing file means every default. A malformed file prints one warning on stderr and
+keeps the defaults: a typo must not silently disable a role. The client does not read
 this file (§11 of the plan downgraded the old readiness gates to generate-time template
 advice), so only this extension consumes it; the key shape stays the one the templates
 carry.
@@ -154,7 +157,8 @@ png/jpeg/gif/webp file: the plugin reads it, base64-encodes it and attaches it a
 
 ### `onlyne_complete{outcome?, text?, force?, reason?}`
 
-Ends the current task with an explicit outcome (`done` by default, or `failed`). A
+Ends the current task with an explicit outcome (`done` by default, or `failed`). It is the
+only path to `done`: a turn that ends without it is reminded and then failed (§4). A
 non-empty `text` becomes the ledger `head` verbatim: whitespace collapses to one line and
 the text stops at 200 characters. An absent or blank `text` carries no summary, so the
 completion falls back to the last assistant text. The call also ends the session's
@@ -163,28 +167,52 @@ pi to shut down through `ctx.shutdown()`. pi 0.85.1 has no tool-result `terminat
 handling. When the workspace carries a relay policy (§5), `force: true` with a non-empty
 `reason` is the deliberate way past a handoff the session still owes.
 
+### `onlyne_handoff{to, text, image?}`
+
+Hands this session's task on to the next hop of its family. The plugin sends one `handoff`
+frame naming the task the session currently holds, and the host mints one child task for
+`to` under it: the child names this task as its `parent_task`, sits one hop further along,
+and carries the same family id, hop budget, origin, deadline and labels. The tool's result
+names the child task id and its hop. A client refusal comes back as the tool's error,
+verbatim. `image` is the same absolute png/jpeg/gif/webp path the send tool takes. An
+assignment whose causality names a hop budget states the hop and the budget in its
+injected header line. `onlyne_send{kind: "task"}` is the other way to reach a role: that
+envelope starts a family of its own at hop 0.
+
 ## 4. Outcome rules
 
-The plugin sends one completion per task, at the first of these events:
-
-1. **`onlyne_complete`** — the model gives an explicit outcome. It wins over everything
-   else, and a later completion for the same task is refused (not re-reported). Its
-   non-empty `text` is the head.
-2. **`agent_settled`** — pi will not continue on its own: no retry, compaction or queued
-   continuation is pending. The plugin reports:
-   - `failed` when the turn ended with a provider error (`stopReason: "error"`), with the
-     error as the head;
-   - `done` otherwise, with the last assistant text as the head;
-   - nothing at all when the task was assigned but no turn has run yet. The injected
-     message has not executed, so completing now would claim work that never happened.
-3. **`recycle{outcome}`** — the host is tearing the session down. The plugin settles an
+`onlyne_complete` is the only path to `done`. The plugin sends one completion per task,
+at the first of these events:
+
+1. **`onlyne_complete`** — the model gives an explicit outcome (`done` by default, or
+   `failed` / `cancelled`). A later completion for the same task is refused (not
+   re-reported). Its non-empty `text` is the head.
+2. **An errored turn** — the turn ended with a provider error (`stopReason: "error"`).
+   That is proof on its own, so the plugin reports `failed` at once, with the error as
+   the head.
+3. **The idle ladder** — the turn ended cleanly without a completion, and the task is
+   still open. The plugin re-sends the assignment and counts the rung. The idle that
+   finds the bound `idleReminders` names already spent reports `failed` — head
+   `no completion after <n> idle reminders` — and the session exits the way any
+   completion makes it exit.
+4. **`recycle{outcome}`** — the host is tearing the session down. The plugin settles an
    unsettled task with the host's outcome first, then stops and exits pi.
 
+Two things settle nothing: a task that was assigned but whose turn has not run yet (the
+injected message has not executed, so completing now would claim work that never
+happened), and an idle the ladder still has a rung for. The ladder re-sends the
+assignment the task arrived with — the same header, task text and attachment paths the
+injection carried, under one line saying the previous turn ended without a completion —
+and never the role prose, which is already in the session's context. Its images are not
+re-attached: the paths travel as text, so the same bytes are not put into the context
+twice. A new envelope for the same task restarts the count.
+
 `head` is a single line, capped at 200 characters; it matches what the client puts in
 `out_head` and what the receipt carries. Each task has one source for it: the `text` of
-the explicit `onlyne_complete` call when that call carried one, and the last assistant
-text otherwise. The auto rule is that fallback path: it reports the text of the turn it
-settles, and a sentence spoken after the call cannot replace what the call handed over.
+the explicit `onlyne_complete` call when that call carried one, the error a failed turn
+reported, or the ladder's own line. The last assistant text is the fallback for an
+`onlyne_complete` call that carried no text at all — a sentence spoken after such a call
+cannot replace what the call handed over, and nothing else reads it.
 
 A reported completion ends the session's process. `report.complete` goes out as a request,
 and the client answers it only after it has settled the session row, acked the delivery
@@ -193,7 +221,7 @@ outcome the socket could not carry is queued and flushed after the next `hello`,
 flush's answer is the handover that ends the process. A completion the host refused leaves
 the process running, so an exit never loses the task.
 
-The last report is one observation with `agent: "idle"` beside the settled outcome, sent
+The last report is one observation with `agent: "idle"`, sent
 after the completion is acknowledged and before the process leaves. The completion settles
 the row from the tuple the client holds, and that tuple still reads `running` when the
 finishing turn was the last heartbeat. Nothing observes the process afterwards, so without
@@ -253,7 +281,7 @@ file its turn.
 | scope | this session's own sends, in process memory: a reconnect keeps them, a restarted session starts empty rather than guessing at what an earlier process sent |
 | waiver | `force: true` with a non-empty `reason`; it only matters when the guard refuses |
 | audit | a waived completion's ledger head starts with `relay-guard-forced: <reason>`, followed by the model's `text` when the call carried one |
-| not guarded | the automatic outcomes: `agent_settled` and `recycle{outcome}` still complete a task that owes a handoff |
+| not guarded | outcomes the plugin reports without the model: an errored turn, the idle ladder's failure, and `recycle{outcome}` |
 
 `relay.toml` is a closed subset of TOML: flat `key = value` lines, the two keys above,
 one-line arrays of double-quoted strings, `#` comments. Anything outside that warns on
@@ -271,18 +299,22 @@ the shipped client.
 - **Report sequence base.** The plugin's own `report` sequence starts at 1000, not 1. The
   client stamps its own dispatch events (`created`, resource attach, `ready`) into the
   same `(generation, seq)` watermark, and the reducer silently drops any report at or
-  below it (`crates/onlyne-session/src/reconcile.rs`). A plugin sequence starting at 1
+  below it (`crates/onlyne-session/src/reconcile/`). A plugin sequence starting at 1
   would lose its first observations. Everything else about the versioning is per spec.
-- **`observed` is a full `Observation`.** `report.heartbeat` carries the whole legal state
+- **`observed` is a full `Observation`.** `report.heartbeat` carries the state
   tuple (`version`, `generation_live`, `isolate_after`, `terminate_after`,
-  `mismatch_count`, `agent`, `delivery`, `resource`, `recovery`, `outcome`, `public`), not
-  a `{"state": "running"}` shorthand: the host deserialises it and rejects anything
-  `is_legal` refuses. This plugin owns only the `agent` dimension (turn hooks). It leaves
-  `delivery` at `none` and `outcome` at `pending`, which is its own truth until it reports
-  a completion. It reports `resource` as `attached` because the host's own dispatch path
-  already recorded the attach.
+  `mismatch_count`, `agent`, `delivery`, `resource`, `recovery`), not
+  a `{"state": "running"}` shorthand: the host deserialises it, overwrites the six
+  keys the client owns, and applies only a tuple `is_legal` accepts. This plugin owns the `agent` dimension (turn hooks), the
+  `resource` claim — its process is live in the pane the attach was recorded on —
+  and the `host` binding. It has no witness for `delivery`, `recovery`,
+  `generation_live`, `isolate_after`, `terminate_after` or `mismatch_count`: the
+  client rewrites all six from its own intent queue, reducer history and role
+  config before the tuple is applied, so whatever this plugin sends there is
+  never read. Neither a
+  task outcome nor a public view travels in a tuple at all.
 - **`ready` is reported once per connection.** The host's own hand-off path
-  (`crates/onlyne-client/src/dispatch.rs::hand_session`) already reports `ready` when the
+  (`crates/onlyne-client/src/session/dispatch/delivery.rs::hand_session`) already reports `ready` when the
   client stages the session for a mounting plugin, so a second report from the plugin is a
   no-op at the host. The plugin sends it anyway: a plugin that mounts *before* any work
   exists is the case the ready barrier names, and it costs one frame.
@@ -354,12 +386,12 @@ path the client's daemon bound, read when the environment carried none, §8).
 | `reconnecting in 4000ms` in a loop | the client is down or the socket was replaced | `onlyne --server-root … roles` |
 | `ready refused: internal: unknown session for …` | the plugin mounted and reported for a task the client never staged (normal when pi is started by hand outside a task) | start pi under the client, not by hand |
 | `assign` never arrives | the client's `session_command` did not spawn pi, or `inject` was dropped | the client log for the spawn line; `/onlyne status` for the capability set |
-| ledger stays `in_flight` | no completion was reported: no turn ran, or `agent_settled` never fired | the pi session file for `onlyne-assign` / `onlyne-complete` entries |
+| ledger stays `in_flight` | no completion yet: no turn has run (the injected message has not executed), or the ladder is still reminding it (`idleReminders`) | the pi session file for the `onlyne-assign` entry and the reminders injected after it; the `onlyne` panel for `reminder n of m`; `/onlyne status` for the task and phase |
 | `onlyne_complete` answers `relay guard: missing handoff to: …` | the workspace's spec (or a `relay.toml` standing in for it) names a role this session never sent to | routine notices appear in the `onlyne` panel; stderr keeps refusals such as `relay guard from …`, socket errors, timeouts and framing faults; `required=…` names the policy; `relay guard: missing handoff …` names the delivered set |
 | `hello … forbidden` / connection closed right after `hello` | the mount role does not match the client's role | `hello.args.mount.role` vs the workspace's role |
 | `frame_too_large` | a body above 8 MiB | only reachable through an oversize outbound image; the ceiling is the core's |
 | tools missing | `pi.registerTool` is absent in that pi version | `/onlyne status`; the capability table above |
-| session reads `idle` again after `exited` | a heartbeat snapshot landed after the completion, carrying `outcome: pending` | the session log for the report order after `completion`; the plugin stops reporting for a completed task |
+| session reads `idle` again after `exited` | a turn-end heartbeat landed after the completion, moving the agent dimension back | the session log for the report order after `completion`; the plugin stops reporting for a completed task, and the client's own `delivery` survives either way |
 | the supervisor board lists no tabs | no live session reported a pane: the adapter predates the report, or this pi is not inside an Orca pane | `onlyne --server-root … sessions --json` for `projection.observed.host.orca.pane_key`; `env \| grep ORCA_` inside the pane |
 
 `/onlyne status` prints the live state (`connected`, `socket`, `role`, `sessionId`,

package/README.zh.md

@@ -6,7 +6,7 @@
 `node:net` 上重写，四字节大端长度前缀加 UTF-8 JSON 的编解码是手写的，运行时零 npm 依赖。
 
 扩展在 onlyne 之外完全静默。客户端 spawn 进程时会注入 `ONLYNE_ROLE`、`ONLYNE_SESSION_ID`、
-`ONLYNE_TASK_ID`（`crates/onlyne-client/src/dispatch.rs`）；三者缺一，就是普通 pi session，
+`ONLYNE_TASK_ID`（`crates/onlyne-client/src/session/dispatch.rs`）；三者缺一，就是普通 pi session，
 插件不注册任何工具、不打开任何 socket。
 
 ```
@@ -22,6 +22,8 @@ hello{protocol:1, plugin:"pi-onlyne", kind:"agent", capabilities:[…], mount:{r
   ├─ 任务文本（含图片路径）──► pi user message（deliverAs:"followUp"）
   ├─ assign_ack{accepted:true}
   ├─ report.heartbeat{running|idle} —— 每个 turn，以及任务存续期间每 10 秒
+  ├─ turn 结束却没有 `onlyne_complete` ──► idle 阶梯：同一条消息再注入
+  │    （最多 `idleReminders` 次），之后 `failed` 并退出
   ├─ report.complete{outcome, head} —— ledger 的终态事实
   │    └─ client 的应答就是交接点：插件据此让 pi 退出，随后 detach
   ├─ probe ──► 一条 heartbeat
@@ -95,8 +97,9 @@ pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 | --- | --- | --- |
 | `enabled` | `true` | `false` 时该工作区禁用扩展 |
 | `watch.autoStart` | `true` | `false` 时注册工具但不建连接，需 `/onlyne connect` |
+| `idleReminders` | `2` | turn 结束却空闲时重发任务的次数上限（§4）；`0` 表示第一次空闲就判失败 |
 
-文件缺失即两个默认值。文件格式错误时打印一行警告，并保留默认值：一个笔误不该静默关掉一个
+文件缺失即取各自默认值。文件格式错误时打印一行警告，并保留默认值：一个笔误不该静默关掉一个
 role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为 generate 期模板提示），所以
 只有本扩展消费它；键名沿用模板里既有的形状。
 
@@ -143,37 +146,53 @@ png/jpeg/gif/webp 的绝对路径：插件读出内容，base64 编码后挂成
 
 ### `onlyne_complete{outcome?, text?, force?, reason?}`
 
-显式结束当前任务，`outcome` 缺省 `done`，也可 `failed`。`text` 非空时就是 ledger 的 `head`，
+显式结束当前任务，`outcome` 缺省 `done`，也可 `failed`。它是通向 `done` 的唯一路径：turn 结束时
+没有这次调用，任务会被重发提醒，之后判失败（§4）。`text` 非空时就是 ledger 的 `head`，
 原样写出：空白折叠成单行，截到 200 字符。`text` 缺失或全空白时不带摘要，completion 退回
 最后一段 assistant 文本。这一调用同时结束所在 session 的进程。client 应答完 completion
 报告（见 §4）之后，插件通过 `ctx.shutdown()` 让 pi 退出。pi 0.85.1 没有 tool-result
 `terminate` 处理。工作区带接力策略（§5）时，`force: true` 加非空 `reason` 是绕过一个仍欠着的
 接力的正规通道。
 
+### `onlyne_handoff{to, text, image?}`
+
+把本会话手上的任务交给家族的下一跳。插件发一个 `handoff` 帧，帧里点名本会话当前持有的任务，
+宿主据此为 `to` 铸一个该家族的子任务：子任务把本任务记为 `parent_task`，hop 加一，家族 id、
+hop 预算、origin、deadline 与 labels 一并随行。工具结果给出子任务 id 与它的 hop。client 拒绝时
+以工具错误原样抛出。`image` 与 send 工具同一含义：png/jpeg/gif/webp 图片的绝对路径。家族带
+hop 预算时，注入的标题行写明 hop 与预算。`onlyne_send{kind: "task"}` 是触达 role 的另一条路：
+那条 envelope 开一个新家族，hop 从 0 起。
+
 ## 4. outcome 判定规则
 
-插件每个任务只发一次 completion，取以下三者的先到者：
+`onlyne_complete` 是通向 `done` 的唯一路径。插件每个任务只发一次 completion，取以下四者的先到者：
 
-1. **`onlyne_complete`** —— 模型给显式 outcome，优先级最高；同一任务的第二次 completion 被
-   拒（不重报）。`text` 非空时即 head，原样写出。
-2. **`agent_settled`** —— pi 不会自己继续：没有待重试、待压缩或排队续跑。此时：
-   - turn 以 provider 错误告终（`stopReason: "error"`）→ `failed`，错误信息当 head；
-   - 其余 → `done`，最后一段 assistant 文本当 head；
-   - 任务已投递但还没跑过任何 turn → 不发 completion。注入的消息尚未执行，这时报终态就是撒谎。
-3. **`recycle{outcome}`** —— 宿主拆 session。插件先按宿主给的 outcome 结算未终态的任务，再停
+1. **`onlyne_complete`** —— 模型给显式 outcome（缺省 `done`，也可 `failed` / `cancelled`）。同一
+   任务的第二次 completion 被拒（不重报）。`text` 非空时即 head，原样写出。
+2. **turn 出错** —— turn 以 provider 错误告终（`stopReason: "error"`）。这本身就是证据，插件立即
+   报 `failed`，错误信息当 head。
+3. **idle 阶梯** —— turn 干净结束却没有 completion，任务还开着。插件重发任务并记一次；当空闲发现
+   `idleReminders` 给的次数已经用完，就报 `failed`（head 为 `no completion after <n> idle
+   reminders`），并像任何一次 completion 一样退出 session。
+4. **`recycle{outcome}`** —— 宿主拆 session。插件先按宿主给的 outcome 结算未终态的任务，再停
    插件并退出 pi。
 
-`head` 恒为单行、上限 200 字符，与 client 写入 `out_head` 和回执携带的内容一致。每个任务的
-head 只有一个来源：显式 `onlyne_complete` 带的 `text`（有则原样采用），否则是最后一段
-assistant 文本。自动规则就是那条退路：它报的是自己那一轮的文字，工具调用之后再说的话，顶不掉
-调用交出的内容。
+两种情况都不结算：任务已投递但还没跑过任何 turn（注入的消息尚未执行，这时报终态就是撒谎），
+以及阶梯还有余额的那次空闲。阶梯重发的是任务到手时的那条消息——同样的头部、任务文本和附件路径，
+外加一行说明上一轮没有 completion——但不重发 role prose，它已经在上下文里；图片也不重挂，
+路径以文本出现，同样的字节不会进上下文两次。同一任务收到新 envelope 时计数重来。
+
+`head` 恒为单行、上限 200 字符，与 client 写入 `out_head` 和回执携带的内容一致。每个任务的 head
+只有一个来源：显式 `onlyne_complete` 带的 `text`（有则原样采用）、出错 turn 报的错误，或阶梯自己
+的那一行。最后一段 assistant 文本只是 `text` 完全缺失的 `onlyne_complete` 的退路——调用之后再说
+的话顶不掉调用交出的内容，此外没有任何东西读它。
 
 报出去的 completion 会结束所在 session 的进程。`report.complete` 以请求形式发出，client 只有
 在结算 session 行、ack 掉投递、并写好 `Completion` envelope 之后才应答，插件就在这个应答处
 让 pi 退出。socket 当时送不出去的 outcome 会被记住，并在下一次 `hello` 后补发，那次补发的
 应答就是结束进程的交接点。被宿主拒掉的 completion 不会让进程退出，任务不会因为退出而丢失。
 
-最后一条上报是：在已结算的 outcome 旁边带一个 `agent: "idle"` 的观测，发在 completion 被
+最后一条上报只说 agent 这一维：`agent: "idle"` 的观测，发在 completion 被
 ack 之后、进程退出之前。completion 是按 client 手里的元组结算 session 行的，而收尾那一轮
 就是最后一次 heartbeat 时，这个元组读到的仍是 `running`；此后没有任何东西再观测这个进程，
 所以缺了这条上报，已退出的 session 会一直说 `running`。最后一次心跳本来就是 idle 时，插件
@@ -224,7 +243,7 @@ stderr 告警并忽略，把机会让回文件。
 | 作用域 | 本会话自己的投递，仅进程内存：重连不丢，会话重启从空开始，不去猜上一个进程发过什么 |
 | 豁免 | `force: true` 加非空 `reason`；只在守卫拒绝时才起作用 |
 | 审计 | 被豁免的 completion，ledger head 以 `relay-guard-forced: <reason>` 开头；调用带了 `text` 时紧接其后 |
-| 不管的路 | 自动终态：`agent_settled` 与 `recycle{outcome}` 照旧结算欠着接力的任务 |
+| 不管的路 | 插件不经过模型就报出的终态：turn 出错、idle 阶梯用尽，以及 `recycle{outcome}` |
 
 `relay.toml` 是 TOML 的封闭子集：扁平的 `key = value` 行、上面两个键、单行双引号字符串数组、
 `#` 注释。子集之外一律 stderr 告警并忽略。它刻意不放 `.onlyne/config.toml`：client 以
@@ -238,17 +257,19 @@ stderr 告警并忽略，把机会让回文件。
 
 - **report 序号基址。** 插件自己的 `report` 序号从 1000 起，不是 1。client 把自身的派发事件
   （`created`、资源 attach、`ready`）写进同一个 `(generation, seq)` 水位，reducer 会静默丢弃
-  水位及以下的报告（`crates/onlyne-session/src/reconcile.rs`），所以从 1 起会丢掉最初的观测。
+  水位及以下的报告（`crates/onlyne-session/src/reconcile/`），所以从 1 起会丢掉最初的观测。
   其余版本语义与规范一致。
 - **`observed` 是完整的 `Observation`。** `report.heartbeat` 携带整个合法状态元组
   （`version`、`generation_live`、`isolate_after`、`terminate_after`、`mismatch_count`、
-  `agent`、`delivery`、`resource`、`recovery`、`outcome`、`public`），不是
-  `{"state": "running"}` 这种简写。宿主会反序列化它，`is_legal` 不接受的一律拒绝。本插件只管
-  `agent` 这一维（turn hooks），`delivery` 保持 `none`、`outcome` 保持 `pending`——在它报出
-  completion 之前这就是它的事实。`resource` 报 `attached`，因为宿主的派发路径已经记过这次
-  attach。
+  `agent`、`delivery`、`resource`、`recovery`），不是
+  `{"state": "running"}` 这种简写。宿主会反序列化它，先改写 client 主张的那六项，再套用 `is_legal`。本插件主张的
+  是 `agent`（turn hooks）、`resource`（进程还活在那块 pane 里，attach 早被宿主派发路径记过）
+  与 `host` 绑定这三件事。`delivery`、`recovery`、`generation_live`、`isolate_after`、
+  `terminate_after`、`mismatch_count` 它一个见证都没有：client 在归约前会用自己
+  的 intent 队列、reducer 历史与角色配置重写这六项，插件填什么都不会被读。任务的 outcome 与公开视图
+  更已经不在元组里，所以也就不再上报。
 - **`ready` 每连接报一次。** 宿主的 hand-off 路径
-  （`crates/onlyne-client/src/dispatch.rs::hand_session`）在把 session 交给挂载的插件时已经报过
+  （`crates/onlyne-client/src/session/dispatch/delivery.rs::hand_session`）在把 session 交给挂载的插件时已经报过
   `ready`，所以插件再报一次在宿主侧是 no-op。插件仍然发送：先挂载、后有活正是 ready barrier
   描述的情形，而且只花一帧。
 - **从不发 `cluster_ref`。** 本插件代表本地 role 说话，从不代表 aggregate；Rust 侧出于同样的
@@ -309,12 +330,12 @@ stderr 告警并忽略，把机会让回文件。
 | 反复 `reconnecting in 4000ms` | client 已停或 socket 被替换 | `onlyne --server-root … roles` |
 | `ready refused: internal: unknown session for …` | 插件为 client 从未暂存的任务报了 ready（手工起 pi 时的正常现象） | 让 client 拉起 pi，而不是手工起 |
 | `assign` 一直不来 | client 的 `session_command` 没能拉起 pi，或 `inject` 被降级 | client 日志里的 spawn 行；`/onlyne status` 看能力集 |
-| ledger 停在 `in_flight` | 没有 completion：没跑 turn，或 `agent_settled` 没触发 | pi session 文件里的 `onlyne-assign` / `onlyne-complete` 条目 |
+| ledger 停在 `in_flight` | 还没有 completion：没跑过 turn（注入的消息尚未执行），或阶梯还在提醒（`idleReminders`） | pi session 文件里的 `onlyne-assign` 条目和其后注入的提醒；`onlyne` 面板里的 `reminder n of m`；`/onlyne status` 看任务与阶段 |
 | `onlyne_complete` 回答 `relay guard: missing handoff to: …` | 工作区的 spec（或顶替它的 `relay.toml`）点名了一个本会话从未触达的 role | 日常通知显示在 `onlyne` 面板；stderr 保留 `relay guard from …` 等拒绝、socket 错误、超时与帧错误；`required=…` 说明策略；`relay guard: missing handoff …` 列出已投递集合 |
 | `hello` 后立刻 `forbidden` / 断连 | mount role 与 client 的 role 不一致 | `hello.args.mount.role` 对该工作区的 role |
 | `frame_too_large` | 正文超过 8 MiB | 只会由超限的出站图片触发；上限来自核心 |
 | 工具缺失 | 该 pi 版本没有 `pi.registerTool` | `/onlyne status`；对照上面的能力表 |
-| 会话在 `exited` 之后又回到 `idle` | completion 之后还落进了一条 heartbeat 快照，带着 `outcome: pending` | 看 session 日志里 `completion` 之后的 report 顺序；插件对已完成任务不再上报 |
+| 会话在 `exited` 之后又回到 `idle` | completion 之后又落进一条 turn-end heartbeat，把 agent 维搬了回去 | 看 session 日志里 `completion` 之后的 report 顺序；插件对已完成任务不再上报，而 client 自己的 `delivery` 两条都会保住 |
 | supervisor 看板一个 tab 都不列 | 没有 live session 上报过 pane：适配器版本早于这条上报，或这个 pi 不在 Orca pane 里 | `onlyne --server-root … sessions --json` 看 `projection.observed.host.orca.pane_key`；在 pane 里跑 `env \| grep ORCA_` |
 
 `/onlyne status` 打印实时状态（`connected`、`socket`、`role`、`sessionId`、`generation`、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
   "license": "MIT",