opencode-superagent 0.2.0 → 0.2.1

package/README.md

@@ -85,6 +85,14 @@ opencode plugin add opencode-superagent
 
 4. 重启 TUI，确认插件加载成功。
 
+### 升级与重启（不支持热加载）
+
+插件没有热加载：改完 `src/` / `server.ts` 或换掉 npm 包版本后，必须**重启 OpenCode 网关**（`opencode service restart`，本仓库可用 `sh restart-service.sh`）才会加载新代码；只重启 TUI 或重开窗口不会更新后台服务。
+
+- 启动日志会打印一行 `superagent <version> loaded; restart the OpenCode gateway after upgrading (no hot reload)`，只含版本号，不含路径、配置、token 或会话信息。
+- `status` 工具输出的首行、以及 `status` RPC 的 `version` 字段，都会给出当前**已加载**的插件版本；升级后这里若还是旧版本，说明网关没重启。
+- 排查顺序：日志里的版本 → `status` 首行 → `opencode service status`。三者一致仍行为异常时，再怀疑代码本身。
+
 ## 使用
 
 - 输入 `/superagent`（或在命令面板执行 `Superagent`）：通过 RPC 创建/获取 Router 会话并跳转过去。
@@ -156,7 +164,7 @@ Router 的 system prompt 里只有短摘要（Inline）：worker 数量、pendin
 - 去重：`dedupeKey` 缺省为 `sha1(source + threadID + 归一化 objective)`，建单前在同 thread 找 `open/in_progress` 的同键单，命中则返回原单并标 `reused=true`。
 - authorization：自动取 Router 最近一次被投递的 trigger（`triggerID` + 原文摘要 ≤300 字），所以每张单都能追溯「用户当时怎么说的」。
 - 存储：`ticket:<id>` 存全量记录；`ticketidx:status:<state>`、`ticketidx:thread:<threadID>`、`ticketidx:all` 是按 createdAt 倒序的派生索引（各截断 200 项）。hydrate 扫 `ticket:` 前缀重建内存与索引，索引丢失不会丢单；历史 Worker 不回填工单。
-- 强制：`dispatch` 的 `ticketID` 必填（工具与 RPC 同一实现）。缺失、单据不存在、单据已关闭（非 `open/in_progress`）、`threadID` 与单据不符、或单据已绑定运行中的 Worker，一律拒绝并给出可操作提示；RPC 直达同样被拦。
+- 强制：`dispatch` 的 `ticketID` 必填，工单门禁只作用于 **Router 的工具调用**——工具拿得到宿主的 `context.sessionID`，能证明调用方就是 Router。RPC 的 `dispatch` / `stop` 属于 fail-closed：RPC 上下文里没有调用方身份，伪造 `caller`/`routerID` 也没用，所以两者一律以 `dispatch.rejected` / `stop.rejected` 拒绝（`dispatch` 不会建会话、`stop` 不会中断 Worker），见下面「RPC 接口」。工具路径上的拒绝规则：缺失单据、单据不存在、单据已关闭（非 `open/in_progress`）、`threadID` 与单据不符、或单据已绑定运行中的 Worker，都会给出可操作提示。
 - 联动：派发成功即原子绑定——写入 `workerSessionID`、`attempts` 追加一条、`state → in_progress`；绑定失败会回滚新建的 Worker 会话（不会出现「Worker 起来了但单没绑上」）。Worker prompt 头部附「工单 + objective + acceptance」；Worker `done/failed` 由 watcher 结单，`abort_session` 关闭为 `failed`；watchdog 只告警，不改状态也不结单。
 
 ## 侧栏工单面板
