pi-onlyne 2.1.0 → 2.2.0

package/README.md

@@ -14,6 +14,11 @@ Outside an onlyne session the extension is inert. The client injects `ONLYNE_ROL
 (`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.
 
+Only the session whose own id equals `ONLYNE_SESSION_ID` mounts. A pi process runs more
+than one session — a `task` subagent's sidechain, `/new` — and each of them loads this
+extension with the same inherited environment, so a session that is not the bound one
+stays inert and every onlyne tool it calls is refused.
+
 ```
 pi session (spawned by onlyne-client)
   │  env: ONLYNE_ROLE / ONLYNE_SESSION_ID / ONLYNE_TASK_ID
@@ -157,6 +162,14 @@ Each result is one plain sentence — the recipient for a send or a handoff, the
 for a completion. A tool result is model-visible, and nothing about the plugin's own
 bookkeeping belongs in it.
 
+The three tools belong to the session that mounted them. A pi process runs more than one
+session — a `task` subagent's sidechain, `/new` — and every one of them loads this
+extension with the same inherited environment, so a call from a session whose id is not
+`ONLYNE_SESSION_ID` is refused with a sentence naming both ids instead of settling the
+parent's task. A pi that does not expose a session id (there is no `getSessionId` in
+`ctx.sessionManager`) is allowed through: the env-bound mount is still the only one that
+connected.
+
 ### `onlyne_send{to, text, kind?, image?}`
 
 Sends one envelope on the `send` frame. `kind: "note"` (the default) is free text and
@@ -178,7 +191,10 @@ receive, with the client holding the ceiling and refusing an oversize body with
 sentence (§3c of the contract). The call also ends the session's process: once the client
 has acknowledged the completion report (§4), the plugin asks pi to shut down through
 `ctx.shutdown()`. pi 0.85.1 has no tool-result `terminate` handling. The result is
-`reported <outcome>`.
+`reported <outcome>` — or, when a client that had already settled the task answers the
+report with its own record, `task already settled as <state> at <settled_at>: <head> —
+this call changed nothing`, which is the one case where the call did not cause the
+outcome it asked for.
 
 ### `onlyne_handoff{to, text, image?}`
 
@@ -196,33 +212,36 @@ of its own at hop 0.
 
 ## 4. Outcome rules
 
-`onlyne_complete` is the only path to `done`. The plugin sends one completion per task,
-at the first of these events:
+`onlyne_complete` is the only path to `done`, and it is the plugin's one completion path.
+The plugin sends one completion per task, at the first of these events:
 
 1. **`onlyne_complete`** — the model gives an explicit outcome: `done`, `failed`,
    `cancelled` or `blocked`. A later completion for the same task is refused (not
    re-reported). Its non-empty `summary` 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. The report itself waits until pi is waiting for input, so the beat that
-   carries it states a phase the session really has.
-3. **`recycle{outcome}`** — the host is tearing the session down. The plugin settles an
+2. **`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.
 
-A turn that ends cleanly without a completion settles nothing here. The client owns that
-rule (`docs/v2-CONTRACT.md`, "3c. One turn-end rule"): it counts the endings, sends its
-own sentence as a `nudge`, and decides what a delivery that never reports becomes. The
-plugin hands the sentence to pi and answers only that it did, so the wording, the count
-and the settlement have one owner rather than two. A task whose injected message has not
-run a turn is left alone whatever a settle signal says: reporting now would claim work
-that never happened.
+A turn that ends without a completion settles nothing here, and neither does a turn that
+ends with one. The endings belong to the client (`docs/v2-CONTRACT.md`, "3c. One
+turn-end rule"): it counts them, sends its own sentence as a `nudge`, and decides what a
+delivery that never reports becomes; its own sweeps own a session whose agent died. The
+plugin hands the nudge to pi, answers only that it did, and reports only its phase and
+the completion the model asked for — one owner for the wording, the count and the
+settlement, rather than two. A task whose injected message has not run a turn is left
+alone whatever a settle signal says: reporting now would claim work that never happened.
+
+A turn that ended with a provider error (`stopReason: "error"`) is not a verdict either.
+pi retries a retryable provider error and stays inside the same run, and the client's
+nudge can restart a session a moment after it settles, so a report sent on the error
+would race work that is still going. The error only supplies the head fallback described
+below.
 
 `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 `summary`
-of the explicit `onlyne_complete` call when that call carried one, or the error a failed
-turn reported. The last assistant text is the fallback for a call whose `summary` is
-empty — a sentence spoken after such a call cannot replace what the call handed over, and
-nothing else reads it.
+of the explicit `onlyne_complete` call when that call carried one. A call whose `summary`
+is empty falls back to what the session last said — the last assistant text, or the error
+of a turn that failed. The error is only ever that fallback: it is never a completion, and
+a sentence spoken after such a call cannot replace what the call handed over.
 
 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
@@ -231,6 +250,13 @@ 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.
 
+A client that had already settled this task answers the same request with
+`{"already_settled": {state, settled_at, head}}` instead of `null`. The plugin hands that
+record on rather than claiming an outcome it did not cause, and the tool result says so
+(§3); on the reconnect flush, where no tool result exists to carry it, the record reaches
+the `[pi-onlyne]` log. Either way the task stays settled: the client's row is the
+authority.
+
 The completion is the plugin's last report, and a session that has completed one answers
 no further beat and no `probe`. The terminal agent state is the client's own write: the
 `detach` frame that follows retires the task-free session, and that path feeds
@@ -256,9 +282,9 @@ A background-task extension changes the question. `bg_run` and its siblings retu
 once and the work continues in a child process, so pi waits for input while the session's
 task is still in flight. The plugin recognises the extension by the tools it registered
 and asks its EventBus service for the live task list; a task in `running` status holds
-the session at `running`, and the one report the plugin owes at a turn end — the failure
-it witnessed itself — waits that out. On a session without the extension there is no tool
-to recognise, no query, and nothing to wait for.
+the session at `running`, so the beat states a phase the session really has. No report of
+the plugin's own waits on that: nothing is reported at a turn end any more. On a session
+without the extension there is no tool to recognise, no query, and nothing to wait for.
 
 ## 5. Protocol notes and deviations
 
@@ -403,6 +429,8 @@ agent's own output lands in `<ws>/.onlyne/logs/session-<task>.log`.
 
 在一个 onlyne 会话之外，扩展不会执行任何操作。客户端会向其启动的每个进程注入 `ONLYNE_ROLE`、`ONLYNE_SESSION_ID` 和 `ONLYNE_TASK_ID`（`crates/onlyne-client/src/session/dispatch.rs`）。任一变量缺失时，这就是一个普通的 pi 会话：插件不注册任何内容，也不打开任何内容。
 
+只有自身会话 id 等于 `ONLYNE_SESSION_ID` 的会话才会挂载。一个 pi 进程会跑不止一个会话——`task` 子代理的 sidechain、`/new`——它们都带着同一份继承来的环境变量加载本扩展，因此不是被绑定会话的那个会话保持静默，它发出的每一次 onlyne 工具调用都会被拒绝。
+
 ```
 pi session (spawned by onlyne-client)
   │  env: ONLYNE_ROLE / ONLYNE_SESSION_ID / ONLYNE_TASK_ID
@@ -522,6 +550,8 @@ pi API 缺失时会发生什么，以及主机随后如何处理：
 
 每个结果只有一句平实的话——send 与 handoff 给出发往的角色，complete 给出结果。工具结果是模型可见的，插件自己的簿记没有理由出现在里面。
 
+这三个工具属于挂载它们的那个会话。一个 pi 进程会跑不止一个会话——`task` 子代理的 sidechain、`/new`——它们都会带着同一份继承来的环境变量加载本扩展；因此，当调用的会话 id 不等于 `ONLYNE_SESSION_ID` 时，调用会被拒绝，并给出同时点名两个 id 的一句话，而不是去结算父任务。若该 pi 不暴露会话 id（`ctx.sessionManager` 没有 `getSessionId`），调用照常放行：此时唯一连上 socket 的仍然是那个由环境变量绑定的挂载。
+
 ### `onlyne_send{to, text, kind?, image?}`
 
 通过 `send` 帧发送一个信封。`kind: "note"`（默认值）是自由文本，不携带 `op_id`。`kind: "task"` 将工作移交给一个角色，因此携带 `o-<uuid>` 幂等键和新的 `causality.task`。`image` 是 `png/jpeg/gif/webp` 文件的绝对路径：插件读取该文件，进行 base64 编码，并将其作为 `body.image` 附加。核心将该文件限制为 2 MiB，并接受四种 mime 类型。
@@ -530,7 +560,7 @@ pi API 缺失时会发生什么，以及主机随后如何处理：
 
 ### `onlyne_complete{outcome, summary, details?, files?}`
 
-以明确结果结束当前任务——即 proto 的 `Outcome`：`done`、`failed`、`cancelled` 或 `blocked`。`summary` 是展示用的一行，原样成为账本的 `head`：空白折叠为一行，文本在 200 个字符处截断；`summary` 为空时不携带展示行，head 回退到最后一条助手文本。`details` 是完整结果，`files` 是它所点名的绝对路径：两者原样搭在 `report.complete` 帧上，也正是下游与发起方收到的东西，上限由客户端把守，超限正文由客户端用自己的句子拒绝（契约 §3c）。该调用也会结束会话进程：客户端确认完成报告后（见 §4），插件会通过 `ctx.shutdown()` 请求 pi 关闭。pi 0.85.1 没有工具结果的 `terminate` 处理。结果为 `reported <outcome>`。
+以明确结果结束当前任务——即 proto 的 `Outcome`：`done`、`failed`、`cancelled` 或 `blocked`。`summary` 是展示用的一行，原样成为账本的 `head`：空白折叠为一行，文本在 200 个字符处截断；`summary` 为空时不携带展示行，head 回退到最后一条助手文本。`details` 是完整结果，`files` 是它所点名的绝对路径：两者原样搭在 `report.complete` 帧上，也正是下游与发起方收到的东西，上限由客户端把守，超限正文由客户端用自己的句子拒绝（契约 §3c）。该调用也会结束会话进程：客户端确认完成报告后（见 §4），插件会通过 `ctx.shutdown()` 请求 pi 关闭。pi 0.85.1 没有工具结果的 `terminate` 处理。结果为 `reported <outcome>`；若客户端此前已经结算过该任务，它会用自己的记录作答，此时结果变成 `task already settled as <state> at <settled_at>: <head> — this call changed nothing`——这是调用并未造成它所请求的那个结果的唯一情形。
 
 ### `onlyne_handoff{to, text, image?}`
 
@@ -538,18 +568,21 @@ pi API 缺失时会发生什么，以及主机随后如何处理：
 
 ## 4. 结果规则
 
-`onlyne_complete` 是通向 `done` 的唯一路径。插件为每个任务发送一次完成报告，在以下事件中第一个发生时发送：
+`onlyne_complete` 是通向 `done` 的唯一路径，也是插件唯一的完成路径。插件为每个任务发送一次完成报告，在以下事件中第一个发生时发送：
 
 1. **`onlyne_complete`**——模型给出明确结果：`done`、`failed`、`cancelled` 或 `blocked`。同一任务后续的完成调用会被拒绝，不会再次报告。其非空 `summary` 就是 head。
-2. **出错的轮次**——该轮次以模型提供方错误结束（`stopReason: "error"`）。这本身即可证明出错，因此插件立即报告 `failed`，并将错误作为 head。报告本身要等到 pi 正在等待输入时才发出，因此承载它的那次心跳陈述的是会话真实的阶段。
-3. **`recycle{outcome}`**——主机正在拆除会话。插件先使用主机给出的结果确定尚未确定状态的任务，然后停止并退出 pi。
+2. **`recycle{outcome}`**——主机正在拆除会话。插件先使用主机给出的结果确定尚未确定状态的任务，然后停止并退出 pi。
+
+没有完成就结束的轮次在这里不结算任何东西，以错误结束的轮次同样不结算。结束这件事归 client（`docs/v2-CONTRACT.md` 的「3c. One turn-end rule」）：它统计这类结束、把自己的一句话作为 `nudge` 发来，并决定一次始终不上报的投递会变成什么；agent 已死的会话由它自己的清扫负责。插件把那句话交给 pi，并且只回答自己交出去了，同时只上报自己的阶段与模型主动要求的完成——措辞、计数与结算都只有一个拥有者，而不是两个。注入消息尚未跑过任何轮次的任务，无论结算信号说什么都不动：现在就上报等于宣称从未发生的工作已经完成。
 
-正常结束、但没有完成的轮次在这里不结算任何东西。那条规则由 client 拥有（`docs/v2-CONTRACT.md` 的「3c. One turn-end rule」）：它统计这类结束、把自己的一句话作为 `nudge` 发来，并决定一次始终不上报的投递会变成什么。插件把那句话交给 pi，并且只回答自己交出去了，于是措辞、计数与结算都只有一个拥有者，而不是两个。注入消息尚未跑过任何轮次的任务，无论结算信号说什么都不动：现在就上报等于宣称从未发生的工作已经完成。
+以提供方错误（`stopReason: "error"`）结束的轮次也不是结论：pi 会对可重试的提供方错误重试，并留在同一次运行里，而 client 的 nudge 可能在会话结算之后的一瞬间重新启动它，所以在这里发出报告只会与仍在进行的工作赛跑。错误只提供下面说的 head 回退。
 
-`head` 是单行文本，上限为 200 个字符；它与客户端写入 `out_head` 的内容以及回执携带的内容一致。每个任务的 `head` 只有一个来源：显式 `onlyne_complete` 调用携带 `summary` 时就是它，否则是失败轮次报告的错误。完全没有携带 `summary` 的调用，回退到最后一条助手文本；此类调用之后说出的句子不能替代调用已经交付的内容，也不会被其他任何内容读取。
+`head` 是单行文本，上限为 200 个字符；它与客户端写入 `out_head` 的内容以及回执携带的内容一致。每个任务的 `head` 只有一个来源：显式 `onlyne_complete` 调用携带 `summary` 时就是它。完全没有携带 `summary` 的调用回退到会话最后说过的话——最后一条助手文本，或失败轮次留下的错误。错误永远只是这个回退：它本身从不构成完成，而此类调用之后说出的句子不能替代调用已经交付的内容。
 
 已报告的完成会结束会话进程。`report.complete` 以请求形式发出；客户端仅在完成会话记录的处理、确认投递并写入 `Completion` 信封后才回复。插件在该回复到达时请求 pi 关闭。套接字无法传输的结果会进入队列，并在下一次 `hello` 之后刷新；该次刷新收到的回复即为结束进程的交接。主机拒绝的完成会让进程继续运行，因此进程退出不会导致任务丢失。
 
+若客户端此前已经结算过该任务，它会对同一个请求回答 `{"already_settled": {state, settled_at, head}}` 而不是 `null`。插件把这个记录原样转交，而不是声称一个并非由本次调用造成的结果，工具结果也照此说明（见 §3）；在重连补发那条路径上，没有工具结果可以承载它，记录会进入 `[pi-onlyne]` 日志。无论哪种情形任务都保持已结算：以客户端的那一行为准。
+
 完成报告是插件发出的最后一份报告；已经完成任务的会话不再回应心跳，也不再回应 `probe`。终态的 agent 维度由客户端自己写入：随后到达的 `detach` 会退役这个已无任务的会话，该路径会喂入 `AgentGone` 并发布这一行（`retire_idle_locked`，`crates/onlyne-client/src/session/dispatch/retire.rs`）。正在离开的进程不为自己声明阶段。
 
 ### 空闲判定
@@ -558,7 +591,7 @@ pi API 缺失时会发生什么，以及主机随后如何处理：
 
 插件向 pi 查询，而不是自行假设。`ctx.isIdle()` 回答是否还有运行、压缩或排队中的续跑，`ctx.hasPendingMessages()` 回答输入是否已经在路上；缺失或抛错的探针一律读作 `running`。`agent_settled` 通常是空闲声明落地的时刻，因为 pi 只在一次运行彻底结算之后才触发该事件；单个轮次的结束是另一个时刻。每 10 秒的心跳会在每次触发时重新向 pi 推导阶段，因此重新开始的运行不会留下过期的空闲读数。
 
-后台任务扩展改变了这个问题。`bg_run` 及其同类工具立即返回，工作继续在子进程中运行，于是 pi 在会话任务仍在进行时等待输入。插件通过该扩展注册的工具识别它，并向它的 EventBus 服务查询存活任务列表；处于 `running` 状态的任务会让会话保持 `running`，插件在轮次结束时欠下的那份报告——它自己目睹的失败——也要等它结束。没有安装该扩展的会话没有可识别的工具、没有查询，也就没有可等待的东西。
+后台任务扩展改变了这个问题。`bg_run` 及其同类工具立即返回，工作继续在子进程中运行，于是 pi 在会话任务仍在进行时等待输入。插件通过该扩展注册的工具识别它，并向它的 EventBus 服务查询存活任务列表；处于 `running` 状态的任务会让会话保持 `running`，于是心跳陈述的是会话真实的阶段。插件自己没有任何报告要等它结束：轮次结束时已经不再上报任何东西。没有安装该扩展的会话没有可识别的工具、没有查询，也就没有可等待的东西。
 
 ## 5. 协议说明与差异
 

package/README.zh.md

@@ -10,6 +10,10 @@ socket——机器级运行目录里的 `<digest>.sock`（`/tmp/onlyne-<uid>/`
 `ONLYNE_TASK_ID`（`crates/onlyne-client/src/session/dispatch.rs`）；三者缺一，就是普通 pi session，
 插件不注册任何工具、不打开任何 socket。
 
+只有自身 session id 等于 `ONLYNE_SESSION_ID` 的那个 session 才会挂载。一个 pi 进程会跑不止一个
+session——`task` 子代理的 sidechain、`/new`——它们都会带着同一份继承来的环境变量加载本扩展；
+因此不是被绑定 session 的那个保持静默，它发出的每一次 onlyne 工具调用都会被拒绝。
+
 ```
 pi session（由 onlyne-client spawn）
   │  环境变量：ONLYNE_ROLE / ONLYNE_SESSION_ID / ONLYNE_TASK_ID
@@ -145,6 +149,12 @@ role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为
 每个结果只有一句话——send 与 handoff 说发给谁，complete 说结果。工具结果模型看得见，
 插件自己的账本没有理由出现在里面。
 
+这三个工具属于挂载它们的那个 session。一个 pi 进程会跑不止一个 session——`task` 子代理的
+sidechain、`/new`——它们都会带着同一份继承来的环境变量加载本扩展；因此当调用的 session id
+不等于 `ONLYNE_SESSION_ID` 时，调用会被拒绝，并给出同时点名两个 id 的一句话，而不是去结算父
+任务。若该 pi 不暴露 session id（`ctx.sessionManager` 没有 `getSessionId`），调用照常放行：
+此时唯一连上 socket 的仍然是那个由环境变量绑定的挂载。
+
 ### `onlyne_send{to, text, kind?, image?}`
 
 经 `send` 帧提交一个 envelope。`kind: "note"`（默认）是自由文本，不带 `op_id`。
@@ -160,7 +170,10 @@ png/jpeg/gif/webp 的绝对路径：插件读出内容，base64 编码后挂成
 `files` 是它点名的绝对路径：两者原样搭在 `report.complete` 帧上，也正是下游与发起方收到的东西，
 上限由 client 把守，超限正文由 client 用自己的句子拒绝（契约 §3c）。这一调用同时结束所在
 session 的进程。client 应答完 completion 报告（见 §4）之后，插件通过 `ctx.shutdown()` 让 pi
-退出。pi 0.85.1 没有 tool-result `terminate` 处理。结果是 `reported <outcome>`。
+退出。pi 0.85.1 没有 tool-result `terminate` 处理。结果是 `reported <outcome>`；若 client 此前
+已经结算过该任务，它会用自己的记录作答，此时结果变成 `task already settled as <state> at
+<settled_at>: <head> — this call changed nothing`——这是调用并未造成它所请求的那个结果的唯一
+情形。
 
 ### `onlyne_handoff{to, text, image?}`
 
@@ -175,32 +188,40 @@ hop 预算留在 envelope 的 `causality` 里，属于协议数据：投递文
 
 ## 4. outcome 判定规则
 
-`onlyne_complete` 是通向 `done` 的唯一路径。插件每个任务只发一次 completion，取以下三者的先到者：
+`onlyne_complete` 是通向 `done` 的唯一路径，也是插件唯一的完成路径。插件每个任务只发一次
+completion，取以下两者的先到者：
 
 1. **`onlyne_complete`** —— 模型给显式 outcome：`done`、`failed`、`cancelled` 或 `blocked`。同一
    任务的第二次 completion 被拒（不重报）。`summary` 非空时即 head，原样写出。
-2. **turn 出错** —— turn 以 provider 错误告终（`stopReason: "error"`）。这本身就是证据，插件立即
-   报 `failed`，错误信息当 head。上报本身要等到 pi 正在等待输入时才发出，所以承载它的那次心跳
-   陈述的是 session 真实的阶段。
-3. **`recycle{outcome}`** —— 宿主拆 session。插件先按宿主给的 outcome 结算未终态的任务，再停
+2. **`recycle{outcome}`** —— 宿主拆 session。插件先按宿主给的 outcome 结算未终态的任务，再停
    插件并退出 pi。
 
-干净结束、却没有 completion 的 turn 在这里不结算任何东西。那条规则归 client
+没有 completion 就结束的 turn 在这里不结算任何东西，以错误结束的 turn 同样不结算。结束这件事归 client
 （`docs/v2-CONTRACT.md` 的 “3c. One turn-end rule”）：它数这类结束、把自己的一句话作为 `nudge`
-发来，并决定一次始终不上报的投递会变成什么。插件把那句话交给 pi，并且只回答自己交出去了，
-于是措辞、计数与结算都只有一个主人，而不是两个。注入的消息还没跑过任何 turn 的任务，无论结算
-信号说什么都不动：现在就报终态，等于声称干过一件没发生过的活。
+发来，并决定一次始终不上报的投递会变成什么；agent 已死的 session 由它自己的清扫负责。插件把那
+句话交给 pi，并且只回答自己交出去了，同时只上报自己的阶段与模型主动要求的 completion——措辞、
+计数与结算都只有一个主人，而不是两个。注入的消息还没跑过任何 turn 的任务，无论结算信号说什么都
+不动：现在就报终态，等于声称干过一件没发生过的活。
+
+以 provider 错误（`stopReason: "error"`）结束的 turn 也不是结论：pi 会对可重试的 provider 错误
+重试，并留在同一次 run 里，而 client 的 nudge 可能在 session 结算之后的一瞬重新启动它，所以在
+这里发报告只会与仍在进行的工作赛跑。错误只提供下面说的 head 退路。
 
 `head` 恒为单行、上限 200 字符，与 client 写入 `out_head` 和回执携带的内容一致。每个任务的 head
-只有一个来源：显式 `onlyne_complete` 带 `summary` 时就是它，否则是出错 turn 报的错误。最后一段
-assistant 文本只是 `summary` 完全缺失的 `onlyne_complete` 的退路——调用之后再说的话顶不掉调用
-交出的内容，此外没有任何东西读它。
+只有一个来源：显式 `onlyne_complete` 带 `summary` 时就是它。完全没有带 `summary` 的调用退到
+session 最后说过的话——最后一段 assistant 文本，或失败 turn 留下的错误。错误永远只是这个退路：
+它本身从不构成 completion，此外没有任何东西读它；而调用之后再说的话顶不掉调用交出的内容。
 
 报出去的 completion 会结束所在 session 的进程。`report.complete` 以请求形式发出，client 只有
 在结算 session 行、ack 掉投递、并写好 `Completion` envelope 之后才应答，插件就在这个应答处
 让 pi 退出。socket 当时送不出去的 outcome 会被记住，并在下一次 `hello` 后补发，那次补发的
 应答就是结束进程的交接点。被宿主拒掉的 completion 不会让进程退出，任务不会因为退出而丢失。
 
+若 client 此前已经结算过该任务，它会对同一个请求回答 `{"already_settled": {state, settled_at,
+head}}` 而不是 `null`。插件把这个记录原样转交，而不是声称一个并非由本次调用造成的结果，工具结果
+也照此说明（见 §3）；在重连补发那条路径上没有工具结果可以承载它，记录会进入 `[pi-onlyne]` 日志。
+无论哪种情形任务都保持已结算：以 client 的那一行为准。
+
 completion 是插件最后一份上报；已经交掉任务的 session 不再发心跳，也不再应答 `probe`。终态的
 agent 维度由 client 自己写：随后到达的 `detach` 会退役这个已无任务的 session，该路径会喂入
 `AgentGone` 并发布这一行（`retire_idle_locked`，
@@ -218,8 +239,9 @@ steer 或 follow-up 消息、重试、压缩，以及被后台任务扩展移出
 
 后台任务扩展改变了这个问题。`bg_run` 与同类工具立即返回，工作继续在子进程里跑，于是 pi 在任务
 仍在进行时就等待输入。插件通过该扩展注册的工具认出它，再向它的 EventBus 服务查存活任务列表；
-处于 `running` 的任务会把 session 按在 `running` 上，插件在轮次结束时欠下的那份报告——它自己
-目睹的失败——也要等它结束。没有装这个扩展的 session 没有工具可认、没有查询，也没有东西要等。
+处于 `running` 的任务会把 session 按在 `running` 上，于是心跳陈述的是 session 真实的阶段。插件
+自己没有任何报告要等它结束：轮次结束时已经不再上报任何东西。没有装这个扩展的 session 没有工具
+可认、没有查询，也没有东西要等。
 
 ## 5. 协议说明与偏差
 

package/package.json

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

package/src/agent.mjs

@@ -10,6 +10,16 @@
 // surface, which is why the whole state machine is testable against a plain
 // Node unix socket.
 //
+// One completion path, and it is the model's: an explicit `onlyne_complete`
+// (`completeFromTool`) or the host's `recycle{outcome}`. A turn that ends
+// without one — cleanly or with a provider error — decides nothing here: the
+// client's own turn-end rule owns the ending (`docs/v2-CONTRACT.md` §3c: one
+// nudge, then the delivery settles `blocked`) and its own sweeps own a session
+// whose agent died. A failed turn only supplies the head fallback, because pi
+// retries a retryable provider error inside the same run and the client's nudge
+// can restart a session a moment after it settles — a report sent on the error
+// would race work that is still going.
+//
 // What the human sees travels through one funnel, `notice` below: the pi widget
 // panel when the host has `ctx.ui.setWidget`, the footer status line plus a
 // `[pi-onlyne]` stderr line when it has not. `log` keeps the diagnostics — a
@@ -46,11 +56,6 @@ export const RECONNECT_LADDER_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
 export const HELLO_TIMEOUT_MS = 5_000;
 /** Default bound on one request round trip. */
 export const REQUEST_TIMEOUT_MS = 30_000;
-/**
- * How long after an errored turn the plugin waits for `agent_settled` before it
- * reports the failure it witnessed itself.
- */
-export const SETTLE_FALLBACK_MS = 2_000;
 
 /** Capabilities this plugin implements on the wire. */
 export const CAPABILITIES = ["register", "report", "inject", "recycle"];
@@ -71,7 +76,6 @@ export class OnlyneAgent {
    *   ladder?: number[],
    *   requestTimeoutMs?: number,
    *   helloTimeoutMs?: number,
-   *   settleFallbackMs?: number,
    *   createConnection?: (path: string) => any,
    *   timer?: { set: (fn: () => void, ms: number) => any, clear: (handle: any) => void },
    * }} options
@@ -92,7 +96,6 @@ export class OnlyneAgent {
     this.ladder = options.ladder ?? RECONNECT_LADDER_MS;
     this.requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
     this.helloTimeoutMs = options.helloTimeoutMs ?? HELLO_TIMEOUT_MS;
-    this.settleFallbackMs = options.settleFallbackMs ?? SETTLE_FALLBACK_MS;
     this.createConnection = options.createConnection ?? ((path) => createConnection(path));
     // The pane this process was spawned in, reported on every heartbeat so the
     // supervisor board can attribute the tab (protocol.mjs `hostBinding`). Read
@@ -122,7 +125,6 @@ export class OnlyneAgent {
     this.attempt = 0;
     this.reconnectHandle = null;
     this.heartbeatHandle = null;
-    this.settleHandle = null;
     /**
      * The heartbeat round in flight, and what the next pass of it should say.
      * `heartbeat` never lets two rounds overlap, so `beatRound` doubles as the
@@ -710,10 +712,6 @@ export class OnlyneAgent {
       this.timer.clear(this.reconnectHandle);
       this.reconnectHandle = null;
     }
-    if (this.settleHandle) {
-      this.timer.clear(this.settleHandle);
-      this.settleHandle = null;
-    }
     this.rejectAll("agent stopped");
   }
 
@@ -775,9 +773,7 @@ export class OnlyneAgent {
     if (held && !held.completed) {
       // A new envelope for a task this session already holds — a follow-up, a
       // redirect, a bounce back through a handoff. The work record stays where
-      // it is, and the failure an errored turn proved belonged to the
-      // instruction being replaced, so it is cleared with that instruction.
-      held.errored = false;
+      // it is; the newest instruction re-points it at the newest envelope.
       held.envelopeId = envelope.id ?? held.envelopeId;
       // `lastSeq` deliberately does not reset here. It is the floor the next
       // allocation for this task must clear, and the host's row for the task
@@ -800,7 +796,6 @@ export class OnlyneAgent {
          * share the plugin's counter. Null until the first report.
          */
         lastSeq: null,
-        errored: false,
         head: "",
       });
     }
@@ -906,8 +901,10 @@ export class OnlyneAgent {
    *
    * How a turn end settles the work is the client's rule
    * (`docs/v2-CONTRACT.md` §3c): the plugin counts nothing, bounds nothing, and
-   * reports only the facts it alone can see — its own phase, and an errored
-   * turn.
+   * reports only its own phase and the completion the model asked for. A turn
+   * that ended without a completion is the client's case — its own one-nudge
+   * rule, and its own sweeps for a session whose agent died — so nothing here
+   * decides an outcome.
    */
   onTurnStart() {
     void this.heartbeat("running").catch((error) => this.log(`heartbeat refused: ${error.message}`));
@@ -925,40 +922,29 @@ export class OnlyneAgent {
   }
 
   /**
-   * pi has settled: the session is waiting for input, which is the moment an
-   * errored turn is reported from.
+   * pi has settled: the session is waiting for input. The phase is the whole of
+   * what this hook says — a settle is not a verdict, because the client's own
+   * nudge can restart a session a moment later and pi can still be inside a
+   * retry that settles it again.
    */
   onSettled() {
-    this.clearSettleFallback();
     void this.heartbeat().catch((error) => this.log(`heartbeat refused: ${error.message}`));
-    void this.trySettle().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
   }
 
   /**
-   * Report a turn that failed, once pi is quiet. pi keeps `isIdle()` false while
-   * it is running, retrying, compacting, or holding a queued continuation, and
-   * a background task keeps work running after pi itself has settled, so a
-   * signal that arrives during any of those waits re-arms instead of reporting
-   * from a session that is still busy. The fallback timer and `agent_settled`
-   * both land here, and a task is reported once because the report completes it.
+   * A turn ended with an error (`stopReason: "error"`). The plugin sends
+   * nothing: an error is not proof of a terminal outcome, because pi retries a
+   * retryable provider error and stays inside the same run, and the client's
+   * nudge can restart a session a moment after it settles — so a report sent
+   * here would race work that is still going. What the error does supply is the
+   * head fallback for a later `onlyne_complete` whose `summary` carries nothing.
    */
-  async trySettle() {
-    if (this.closed || this.activeTasks().length === 0) return;
-    if (await this.derivedPhase() !== "idle") {
-      this.armSettleFallback();
-      return;
-    }
-    await this.reportFailedTurns().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
-  }
-
-  /** A failed turn: the task's outcome is `failed`, with the error as its head. */
   onTurnError(text) {
     for (const task of this.tasks.values()) {
       if (task.completed) continue;
-      task.errored = true;
       if (text) task.head = headOf(text);
     }
-    void this.trySettle().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
+    this.notice("warn", `turn ended with an error: ${headOf(text) || "no reason given"}`);
   }
 
   /**
@@ -979,38 +965,6 @@ export class OnlyneAgent {
     }
   }
 
-  armSettleFallback() {
-    this.clearSettleFallback();
-    if (this.closed || this.activeTasks().length === 0) return;
-    this.settleHandle = this.timer.set(() => {
-      this.settleHandle = null;
-      void this.trySettle().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
-    }, this.settleFallbackMs);
-  }
-
-  clearSettleFallback() {
-    if (!this.settleHandle) return;
-    this.timer.clear(this.settleHandle);
-    this.settleHandle = null;
-  }
-
-  /**
-   * Report the failures this session witnessed itself, for every task it still
-   * holds.
-   *
-   * An errored turn is proof on its own — pi may skip the clean turn end — so
-   * its task is reported `failed` at once, with the error as its head. Nothing
-   * else is decided here: a turn that ends without a completion is the client's
-   * case, and it reaches the session as the host's nudge (`onNudge`), so a
-   * plugin that also decided it would be the second owner of the rule.
-   */
-  async reportFailedTurns() {
-    for (const task of [...this.tasks.values()]) {
-      if (task.completed || !task.errored) continue;
-      await this.complete(task.taskId, "failed", task.head);
-    }
-  }
-
   /**
    * `onlyne_complete`: the model's explicit outcome, and the only path to
    * `done`.
@@ -1100,8 +1054,9 @@ export class OnlyneAgent {
     // flight. A refused or broken request handed nothing over, so the task
     // goes back to open and the caller sees why: a retry reports again, and
     // `completeFromTool` still finds the task.
+    let answer = null;
     try {
-      await this.request("report", report);
+      answer = await this.request("report", report);
     } catch (error) {
       if (task) task.completed = false;
       throw error;
@@ -1114,6 +1069,14 @@ export class OnlyneAgent {
       this.stopHeartbeat();
       if (exitProcess) this.exitSession(normalized);
     }
+    // A client that had already settled this task says so with its own record
+    // of the terminal fact, and the caller hands that on rather than claiming
+    // the completion it just sent. The task is still left settled here: the
+    // client's row is the authority, and re-opening it would only ask the
+    // model to report an outcome nobody is waiting for.
+    if (isAlreadySettled(answer)) {
+      return { taskId, outcome: normalized, head: summary, alreadySettled: answer.already_settled };
+    }
     return { taskId, outcome: normalized, head: summary };
   }
 
@@ -1143,7 +1106,15 @@ export class OnlyneAgent {
       if (!this.connected) return;
       const pending = this.pendingCompletions.shift();
       try {
-        await this.request("report", pending.report);
+        const answer = await this.request("report", pending.report);
+        // A queued completion has no tool result to carry the client's record
+        // back through, so the one thing worth saying is that the client had
+        // already settled the task and this report changed nothing.
+        if (isAlreadySettled(answer)) {
+          this.log(
+            `queued completion for ${pending.taskId.slice(0, 8)} was already settled by the client as ${answer.already_settled.state}`
+          );
+        }
         this.stats.completions += 1;
         this.activity.set({ taskId: this.activeTaskId() ?? null, phase: pending.outcome });
         this.notice("out", `complete ${pending.taskId.slice(0, 8)} ${pending.outcome} flushed after reconnect`);
@@ -1233,6 +1204,17 @@ export class OnlyneAgent {
   }
 }
 
+/**
+ * Whether a client's answer to a `report.complete` says the task had already
+ * settled. The shape is the client's (`{"already_settled": {state, settled_at,
+ * head}}`); a normal accepted completion answers `data = null`, which is not an
+ * object and reads as no.
+ */
+function isAlreadySettled(answer) {
+  return Boolean(answer) && typeof answer === "object" && answer.already_settled !== null
+    && typeof answer.already_settled === "object";
+}
+
 /** Mime type for one attachment path the model asked to send. */
 export function mimeForPath(path) {
   const lower = String(path).toLowerCase();

package/src/agent.test.mjs

@@ -117,6 +117,9 @@ async function waitFor(predicate, { timeoutMs = 2_000, stepMs = 5 } = {}) {
  * reports before answering the rest, the way a client whose settle failed would.
  * `request` sends a host frame carrying an id, which is how the plugin is asked
  * for an answer (`nudge`); `answers` reads what came back.
+ * `alreadySettled` answers every `complete` report with the client's
+ * already-settled shape in `data`, the way a client that had settled the task
+ * before the report arrived does.
  */
 class FakeHost {
   constructor({
@@ -125,6 +128,7 @@ class FakeHost {
     failSend = false,
     handoffError = null,
     failCompletions = 0,
+    alreadySettled = null,
   } = {}) {
     this.server = createServer((socket) => this.onConnection(socket));
     this.frames = [];
@@ -135,6 +139,7 @@ class FakeHost {
     this.failSend = failSend;
     this.handoffError = handoffError;
     this.failCompletions = failCompletions;
+    this.alreadySettled = alreadySettled;
     this.held = [];
   }
 
@@ -189,6 +194,9 @@ class FakeHost {
       }));
       return;
     }
+    if (this.alreadySettled && frame.op === "report" && frame.args?.kind === "complete") {
+      body = { ok: true, data: { already_settled: this.alreadySettled } };
+    }
     if (this.failSend && frame.op === "send") {
       socket.write(encodeFrame({
         reply_to: frame.id,
@@ -293,10 +301,11 @@ async function startAgent({
   failSend = false,
   handoffError = null,
   failCompletions = 0,
+  alreadySettled = null,
 } = {}) {
   const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-agent-"));
   const socketPath = join(dir, "s");
-  const host = new FakeHost({ coalesceAssign, holdCompletion, failSend, handoffError, failCompletions });
+  const host = new FakeHost({ coalesceAssign, holdCompletion, failSend, handoffError, failCompletions, alreadySettled });
   await host.listen(socketPath);
   const logs = [];
   const agent = new OnlyneAgent({
@@ -308,9 +317,6 @@ async function startAgent({
     surface,
     log: (line) => logs.push(line),
     ladder: [20, 40, 80],
-    // The fallback is the agent_settled-less path; a test that wants it asks for
-    // a short window, and every other test drives the exit explicitly.
-    settleFallbackMs: options.settleFallbackMs ?? 30_000,
     heartbeatMs: options.heartbeatMs ?? 60_000,
     ...(capabilities ? { capabilities } : {}),
     ...(options.host !== undefined ? { host: options.host } : {}),
@@ -688,30 +694,37 @@ test("a turn-end heartbeat after the completion never leaves the plugin", async
   assert.deepEqual(host.of("report").slice(reports), [], "the completion is the last report");
 });
 
-// The plugin still owes one report at a turn end: the failure it witnessed
-// itself. That report waits for the idle it is about, exactly as the phase-based
-// signal always did.
-test("a busy pi holds the failed-turn report until it is waiting for input", async () => {
-  let waiting = false;
-  const surface = fakeSurface({ waiting: () => waiting });
-  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+// A turn that ends with an error is not a verdict. pi retries a retryable
+// provider error and stays inside the same run, and the client's nudge can
+// restart a session a moment after it settles, so a report sent from here would
+// race work that is still going. The client's own turn-end rule (§3c) owns the
+// ending, and its sweeps own a session whose agent died; the plugin states its
+// phase and nothing else.
+test("a turn error sends no completion, even after a settle and a wait", async () => {
+  const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
   agent.onTurnError("provider exploded");
-  await new Promise((resolve) => setTimeout(resolve, 80));
-  assert.deepEqual(completions(host), [], "a busy pi is not reported on yet");
+  await waitFor(() => heartbeats(host).some((observed) => observed.agent === "running"));
+  agent.onSettled();
+  // Past the window the deleted fallback used to fire in (40 ms in the harness
+  // that pinned it), so a plugin that still armed one would have reported here.
+  await new Promise((resolve) => setTimeout(resolve, 150));
 
-  waiting = true;
-  const complete = await waitFor(() => completions(host)[0] ?? null);
-  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "failed", head: "provider exploded" });
+  assert.deepEqual(completions(host), [], "a failed turn reports no outcome nobody claimed");
+  assert.deepEqual(agent.status().tasks, [TASK_ID], "the task is still open");
+  assert.deepEqual(surface.calls.exits, [], "and the session stays mounted");
 });
 
-test("a live background task holds the failed-turn report until its task is terminal", async () => {
-  let backgroundWork = true;
-  const surface = fakeSurface({ backgroundWork: () => backgroundWork });
-  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+// What the error does supply is the head fallback: a completion whose summary
+// carries nothing still has a display line, and it is the sentence the failed
+// turn left behind.
+test("an explicit completion after a turn error uses the error as its head", async () => {
+  const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
@@ -719,14 +732,11 @@ test("a live background task holds the failed-turn report until its task is term
 
   agent.onTurnStart();
   agent.onTurnError("provider exploded");
-  await waitFor(() => heartbeats(host).at(-1)?.agent === "running");
-  await new Promise((resolve) => setTimeout(resolve, 80));
-  assert.deepEqual(completions(host), [], "work off the agent loop keeps the report off");
+  const result = await agent.completeFromTool({ outcome: "done" });
 
-  backgroundWork = false;
-  agent.onSettled();
-  const complete = await waitFor(() => completions(host)[0] ?? null);
-  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "failed", head: "provider exploded" });
+  assert.equal(result.head, "provider exploded", "the error text is the head fallback");
+  const [complete] = completions(host);
+  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "done", head: "provider exploded" });
 });
 
 // The turn-end rule has one owner, the client (`docs/v2-CONTRACT.md` §3c): a
@@ -735,15 +745,15 @@ test("a live background task holds the failed-turn report until its task is term
 // plugin's answer to a clean turn end is its beat and nothing else — no
 // injection, no count, and no outcome nobody claimed.
 test("a turn that ends without a completion settles nothing and says nothing", async () => {
-  const { agent, host, surface } = await startAgent({ options: { settleFallbackMs: 40 } });
+  const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
   agent.noteAssistantText("OK");
 
-  // Two clean turns and a settle after each: the fallback window and the
-  // settled signal both land, and neither has anything to decide.
+  // Two clean turns and a settle after each: the settled signal lands, and it
+  // has nothing to decide.
   agent.onTurnStart();
   agent.onTurnEnd();
   agent.onSettled();
@@ -772,18 +782,6 @@ test("an assigned task that never ran is not completed", async () => {
   assert.deepEqual(agent.status().tasks, [TASK_ID]);
 });
 
-test("a failed turn settles the task as failed with the error as head", async () => {
-  const { agent, host, surface } = await startAgent();
-  agent.start();
-  await waitFor(() => host.of("report").length >= 1);
-  host.notify("assign", assignArgs());
-  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
-  agent.onTurnStart();
-  agent.onTurnError("provider exploded");
-  const complete = await waitFor(() => host.of("report").find((report) => report.kind === "complete"));
-  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "failed", head: "provider exploded" });
-});
-
 test("an explicit tool outcome wins and a second completion is refused", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
@@ -1277,7 +1275,6 @@ test("a host that never answers the hello is dropped and retried", async () => {
     log: (line) => logs.push(line),
     ladder: [20],
     helloTimeoutMs: 40,
-    settleFallbackMs: 30,
   });
   cleanups.push(async () => {
     agent.stop("test");
@@ -1314,6 +1311,40 @@ test("a completion sends the summary as the head and adds nothing else", async (
   assert.equal(JSON.stringify(completions(host)[0]), COMPLETE_VECTOR);
 });
 
+// A client that had already settled this task answers the report with its own
+// record instead of `data: null`. The completion still leaves the task settled —
+// the client's row is the authority — but the caller hands the record on, so the
+// tool result can say the call changed nothing rather than claim the outcome.
+test("a report the client answers as already settled comes back as the client's record", async () => {
+  const settled = {
+    state: "failed",
+    settled_at: "2026-10-11T05:15:47Z",
+    head: "provider exploded",
+  };
+  const { agent, host } = await startAgent({ alreadySettled: settled });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const result = await agent.completeFromTool({ outcome: "done", summary: "finished it" });
+  assert.deepEqual(result, {
+    taskId: TASK_ID,
+    outcome: "done",
+    head: "finished it",
+    alreadySettled: settled,
+  });
+  assert.equal(completions(host).length, 1, "the report still went out");
+  assert.deepEqual(agent.status().tasks, [], "the client's row is the authority");
+});
+
+test("a normal accepted completion carries no already-settled record", async () => {
+  const { agent, host } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const result = await agent.completeFromTool({ outcome: "done", summary: "finished it" });
+  assert.deepEqual(result, { taskId: TASK_ID, outcome: "done", head: "finished it" });
+});
+
 test("details and files ride the completion unchanged", async () => {
   const { agent, host } = await startAgent();
   agent.start();
@@ -1374,7 +1405,7 @@ test("a nudge hands the client's sentence over as it stands and answers ok", asy
   // A nudge is not a delivery and not a report: the task stays open, its record
   // is untouched, and no frame of the plugin's own follows.
   assert.equal(agent.tasks.get(TASK_ID), record);
-  assert.equal(record.errored, false);
+  assert.equal(record.head, "", "the nudge leaves the head fallback alone");
   assert.deepEqual(host.of("report").slice(reportsBefore), []);
 });
 

package/src/index.ts

@@ -7,20 +7,34 @@
 // `crates/onlyne-client/src/dispatch.rs`); with any of the three missing this is
 // a plain pi session and the extension stays silent rather than failing.
 //
-//   session_start      -> read env + .pi/onlyne.json, connect, register tools
+//   session_start      -> bind the env session id, read env + .pi/onlyne.json,
+//                         connect, register tools
 //   before_agent_start -> the role prose becomes one section of the system
 //                         prompt the run is about to send (the instruction layer)
 //   turn_start         -> heartbeat{running}
 //   turn_end           -> one turn of a run ended; the phase is re-derived from pi
-//                         and the fallback window for a witnessed failure opens
-//   message_end        -> keep the last assistant text; a failed turn is `failed`
-//   agent_settled      -> heartbeat{idle} when the session waits for input, and the
-//                         report a failed turn owes is sent from here
+//   message_end        -> keep the last assistant text as the head fallback
+//   agent_settled      -> heartbeat{idle} when the session waits for input
 //   session_shutdown   -> detach{reason}
 //
+// The plugin keeps exactly one completion path: the model's explicit
+// `onlyne_complete` (and `recycle{outcome}`). A turn that ends without one
+// decides nothing here — the client's own turn-end rule owns it
+// (`docs/v2-CONTRACT.md` §3c: one nudge, then the delivery settles `blocked`)
+// and its sweeps own a session whose agent died. A turn error only supplies the
+// head fallback, because pi retries a retryable provider error and stays inside
+// the same run, and the client's nudge can restart a session a moment after it
+// settles — a report sent on a turn error would race work that is still going.
+//
 // Host frames are dispatched in `agent.mjs`, not here: `assign` and `nudge` are
 // injected as user messages, `probe` is answered with a heartbeat, and `recycle`
 // settles the task and stops the plugin.
+//
+// Only the session whose id equals `ONLYNE_SESSION_ID` mounts: a pi process runs
+// a subagent sidechain and `/new` sessions too, all inheriting this extension's
+// environment, and a sidechain that called `onlyne_complete` would settle the
+// parent's task. `session-scope.mjs` carries the rule, the guard behind it, and
+// what a call from a foreign session is told.
 
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -29,6 +43,7 @@ import { OnlyneAgent } from "./agent.mjs";
 import { loadConfig, sessionIdentity } from "./config.mjs";
 import { resolveSocketPath } from "./socket.mjs";
 import { createSurface } from "./pi-surface.mjs";
+import { foreignSessionRefusal, mountsSession, ownsSession, sessionIdOf } from "./session-scope.mjs";
 
 /**
  * Node's process globals, declared here so the package needs no `@types/node`
@@ -131,12 +146,29 @@ export default function onlyne(pi: ExtensionAPI) {
   let agent: OnlyneAgent | null = null;
   let surface: PiSurface | null = null;
   let registered = false;
+  /**
+   * The session id that mounted this plugin. A pi process can host more than
+   * one session — a `task` subagent runs a sidechain in the same process and
+   * inherits `ONLYNE_*`, and `/new` starts another — and every one of them
+   * loads this extension. The env names the one session that is the onlyne
+   * session, so the tools belong to it alone; an unbound session must not be
+   * able to settle this task by calling `onlyne_complete` from its sidechain.
+   */
+  let boundSessionId: string | null = null;
 
   const log = (line: string, data?: unknown) => {
     const detail = data === undefined ? "" : ` ${JSON.stringify(data)}`;
     process?.stderr?.write(`[pi-onlyne] ${line}${detail}\n`);
   };
 
+  /**
+   * Guard one tool call: the caller must be the session that mounted this
+   * plugin (`session-scope.mjs` carries the rule and the reason).
+   */
+  const refuseForeignSession = (caller: string | null): never => {
+    throw new Error(foreignSessionRefusal(boundSessionId, caller));
+  };
+
   /** Tools and the `/onlyne` command exist only inside an onlyne session. */
   const registerSurface = () => {
     if (registered || !surface) return;
@@ -157,7 +189,9 @@ export default function onlyne(pi: ExtensionAPI) {
           kind: Type.Optional(Type.String({ description: '"note" (default) or "task"' })),
           image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
         }),
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+          const caller = sessionIdOf(ctx?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) refuseForeignSession(caller);
           if (!agent) throw new Error("onlyne: session is not connected");
           const result = await agent.sendFromTool({
             to: params.to,
@@ -189,7 +223,9 @@ export default function onlyne(pi: ExtensionAPI) {
           details: Type.Optional(Type.String({ description: "the full result, delivered as it stands" })),
           files: Type.Optional(Type.Array(Type.String(), { description: "absolute paths of the files the result names" })),
         }),
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+          const caller = sessionIdOf(ctx?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) refuseForeignSession(caller);
           if (!agent) throw new Error("onlyne: session is not connected");
           // The exit is not a tool-result flag: pi 0.85.1 has no tool-result
           // `terminate` handling. `agent.complete` asks the surface to shut the
@@ -202,6 +238,17 @@ export default function onlyne(pi: ExtensionAPI) {
             details: params.details,
             files: params.files,
           });
+          // The client that had already settled this task answers with its own
+          // record, and the sentence says so rather than claiming a completion
+          // this call did not cause.
+          if (result.alreadySettled) {
+            const settled = result.alreadySettled;
+            const head = settled.head ? `: ${settled.head}` : "";
+            return textResult(
+              `task already settled as ${settled.state} at ${settled.settled_at}${head} — this call changed nothing`,
+              { outcome: result.outcome, alreadySettled: settled }
+            );
+          }
           // The outcome and nothing else: the ledger's head stays a display
           // field (docs/v2-CONTRACT.md §3c), and the task's identity is not a
           // fact the model is meant to hold.
@@ -226,7 +273,9 @@ export default function onlyne(pi: ExtensionAPI) {
           text: Type.String({ description: "handoff text for the receiving role" }),
           image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
         }),
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+          const caller = sessionIdOf(ctx?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) refuseForeignSession(caller);
           if (!agent) throw new Error("onlyne: session is not connected");
           const result = await agent.handoffFromTool({
             to: params.to,
@@ -246,6 +295,17 @@ export default function onlyne(pi: ExtensionAPI) {
       pi.registerCommand("onlyne", {
         description: "Onlyne session status: connection, task, reports",
         handler: async (argLine, commandContext) => {
+          // The command drives this plugin's connection, so it belongs to the
+          // bound session for the same reason the tools do: a sidechain that
+          // issued `/onlyne disconnect` would detach the real session.
+          const caller = sessionIdOf(commandContext?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) {
+            commandContext.ui.notify(
+              foreignSessionRefusal(boundSessionId, caller),
+              "info"
+            );
+            return;
+          }
           if (!agent) {
             commandContext.ui.notify("onlyne: no session (ONLYNE_* env is absent)", "info");
             return;
@@ -270,9 +330,22 @@ export default function onlyne(pi: ExtensionAPI) {
   };
 
   pi.on("session_start", async (_event, ctx) => {
-    context = ctx;
     const identity = sessionIdentity(env);
     if (!identity) return; // not an onlyne session: stay out of the way
+    // Only the session the client names may mount. A pi process runs more than
+    // one session — a `task` subagent's sidechain, `/new` — and each of them
+    // loads this extension with the same inherited environment, so without this
+    // check a subagent's `onlyne_complete` settles the parent's task (observed:
+    // librarian task cfa73386). An unknown id means an older pi that does not
+    // expose one; the env-bound mount is then the only candidate and stays the
+    // behaviour, with no line to explain.
+    const starting = sessionIdOf(ctx.sessionManager);
+    if (!mountsSession(identity.sessionId, starting)) {
+      log(`session ${starting} is not the onlyne session ${identity.sessionId}; staying inert`);
+      return;
+    }
+    context = ctx;
+    boundSessionId = identity.sessionId;
     const config = loadConfig(ctx.cwd);
     if (config.warning) log(config.warning);
     if (!config.enabled) {
@@ -351,5 +424,6 @@ export default function onlyne(pi: ExtensionAPI) {
     surface = null;
     registered = false;
     context = null;
+    boundSessionId = null;
   });
 }

package/src/session-scope.mjs

@@ -0,0 +1,90 @@
+// One question, asked twice: is the session in front of us the one the client
+// spawned this process for?
+//
+// A pi process runs more than one session. The client spawns pi with
+// `--session-id <the delivery's session>` and injects `ONLYNE_*` into the
+// process environment, and pi then runs other sessions inside that same process
+// with the same environment: a `task` subagent's sidechain
+// (`@tintinweb/pi-subagents` re-binds every extension for the child,
+// `session.bindExtensions`), and `/new`. Each of those loads this extension and
+// sees the parent's `ONLYNE_SESSION_ID`, so a rule that read the environment
+// alone would mount a second connection for the parent's session and let a
+// subagent's `onlyne_complete` settle the parent's task — which is exactly what
+// happened live (librarian task cfa73386, 2026-08-11: a writer subagent settled
+// its parent at 05:15:47 while the parent kept writing).
+//
+// So the rule is the session's own id, read off the pid pi gave the handler, and
+// the environment is only the expectation it is measured against. The two
+// readings are separate on purpose: `mountsSession` is the door (does this
+// session get a connection and the tools at all), `ownsSession` is the guard
+// behind it (may this caller's tool call move the task), and a pi that cannot
+// report a session id at all is the one case where both answer yes — refusing
+// every call on an older pi would break the ordinary session to prevent nothing,
+// because the env-bound mount is still the only one that connected.
+
+/**
+ * The id of the session a pi extension context belongs to.
+ *
+ * `null` means this pi cannot tell — no `sessionManager`, or one without
+ * `getSessionId` — which is the honest reading of an unknown, and both rules
+ * below treat it as "allowed" for the reason in the header.
+ *
+ * @param {{ getSessionId?: () => unknown } | null | undefined} sessionManager
+ * @returns {string | null}
+ */
+export function sessionIdOf(sessionManager) {
+  try {
+    const id = sessionManager?.getSessionId?.();
+    return typeof id === "string" && id.length > 0 ? id : null;
+  } catch {
+    // A context that throws is a context this plugin cannot read; the caller
+    // gets the same answer as one that is absent.
+    return null;
+  }
+}
+
+/**
+ * Whether the session pi is starting is the one the client spawned this process
+ * for, and therefore whether it may mount.
+ *
+ * @param {string} identitySessionId `ONLYNE_SESSION_ID`, the client's own word
+ * @param {string | null} startingSessionId the session's own id, or `null`
+ * @returns {boolean}
+ */
+export function mountsSession(identitySessionId, startingSessionId) {
+  return startingSessionId === null || startingSessionId === identitySessionId;
+}
+
+/**
+ * Whether a call comes from the session that mounted this plugin.
+ *
+ * The guard behind the tools and the `/onlyne` command: a sidechain that reached
+ * a tool through its parent's registration must not settle the parent's task,
+ * and the sentence it earns says so rather than reporting an outcome nobody
+ * asked this session for.
+ *
+ * @param {string | null} boundSessionId the session that mounted, or `null`
+ *   before one has
+ * @param {string | null} callingSessionId the session the call came from
+ * @returns {boolean}
+ */
+export function ownsSession(boundSessionId, callingSessionId) {
+  if (callingSessionId === null) return true;
+  return boundSessionId !== null && callingSessionId === boundSessionId;
+}
+
+/**
+ * The one sentence a call from a foreign session earns, for a tool error and for
+ * a command notice alike.
+ *
+ * @param {string | null} boundSessionId
+ * @param {string | null} callingSessionId
+ * @returns {string}
+ */
+export function foreignSessionRefusal(boundSessionId, callingSessionId) {
+  return (
+    `onlyne: session ${callingSessionId} did not mount these tools; they belong to onlyne ` +
+    `session ${boundSessionId}, and a subagent or another session in the same pi process ` +
+    `must not settle this task`
+  );
+}

package/src/session-scope.test.mjs

@@ -0,0 +1,61 @@
+// The rule that keeps a pi subagent from settling its parent's task, and the
+// sentence a foreign caller reads. The live defect these pin: a `task` subagent
+// runs a sidechain in the same pi process with the same inherited environment,
+// so it saw the parent's `ONLYNE_SESSION_ID` and its `onlyne_complete` settled
+// the parent's task (librarian cfa73386, 2026-08-11).
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  foreignSessionRefusal,
+  mountsSession,
+  ownsSession,
+  sessionIdOf,
+} from "./session-scope.mjs";
+
+const PARENT = "a379b47d-65b7-49c3-ad4b-b978cdf5a5d3";
+const SIDECHAIN = "4f1cb760-c254-4ea1-9d55-6f2a1c8bb0e1";
+
+test("the session id is read off the manager, and an unreadable one reads as unknown", () => {
+  assert.equal(sessionIdOf({ getSessionId: () => PARENT }), PARENT);
+  assert.equal(sessionIdOf({}), null, "no accessor, no id");
+  assert.equal(sessionIdOf(undefined), null);
+  assert.equal(sessionIdOf({ getSessionId: () => "" }), null, "an empty id names nothing");
+  assert.equal(sessionIdOf({ getSessionId: () => 7 }), null, "a non-string id is not one");
+  assert.equal(
+    sessionIdOf({
+      getSessionId: () => {
+        throw new Error("stale context");
+      },
+    }),
+    null,
+    "a context that throws is one this plugin cannot read",
+  );
+});
+
+test("only the session the client named mounts, and an unknown id does not stop the mount", () => {
+  assert.equal(mountsSession(PARENT, PARENT), true, "the spawned session is the one");
+  assert.equal(mountsSession(PARENT, SIDECHAIN), false, "a subagent sidechain is not");
+  assert.equal(
+    mountsSession(PARENT, null),
+    true,
+    "an older pi that cannot say which session this is keeps the env-bound mount",
+  );
+});
+
+test("a call is the bound session's unless pi names another session", () => {
+  assert.equal(ownsSession(PARENT, PARENT), true);
+  assert.equal(ownsSession(PARENT, SIDECHAIN), false, "the sidechain must not settle the parent");
+  assert.equal(ownsSession(PARENT, null), true, "a caller this pi cannot identify is allowed");
+  assert.equal(
+    ownsSession(null, SIDECHAIN),
+    false,
+    "a runner with no bound session has no session whose calls are its own",
+  );
+});
+
+test("the refusal names both sessions and why the call is refused", () => {
+  const sentence = foreignSessionRefusal(PARENT, SIDECHAIN);
+  assert.ok(sentence.includes(SIDECHAIN), sentence);
+  assert.ok(sentence.includes(PARENT), sentence);
+  assert.ok(sentence.includes("subagent"), sentence);
+});