@@ -264,6 +272,7 @@ context.ui.slot({ append: "sidebar.content", render: () => <SidebarTickets conte
 .                              # 仓库根即本包
 ├── tui.tsx                      # TUI 入口：keymap、slash 命令、RPC 调用、侧栏工单面板
 ├── src/protocol.ts              # 服务端 RPC 契约（由服务端实现提供）
+├── src/version.ts               # 从 package.json 读插件版本（带 fallback），生成启动/status 的版本提示
 ├── src/ticket-view.ts           # 侧栏面板的纯视图模型：解析 tickets 文本、排序、按 cell 截断
 ├── src/agents.ts                # Router/Worker agent 的程序化注册（插件 setup 调用）
 ├── src/                          # 服务端 Router/Worker/批处理实现
@@ -278,13 +287,15 @@ context.ui.slot({ append: "sidebar.content", render: () => <SidebarTickets conte
 └── README.md
 ```
 
-TUI 侧只依赖 `src/protocol.ts` 导出的 `Definition`（`id: "opencode.superagent"`）与 `src/tools.ts` 的工具目录（`/tools` 直接渲染它，不发 RPC），当前使用六个方法：
+TUI 侧只依赖 `src/protocol.ts` 导出的 `Definition`（`id: "opencode.superagent"`）与 `src/tools.ts` 的工具目录（`/tools` 直接渲染它，不发 RPC）。服务端注册的就是同一个 `Definition` 对象（`server.ts` 的 `ServerDefinition = Definition`），所以方法、入参/出参和声明错误两边不会漂移。TUI 实际调用六个方法：
 
 - `router({}) -> { sessionID }`：创建或返回 Router 会话。
-- `status({}) -> { router?, pending, workers }`：查看 Router 与各 Worker 的 thread 归属，演示命令用它等待 `T-1` 的 Worker 就绪。
+- `status({}) -> { version?, router?, pending, workers }`：`version` 是当前网关加载的插件版本（启动日志里也有），Router 尚未创建时不带 `router` 字段；演示命令用它等待 `T-1` 的 Worker 就绪。
 - `trigger({ source, threadID, author?, text, title?, createdAt?, id? }) -> { route, sessionID? }`：注入一条事件，`route` 为 `router` / `worker` / `dropped`。
 - `abort({ sessionID?, reason?, all?, stale? }) -> { text }`：终止/清理 Worker，被拒绝时抛 `abort.rejected`（带可读 message）。TUI 的 `/abort`（或命令面板 “Superagent abort worker”）会列出 Worker 供选择，首项是“清理全部已结束 worker”。
-- `tickets({ threadID?, status?, limit? }) -> { text }` / `ticket({ ticketID }) -> { text }`：渲染工单列表（按状态分组，窄终端友好）与单张工单的详情；对应 `/tickets` 与 `/ticket <id>`。
+- `tickets({ threadID?, status?, limit? }) -> { text }` / `ticket({ ticketID }) -> { text }`：渲染工单列表（按状态分组，窄终端友好）与单张工单的详情；对应 `/tickets` 与 `/ticket <id>`。`status` 是闭合枚举，传非法值（如 `DONE`、拼写错误）会直接被协议校验拒绝，不会退化成“不过滤的完整列表”；服务端另有 `tickets.invalid_status` 作为第二道防线。
+
+契约里还声明了 `dispatch` 与 `stop`：两者只给 Router 的工具使用，**RPC 调用一律 fail-closed**。RPC 传输层不提供调用方 session（`RpcCallContext` 只有 `error`），入参里的 `caller`/`routerID` 可伪造（router id 在 `status` 里公开），因此 `dispatch` 固定返回 `dispatch.rejected`、`stop` 固定返回 `stop.rejected`，既不会建 Worker 也不会中断 Worker。这两个错误与其他方法一样声明在共享 `Definition` 里，server 与 TUI 读同一份定义；真正的 Router 通过工具干活，工具的 `context.sessionID` 由宿主提供，是唯一被信任的身份来源。
 
 ## 已知限制与下一步
 
@@ -334,4 +345,4 @@ npm pack --dry-run     # 预览 tarball（prepack/prepare 会各跑一次 build
 - **只告警不自动杀**：停滞后向 Router 注入一条 delivery `queue` 的提示（`Worker <sid>（<title>）已停滞 <N> 分钟，建议：stop 后重派或人工介入`）。不修改 Worker 的 `state`/`lastReport`，不结单，也不 interrupt；同一繁忙窗口只告警一次，避免误杀长任务和重复刷屏。
 - **单轮错误隔离**：单个 Worker 检查失败只 `logWarning` 并继续下一个；整轮失败也只告警，循环永不退出。
 - **pending 队列崩溃恢复**：入队时同步写 KV（键前缀 `pending:`，纯 JSON），flush 成功后删除该键；setup 时从 KV 读回未 flush 的 trigger 重新入内存队列（不自动建 Router，等下一次 `router` RPC 或新 trigger 时再 flush）。同一 id 重复入队会被去重。
-- **status 无 Router**：Router 尚未创建时 `status` 返回 `{pending, workers}` 且不含 `router` 字段（显式 `undefined` 会导致输出校验失败，故直接省略该键）。
+- **status 无 Router**：Router 尚未创建时 `status` 返回 `{version, pending, workers}` 且不含 `router` 字段（显式 `undefined` 会导致输出校验失败，故直接省略该键）。`version` 始终存在，是当前网关加载的插件版本。

package/dist/server.d.ts

@@ -1,28 +1,28 @@
 import { Plugin } from "@opencode/plugin/effect";
 import type { RpcHandlers } from "@opencode/plugin/effect/rpc";
-import { Schema } from "effect";
 /**
- * The RPC surface this server registers. `stop` gains its rejection error here
- * rather than in the shared TUI contract: only the server refuses router-only
- * calls, and the TUI never calls `stop`.
+ * The RPC surface this server registers. It is the shared `Definition` object
+ * itself, not a copy: `stop.rejected` and `dispatch.rejected` live in
+ * `src/protocol.ts`, which is also what the TUI imports, so the server and the
+ * TUI can never advertise different errors.
  */
 export declare const ServerDefinition: {
     readonly id: "opencode.superagent";
-    readonly events: {};
     readonly methods: {
-        readonly router: {
-            input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+        router: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly sessionID: string;
             }, {
                 readonly sessionID: string;
-            }> & Schema.Struct<{
-                readonly sessionID: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
             }>;
         };
-        readonly status: {
-            input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+        status: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly version?: string | undefined;
                 readonly router?: string | undefined;
                 readonly pending: number;
                 readonly workers: readonly {
@@ -32,6 +32,7 @@ export declare const ServerDefinition: {
                     readonly state: "aborted" | "done" | "failed" | "idle" | "running";
                 }[];
             }, {
+                readonly version?: string | undefined;
                 readonly router?: string | undefined;
                 readonly pending: number;
                 readonly workers: readonly {
@@ -40,18 +41,19 @@ export declare const ServerDefinition: {
                     readonly threads: readonly string[];
                     readonly state: "aborted" | "done" | "failed" | "idle" | "running";
                 }[];
-            }> & Schema.Struct<{
-                readonly router: Schema.optionalKey<Schema.String>;
-                readonly pending: Schema.Number;
-                readonly workers: Schema.$Array<Schema.Struct<{
-                    readonly sessionID: Schema.String;
-                    readonly title: Schema.optionalKey<Schema.String>;
-                    readonly threads: Schema.$Array<Schema.String>;
-                    readonly state: Schema.Literals<readonly ["running", "idle", "failed", "done", "aborted"]>;
+            }> & import("effect/Schema").Struct<{
+                readonly version: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly router: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly pending: import("effect/Schema").Number;
+                readonly workers: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly title: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                    readonly threads: import("effect/Schema").$Array<import("effect/Schema").String>;
+                    readonly state: import("effect/Schema").Literals<readonly ["running", "idle", "failed", "done", "aborted"]>;
                 }>>;
             }>;
         };
-        readonly tickets: {
+        tickets: {
             input: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly threadID?: string | undefined;
                 readonly status?: "blocked" | "cancelled" | "done" | "failed" | "in_progress" | "open" | "superseded" | undefined;
@@ -60,45 +62,45 @@ export declare const ServerDefinition: {
                 readonly threadID?: string | undefined;
                 readonly status?: "blocked" | "cancelled" | "done" | "failed" | "in_progress" | "open" | "superseded" | undefined;
                 readonly limit?: number | undefined;
-            }> & Schema.Struct<{
-                readonly threadID: Schema.optionalKey<Schema.String>;
-                readonly status: Schema.optionalKey<Schema.Literals<readonly ["open", "in_progress", "blocked", "done", "failed", "cancelled", "superseded"]>>;
-                readonly limit: Schema.optionalKey<Schema.Number>;
+            }> & import("effect/Schema").Struct<{
+                readonly threadID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly status: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["open", "in_progress", "blocked", "done", "failed", "cancelled", "superseded"]>>;
+                readonly limit: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
             }>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly text: string;
             }, {
                 readonly text: string;
-            }> & Schema.Struct<{
-                readonly text: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly text: import("effect/Schema").String;
             }>;
             errors: {
                 "tickets.invalid_status": import("effect/StandardSchema").StandardSchemaV1<{
                     readonly status: string;
                 }, {
                     readonly status: string;
-                }> & Schema.Struct<{
-                    readonly status: Schema.String;
+                }> & import("effect/Schema").Struct<{
+                    readonly status: import("effect/Schema").String;
                 }>;
             };
         };
-        readonly ticket: {
+        ticket: {
             input: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly ticketID: string;
             }, {
                 readonly ticketID: string;
-            }> & Schema.Struct<{
-                readonly ticketID: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly ticketID: import("effect/Schema").String;
             }>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly text: string;
             }, {
                 readonly text: string;
-            }> & Schema.Struct<{
-                readonly text: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly text: import("effect/Schema").String;
             }>;
         };
-        readonly dispatch: {
+        dispatch: {
             input: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly task: string;
                 readonly title?: string | undefined;
@@ -113,26 +115,26 @@ export declare const ServerDefinition: {
                 readonly agent?: string | undefined;
                 readonly directory?: string | undefined;
                 readonly ticketID: string;
-            }> & Schema.Struct<{
-                readonly task: Schema.String;
-                readonly title: Schema.optionalKey<Schema.String>;
-                readonly threadID: Schema.optionalKey<Schema.String>;
-                readonly agent: Schema.optionalKey<Schema.String>;
-                readonly directory: Schema.optionalKey<Schema.String>;
-                readonly ticketID: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly task: import("effect/Schema").String;
+                readonly title: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly threadID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly agent: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly directory: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly ticketID: import("effect/Schema").String;
             }>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly sessionID: string;
             }, {
                 readonly sessionID: string;
-            }> & Schema.Struct<{
-                readonly sessionID: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
             }>;
             errors: {
-                "dispatch.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+                "dispatch.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
             };
         };
-        readonly trigger: {
+        trigger: {
             input: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly id?: string | undefined;
                 readonly source: string;
@@ -149,14 +151,14 @@ export declare const ServerDefinition: {
                 readonly text: string;
                 readonly title?: string | undefined;
                 readonly createdAt?: number | undefined;
-            }> & Schema.Struct<{
-                readonly id: Schema.optionalKey<Schema.String>;
-                readonly source: Schema.String;
-                readonly threadID: Schema.String;
-                readonly author: Schema.optionalKey<Schema.String>;
-                readonly text: Schema.String;
-                readonly title: Schema.optionalKey<Schema.String>;
-                readonly createdAt: Schema.optionalKey<Schema.Number>;
+            }> & import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly source: import("effect/Schema").String;
+                readonly threadID: import("effect/Schema").String;
+                readonly author: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly text: import("effect/Schema").String;
+                readonly title: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly createdAt: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
             }>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly route: "dropped" | "router" | "worker";
@@ -164,12 +166,31 @@ export declare const ServerDefinition: {
             }, {
                 readonly route: "dropped" | "router" | "worker";
                 readonly sessionID?: string | undefined;
-            }> & Schema.Struct<{
-                readonly route: Schema.Literals<readonly ["router", "worker", "dropped"]>;
-                readonly sessionID: Schema.optionalKey<Schema.String>;
+            }> & import("effect/Schema").Struct<{
+                readonly route: import("effect/Schema").Literals<readonly ["router", "worker", "dropped"]>;
+                readonly sessionID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
             }>;
         };
-        readonly abort: {
+        stop: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly interrupted: boolean;
+            }, {
+                readonly interrupted: boolean;
+            }> & import("effect/Schema").Struct<{
+                readonly interrupted: import("effect/Schema").Boolean;
+            }>;
+            errors: {
+                "stop.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            };
+        };
+        abort: {
             input: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly sessionID?: string | undefined;
                 readonly reason?: string | undefined;
@@ -180,43 +201,25 @@ export declare const ServerDefinition: {
                 readonly reason?: string | undefined;
                 readonly all?: boolean | undefined;
                 readonly stale?: boolean | undefined;
-            }> & Schema.Struct<{
-                readonly sessionID: Schema.optionalKey<Schema.String>;
-                readonly reason: Schema.optionalKey<Schema.String>;
-                readonly all: Schema.optionalKey<Schema.Boolean>;
-                readonly stale: Schema.optionalKey<Schema.Boolean>;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly reason: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly all: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+                readonly stale: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
             }>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly text: string;
             }, {
                 readonly text: string;
-            }> & Schema.Struct<{
-                readonly text: Schema.String;
+            }> & import("effect/Schema").Struct<{
+                readonly text: import("effect/Schema").String;
             }>;
             errors: {
-                "abort.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
-            };
-        };
-        readonly stop: {
-            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
-                readonly sessionID: string;
-            }, {
-                readonly sessionID: string;
-            }> & Schema.Struct<{
-                readonly sessionID: Schema.String;
-            }>;
-            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
-                readonly interrupted: boolean;
-            }, {
-                readonly interrupted: boolean;
-            }> & Schema.Struct<{
-                readonly interrupted: Schema.Boolean;
-            }>;
-            readonly errors: {
-                readonly "stop.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+                "abort.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
             };
         };
     };
+    readonly events: {};
 };
 type ServerRpcHandlers = RpcHandlers<typeof ServerDefinition>;
 /**

package/dist/server.js

@@ -1,5 +1,5 @@
 import { Plugin, Rpc } from "@opencode/plugin/effect";
-import { Effect, Schema } from "effect";
+import { Effect } from "effect";
 import { registerAbort, runAbort } from "./src/abort.js";
 import { registerAgents } from "./src/agents.js";
 import { registerContext } from "./src/context.js";
@@ -16,6 +16,7 @@ import { hydrateTickets, TICKET_STATES } from "./src/ticket.js";
 import { registerTicketTools, renderTicketText, renderTicketsText } from "./src/ticket-tools.js";
 import { registerWatcher } from "./src/watcher.js";
 import { registerWatchdog } from "./src/watchdog.js";
+import { pluginVersion, versionNotice } from "./src/version.js";
 const runTrigger = Effect.fn("superagent.runTrigger")(function* (ctx, input) {
     const sources = ctx.options.sources;
     if (Array.isArray(sources) && !sources.includes(input.source))
@@ -55,20 +56,12 @@ const runTrigger = Effect.fn("superagent.runTrigger")(function* (ctx, input) {
     return { route: "router", sessionID: routerID };
 });
 /**
- * The RPC surface this server registers. `stop` gains its rejection error here
- * rather than in the shared TUI contract: only the server refuses router-only
- * calls, and the TUI never calls `stop`.
+ * The RPC surface this server registers. It is the shared `Definition` object
+ * itself, not a copy: `stop.rejected` and `dispatch.rejected` live in
+ * `src/protocol.ts`, which is also what the TUI imports, so the server and the
+ * TUI can never advertise different errors.
  */
-export const ServerDefinition = {
-    ...Definition,
-    methods: {
-        ...Definition.methods,
-        stop: {
-            ...Definition.methods.stop,
-            errors: { "stop.rejected": Schema.toStandardSchemaV1(Schema.Struct({})) },
-        },
-    },
-};
+export const ServerDefinition = Definition;
 /**
  * Router-only RPC methods are rejected unconditionally.
  *
@@ -89,6 +82,9 @@ export const rejectedRouterRpc = {
 export default Plugin.define({
     id: "opencode.superagent",
     effect: Effect.fn(function* (ctx) {
+        // Version only: no paths, options or tokens. Makes a stale gateway obvious
+        // in the log right after an upgrade (the plugin has no hot reload).
+        yield* Effect.logInfo(versionNotice());
         // Tickets first: hydrating workers reconciles finished `running` records
         // and closes their tickets, so the ticket store must already be loaded.
         yield* hydrateTickets(ctx);
@@ -111,6 +107,9 @@ export default Plugin.define({
             .register(ServerDefinition, {
             router: () => ensureRouter(ctx).pipe(Effect.map((sessionID) => ({ sessionID })), Effect.catch((cause) => Effect.logWarning("superagent router handler failed", { cause }).pipe(Effect.andThen(Effect.die(new Error("superagent router is unavailable")))))),
             status: () => Effect.sync(() => ({
+                // Reported alongside the runtime state so the TUI/diagnostics can
+                // show which plugin build the gateway actually loaded.
+                version: pluginVersion(),
                 // Omit the key entirely when no router exists: an explicit
                 // `undefined` value fails output validation.
                 ...(store.routerID === undefined ? {} : { router: store.routerID }),

package/dist/src/dispatch.d.ts

@@ -17,6 +17,12 @@ interface DispatchInput {
     readonly directory?: string;
     readonly ticketID: string;
 }
+/**
+ * Compact status text for the `status` tool and its diagnostics readers.
+ * Starts with the plugin version so a stale gateway (code upgraded but not
+ * restarted) is visible from the first line instead of guessed from behavior.
+ */
+export declare function statusText(): string;
 /**
  * The one dispatch implementation, shared by the `dispatch` tool and the
  * `dispatch` RPC. Both paths pass the same ticket gate: `ticketID` is required

package/dist/src/dispatch.js

@@ -8,6 +8,7 @@ import { superagentMetadata, workerTitle } from "./session-meta.js";
 import { encodeThread, linkTriggerToWorker, saveWorker, store, threadKey, toSessionID, workerKey } from "./state.js";
 import { activeTicketForWorker, activeTicketSummary, closeTicket, currentTrigger, linkTicketToWorker, requireDispatchTicket, ticketStats, } from "./ticket.js";
 import { specFor } from "./tools.js";
+import { pluginVersion } from "./version.js";
 export const DispatchInput = Schema.Struct({
     task: Schema.String,
     title: Schema.optionalKey(Schema.String),
@@ -45,10 +46,16 @@ function workerPrompt(threadID, title, task, ticket) {
     const subject = title === undefined ? "" : `Title: ${title}\n`;
     return `${ticketHeader(ticket)}Thread: ${threadID}\n${subject}Task:\n${task}\n\nEnd with a short report: what changed, how it was verified, remaining risks.`;
 }
-function statusText() {
+/**
+ * Compact status text for the `status` tool and its diagnostics readers.
+ * Starts with the plugin version so a stale gateway (code upgraded but not
+ * restarted) is visible from the first line instead of guessed from behavior.
+ */
+export function statusText() {
     const stats = ticketStats();
     const active = activeTicketSummary(undefined, 5);
     const lines = [
+        `superagent ${pluginVersion()} — restart the gateway after upgrading (no hot reload)`,
         `router: ${store.routerID ?? "none"} pending: ${store.pending.length} workers: ${store.workers.size} tickets: open=${stats.open} in_progress=${stats.inProgress} blocked=${stats.blocked} closed=${stats.closed}`,
     ];
     if (active !== "")

package/dist/src/protocol.d.ts

@@ -1,11 +1,13 @@
 import { Schema } from "effect";
 /**
- * Server-side RPC contract for the Super-agent P0 prototype.
+ * The single RPC contract shared by the server and the TUI.
  *
  * The TUI (`tui.tsx`) calls these methods through `client.rpc(Definition)`,
- * so the id, method names and field names are fixed. Schemas are wrapped
- * with `Schema.toStandardSchemaV1` exactly like `Goal.Definition`, which is
- * what makes the same definition usable from both the Effect server
+ * and `server.ts` registers the very same object (`ServerDefinition =
+ * Definition`), so method names, input/output schemas and declared errors
+ * cannot drift between the two halves. Schemas are wrapped with
+ * `Schema.toStandardSchemaV1` exactly like `Goal.Definition`, which is what
+ * makes the same definition usable from both the Effect server
  * (`ctx.rpc.register`) and the Promise TUI client.
  */
 export declare const Definition: {
@@ -24,6 +26,7 @@ export declare const Definition: {
         status: {
             input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
             output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly version?: string | undefined;
                 readonly router?: string | undefined;
                 readonly pending: number;
                 readonly workers: readonly {
@@ -33,6 +36,7 @@ export declare const Definition: {
                     readonly state: "aborted" | "done" | "failed" | "idle" | "running";
                 }[];
             }, {
+                readonly version?: string | undefined;
                 readonly router?: string | undefined;
                 readonly pending: number;
                 readonly workers: readonly {
@@ -42,6 +46,7 @@ export declare const Definition: {
                     readonly state: "aborted" | "done" | "failed" | "idle" | "running";
                 }[];
             }> & Schema.Struct<{
+                readonly version: Schema.optionalKey<Schema.String>;
                 readonly router: Schema.optionalKey<Schema.String>;
                 readonly pending: Schema.Number;
                 readonly workers: Schema.$Array<Schema.Struct<{
@@ -185,6 +190,9 @@ export declare const Definition: {
             }> & Schema.Struct<{
                 readonly interrupted: Schema.Boolean;
             }>;
+            errors: {
+                "stop.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+            };
         };
         abort: {
             input: import("effect/StandardSchema").StandardSchemaV1<{

package/dist/src/protocol.js

@@ -5,12 +5,14 @@ import { Schema } from "effect";
 // `src/ticket.ts`, so reusing it here keeps the RPC enum from drifting.
 import { TICKET_STATES } from "./ticket-view.js";
 /**
- * Server-side RPC contract for the Super-agent P0 prototype.
+ * The single RPC contract shared by the server and the TUI.
  *
  * The TUI (`tui.tsx`) calls these methods through `client.rpc(Definition)`,
- * so the id, method names and field names are fixed. Schemas are wrapped
- * with `Schema.toStandardSchemaV1` exactly like `Goal.Definition`, which is
- * what makes the same definition usable from both the Effect server
+ * and `server.ts` registers the very same object (`ServerDefinition =
+ * Definition`), so method names, input/output schemas and declared errors
+ * cannot drift between the two halves. Schemas are wrapped with
+ * `Schema.toStandardSchemaV1` exactly like `Goal.Definition`, which is what
+ * makes the same definition usable from both the Effect server
  * (`ctx.rpc.register`) and the Promise TUI client.
  */
 export const Definition = Rpc.define({
@@ -23,6 +25,9 @@ export const Definition = Rpc.define({
         status: {
             input: Schema.toStandardSchemaV1(Schema.Struct({})),
             output: Schema.toStandardSchemaV1(Schema.Struct({
+                // Optional so an older server that predates the version notice still
+                // satisfies the contract; the current server always sends it.
+                version: Schema.optionalKey(Schema.String),
                 router: Schema.optionalKey(Schema.String),
                 pending: Schema.Number,
                 workers: Schema.Array(Schema.Struct({
@@ -55,7 +60,9 @@ export const Definition = Rpc.define({
                 threadID: Schema.optionalKey(Schema.String),
                 agent: Schema.optionalKey(Schema.String),
                 directory: Schema.optionalKey(Schema.String),
-                // Required: the RPC path enforces the same work-order gate as the tool.
+                // Required by the shape, but the RPC handler never runs it: RPC
+                // cannot prove router identity, so `dispatch` fails closed with
+                // `dispatch.rejected` and the router uses its tool instead.
                 ticketID: Schema.String,
             })),
             output: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String })),
@@ -79,6 +86,10 @@ export const Definition = Rpc.define({
         stop: {
             input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String })),
             output: Schema.toStandardSchemaV1(Schema.Struct({ interrupted: Schema.Boolean })),
+            // Declared in the shared contract, not only on the server: the TUI and
+            // the server register the same `Definition`, so a client can tell that
+            // `stop` is router-only without importing server internals.
+            errors: { "stop.rejected": Schema.toStandardSchemaV1(Schema.Struct({})) },
         },
         abort: {
             input: Schema.toStandardSchemaV1(Schema.Struct({

package/dist/src/state.d.ts

@@ -1,27 +1,8 @@
 import type { Plugin } from "@opencode/plugin/effect";
 import type { Session } from "@opencode/schema/session";
 import { Effect, type Schema } from "effect";
-export type WorkerState = "running" | "idle" | "failed" | "done" | "aborted";
-export interface WorkerRecord {
-    readonly sessionID: string;
-    readonly title?: string;
-    /**
-     * Primary thread this worker was dispatched for. Legacy records decode to
-     * `""` and `hydrate` backfills it from `thread.workers`, so every live record
-     * carries a forward link to its thread without losing the multi-thread
-     * `threads` list.
-     */
-    threadID: string;
-    /** Trigger that authorized the dispatch, when the record knows it. */
-    triggerID?: string;
-    readonly threads: Array<string>;
-    state: WorkerState;
-    readonly createdAt: number;
-    /** Last persisted write. Refreshed by `saveWorker`, so an aborted record keeps a traceable timestamp. */
-    updatedAt?: number;
-    lastReport?: string;
-    directory?: string;
-}
+import { type WorkerRecord } from "./worker-state.js";
+export type { WorkerRecord, WorkerState } from "./worker-state.js";
 export interface ThreadRecord {
     readonly threadID: string;
     readonly workers: Array<string>;

package/dist/src/state.js

@@ -1,6 +1,8 @@
 import { DateTime, Effect } from "effect";
 import { buildReport, lastAssistantText, reportSummary, saveReport } from "./report.js";
 import { closeTicketsForWorker } from "./ticket.js";
+import { closeOutcomeForWorkerState } from "./ticket-state.js";
+import { WORKER_STATES, workers } from "./worker-state.js";
 const ROUTES = ["router", "worker"];
 /** Host context for fire-and-forget KV writes from synchronous interception points. Set during hydrate. */
 let persistHost;
@@ -106,7 +108,7 @@ export function upsertDirectTrigger(input, sessionID) {
 export const store = {
     routerID: undefined,
     routerBusy: false,
-    workers: new Map(),
+    workers,
     threads: new Map(),
     pending: new PendingQueue(),
     triggers: new Map(),
@@ -130,7 +132,6 @@ export function isRunning(info) {
     const idle = info.time.idle;
     return idle === undefined || DateTime.toEpochMillis(busy) > DateTime.toEpochMillis(idle);
 }
-const STATES = ["running", "idle", "failed", "done", "aborted"];
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -154,7 +155,7 @@ export function decodeWorker(value) {
         return undefined;
     if (typeof value["sessionID"] !== "string")
         return undefined;
-    if (typeof value["state"] !== "string" || !STATES.includes(value["state"]))
+    if (typeof value["state"] !== "string" || !WORKER_STATES.includes(value["state"]))
         return undefined;
     const threads = stringArray(value["threads"]);
     if (threads === undefined)
@@ -295,11 +296,12 @@ const reconcileRunningWorker = Effect.fn("superagent.reconcileRunningWorker")(fu
         record.lastReport = reportSummary(captured);
     }
     yield* saveWorker(ctx, record);
-    if (state === "done" || state === "failed") {
+    const outcome = closeOutcomeForWorkerState(state);
+    if (outcome !== undefined) {
         yield* closeTicketsForWorker(ctx, {
             sessionID: record.sessionID,
-            outcome: state,
-            summary: record.lastReport ?? report ?? `${state} (worker ${record.sessionID})`,
+            outcome,
+            summary: record.lastReport ?? report ?? `${outcome} (worker ${record.sessionID})`,
         }).pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to close ticket for rehydrated worker", {
             sessionID: record.sessionID,
             cause,