specrune-opencode 0.0.0-stage → 0.9.0

package/src/plugin.ts

@@ -0,0 +1,835 @@
+// SpecRune 的 OpenCode v2 宿主插件（由 OpenCode 以 Bun 加载，无编译步骤）。
+//
+// 落盘在 `.opencode/plugins/specrune.ts`，OpenCode 启动时自动加载该目录下的所有插件，
+// 不需要任何配置挂载。
+//
+// 模块形状与钩子名是 OpenCode v2.0.15 的实测契约，不是文档抄写：
+//   - 模块必须 `export default { id, setup }`，Effect schema 会校验这个形状。
+//   - `setup(ctx)` 收到的是服务注册表（ctx.session / ctx.tool / ctx.shell /
+//     ctx.permission / ctx.aisdk / ctx.rpc …），钩子用 `ctx.<域>.hook(名字, 处理器)`
+//     命令式注册。注册时名字不做校验，名字打错就静默不触发。
+//   - `session/prompt`  ：每条用户发言触发，载荷含 sessionID / prompt.text。
+//   - `session/context` ：每轮组装 LLM 上下文时触发，载荷含 sessionID / agent /
+//     system（{type:"text",text} 块数组）/ messages。往 system **追加**文本块即完成
+//     稳定段注入：前面的块保持逐字节不变，provider 的前缀缓存不受影响
+//     （req:injection-chain#injection-pipeline-hard-constraints）。易变段与 workflow-state 面包屑改走 messages——易变内容
+//     禁入 system，而 messages 的改动只影响当次模型调用、不进持久历史。
+//     messages 的 Message 形状为 { id, role, content:[{type,text}], metadata }，
+//     字段是 `content` **不是** `parts`；push 无运行时校验，写错字段不报错但内容
+//     不会到达模型（静默失效）。见 req:injection-runtime#opencode-rpc-injection。
+//   - `tool/execute.before`：工具调用前触发，载荷含 tool / input，只读审计用。
+//
+// 注入与审计逻辑与具体 OpenCode 版本解耦：钩子名改了只改本文件顶部的注册表，
+// 协议层（分帧、超时、微缓存、降级）不动。
+
+import path from "node:path";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// 二进制定位 + 熔断
+
+// npm 全局安装的 Windows bin 只有 specrune.cmd，没有 .exe；spawn 不能直接执行
+// .cmd（req:backend/npm-distribution#launcher-contract）。win32 下按
+// SPECRUNE_BIN → specrune.exe → specrune.cmd 解析，.cmd 经 cmd.exe 拉起。
+type BinarySpec = { command: string; viaCmd: boolean };
+
+// findOnPath 在 PATH 里找一个存在的文件；名字自带扩展名，不做 PATHEXT 展开。
+// 扫 PATH 而不是 `where`：省一次进程，且宿主启动路径上任何额外进程都要付
+// 控制台闪窗与超时的代价。
+function findOnPath(name: string): string | undefined {
+  const raw = process.env["PATH"] ?? process.env["Path"] ?? "";
+  for (const dir of raw.split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    } catch {
+      // 单个坏目录项不该让整条 PATH 解析失败。
+    }
+  }
+  return undefined;
+}
+
+// npm 平台包映射表是 npm/cli/lib/launcher.js 的 TARGETS 的镜像，那边是唯一出处。
+// 插件落盘在宿主配置目录、包里不带 npm/cli 模板，运行时只能抄一份；漂移由
+// npm/stage.test.mjs 的平台包名断言与安装器同表兜住。
+const NPM_PLATFORM_PACKAGES: Record<string, string> = {
+  "linux-x64": "specrune-linux-x64",
+  "linux-arm64": "specrune-linux-arm64",
+  "darwin-x64": "specrune-darwin-x64",
+  "darwin-arm64": "specrune-darwin-arm64",
+  "win32-x64": "specrune-windows-x64",
+  "win32-arm64": "specrune-windows-arm64",
+};
+
+// 安装器在落盘前把带引号的占位符替换成本机平台二进制的绝对路径。未被替换时
+// （仍以 __ 开头）说明是从源码直接加载、没经过安装器，继续走下一档。
+const BUNDLED_SPECRUNE = "__SPECRUNE_BUNDLED_BIN__";
+
+// .cmd / .bat 在 Windows 上不能直接 spawn，必须经 cmd.exe 拉起。安装器通常注入
+// 原生平台二进制，但 SPECRUNE_BIN 也可能被覆盖成 npm 的 shim，所以按扩展名判定，
+// 不能假设某个来源一定是原生可执行文件。
+function isCmdShim(command: string): boolean {
+  return /\.(?:cmd|bat)$/i.test(command);
+}
+
+// findPlatformPackageBinary 沿自身目录向上找 node_modules 里的平台包。
+// 用纯 fs 查找而不是 createRequire：插件可能被 Bun 以任意路径加载，纯 fs
+// 的向上查找对 npm / pnpm / Bun 的 node_modules 布局都成立。
+//
+// 每层查两处：npm 提升后的 <dir>/node_modules/<pkg>，以及 npm 因版本冲突
+// 塞进 <dir>/node_modules/specrune/node_modules/<pkg> 的嵌套副本。
+function findPlatformPackageBinary(): string | undefined {
+  const pkg = NPM_PLATFORM_PACKAGES[`${process.platform}-${process.arch}`];
+  if (!pkg) return undefined;
+  const binName = process.platform === "win32" ? "specrune.exe" : "specrune";
+  for (let dir = path.dirname(fileURLToPath(import.meta.url)); ; dir = path.dirname(dir)) {
+    for (const base of [dir, path.join(dir, "node_modules", "specrune")]) {
+      const bin = path.join(base, "node_modules", pkg, "bin", binName);
+      try {
+        if (existsSync(bin) && statSync(bin).isFile()) return bin;
+      } catch {
+        // 单个坏目录项不该让整条查找失败。
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+  }
+}
+
+// 定位 specrune 可执行文件。顺序：SPECRUNE_BIN（本地开发期覆盖，与 pi 扩展同名，
+// 见 req:cli-contract#env-contract-table）→ 安装器注入的随包平台二进制 →
+// npm 平台包向上查找 → PATH。
+//
+// viaCmd 只由扩展名决定：注入档与 npm 档通常是原生平台二进制，但 SPECRUNE_BIN
+// 或安装时的覆盖可能指向 .cmd shim，漏判会让 Windows 上的 spawn 直接 EINVAL。
+// win32 的 PATH 回退才需要依次找 specrune.exe、specrune.cmd，都没有时回退
+// specrune.exe 让 spawn 报 ENOENT（保留旧失败形态）。
+function locateSpecruneBinary(): BinarySpec {
+  const fromEnv = (process.env["SPECRUNE_BIN"] || "").trim();
+  if (fromEnv) return { command: fromEnv, viaCmd: isCmdShim(fromEnv) };
+  // 注入路径可能因用户后来删掉依赖而失效；存在性检查让这种情况自然落到下一档，
+  // 而不是每轮 spawn 一个不存在的文件。
+  if (BUNDLED_SPECRUNE && !BUNDLED_SPECRUNE.startsWith("__") && existsSync(BUNDLED_SPECRUNE)) {
+    return { command: BUNDLED_SPECRUNE, viaCmd: isCmdShim(BUNDLED_SPECRUNE) };
+  }
+  const viaNpm = findPlatformPackageBinary();
+  if (viaNpm) return { command: viaNpm, viaCmd: false };
+  if (process.platform !== "win32") return { command: "specrune", viaCmd: false };
+  const exe = findOnPath("specrune.exe");
+  if (exe) return { command: exe, viaCmd: false };
+  const cmd = findOnPath("specrune.cmd");
+  if (cmd) return { command: cmd, viaCmd: true };
+  return { command: "specrune.exe", viaCmd: false };
+}
+
+// spawnSpecrune 按定位结果起进程：.cmd 必须经 cmd.exe /d /s /c 执行，
+// windowsVerbatimArguments 保证路径里的空格不被 Node 的二次转义拆坏。
+function spawnSpecrune(
+  spec: BinarySpec,
+  args: string[],
+  options: Parameters<typeof spawn>[2],
+): ReturnType<typeof spawn> {
+  if (!spec.viaCmd) return spawn(spec.command, args, options);
+  const line = [`"${spec.command}"`, ...args].join(" ");
+  return spawn(process.env["ComSpec"] || "cmd.exe", ["/d", "/s", "/c", `"${line}"`], {
+    ...options,
+    windowsVerbatimArguments: true,
+  });
+}
+
+// killSpecrune 终止一次调用的进程树。.cmd 分支的 child.pid 是 cmd.exe，
+// 只 kill 它会把真正的 specrune 子进程留下；taskkill /pid <pid> /T /F 才是整棵树。
+function killSpecrune(child: ReturnType<typeof spawn>, viaCmd: boolean): void {
+  if (!viaCmd) {
+    try {
+      if (child.exitCode === null) child.kill();
+    } catch {
+      /* 已经死了 */
+    }
+    return;
+  }
+  const pid = child.pid;
+  if (pid === undefined) return;
+  const fallback = (): void => {
+    try {
+      if (child.exitCode === null) child.kill();
+    } catch {
+      /* 已经死了 */
+    }
+  };
+  try {
+    const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+      windowsHide: true,
+      stdio: "ignore",
+    });
+    killer.on("error", fallback);
+  } catch {
+    fallback();
+  }
+}
+
+// 拉起失败几乎总是环境性的（二进制不在 PATH、目录不可写、权限不足），重试不会
+// 变好，而每次重试都在 Agent 的关键路径上。熔断：连续 3 次失败后冷却 30 秒，期间
+// 直接走降级（微缓存 / 跳过注入）。
+const MAX_SPAWN_FAILURES = 3;
+const RETRY_COOLDOWN_MS = 30_000;
+
+// 逐轮上下文走 stdio 帧管道，不走套接字（req:injection-chain#injection-pipeline-hard-constraints）。
+//
+// 不做套接字直连：stdio 管道在 Node 与 Bun 上行为一致，而套接字直连只有 Bun 可行，
+// 两条注入链会因此分叉（req:architecture#injection-bridge-process-shape）。
+//
+// 父子同生共死：不设 detached，子进程绑宿主生命周期，宿主退出即随之退出——detached
+// 全局进程倍增那类事故在结构上不可能发生。
+
+const HEADER_END = "\r\n\r\n";
+
+function encodeFrame(obj: unknown): Buffer {
+  const payload = Buffer.from(JSON.stringify(obj), "utf8");
+  return Buffer.concat([Buffer.from(`Content-Length: ${payload.length}${HEADER_END}`, "utf8"), payload]);
+}
+
+// decodeFrame 从缓冲里解出**一帧**。
+//
+// 返回 undefined 表示半截帧（等更多字节），null 表示头坏了（整条流已废）。
+// per-call 下只读一帧，所以解出即返回，不做「扫完整个缓冲里所有帧」。
+function decodeFrame(buf: Buffer): Record<string, unknown> | undefined | null {
+  const headerEnd = buf.indexOf(HEADER_END);
+  if (headerEnd < 0) return undefined;
+  const m = /Content-Length:\s*(\d+)/i.exec(buf.subarray(0, headerEnd).toString("utf8"));
+  if (!m) return null;
+  const length = parseInt(m[1], 10);
+  const start = headerEnd + HEADER_END.length;
+  if (buf.length < start + length) return undefined;
+  try {
+    return JSON.parse(buf.subarray(start, start + length).toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+// CallFailure 是一次调用没拿到结果的原因。
+//
+// "error" 与其它几种性质不同：它意味着桥**应答了**（最常见是「没有活跃任务」），
+// 属于正常跳过而不是故障——所以消息要单独带出来。
+type CallFailure = "dead" | "timeout" | "error";
+
+// CallResult 承载一次调用的结局：结果 / 子进程已死 / 超时 / 对端报错。
+// message 只在 reason==="error" 时有值。
+type CallResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; reason: CallFailure; message?: string };
+
+// BRIDGE_FALLBACK_MS 是「等不到响应就降级」的兜底，**不是**决定成败的预算。
+//
+// 预算档位表只在 Go 侧（`cli/hookserve.go` 按方法查表，req:architecture#bridge-budget-tiers）：两个宿主共用
+// 同一座桥，预算只能有一个来源。TS 侧另写常数会让兜底抢在档位之前把请求掐掉，
+// 等于把预算又搬回 TS 侧。
+//
+// 它必须大于桥的最高档（800ms），只负责「桥已经没了 / 卡住了」这两种情况。
+const BRIDGE_FALLBACK_MS = 1_500;
+
+// HookBridge 是一次性的注入桥：**每次调用 spawn 一个 `specrune hook-serve` 子进程，
+// 发一帧、读一帧、随即终止**（req:architecture#injection-bridge-process-shape）。
+//
+// 不做常驻：常驻唯一的收益是省掉重复的 `BuildSessionContext`，而缓存 TTL 1s、每轮只调
+// 一次，那个节省从不发生（req:architecture#bridge-no-cache）。per-call 后新进程没有状态。
+//
+// **一次调用只发一帧、只读一帧，所以响应错配在结构上不可能发生**——child 引用、请求表、
+// 按 id 配对、存活探测、跨调用的缓冲累积全都不需要，它们都是为常驻服务的。
+class HookBridge {
+  private failures = 0;
+  private cooldownUntil = 0;
+  // 微缓存：key = repoRoot|agent → 最近一次成功的稳定段。桥不可用或超时时注入降级用它，
+  // Agent 的推理循环不被阻塞（req:architecture#daemon-process-retired / req:architecture#bridge-degradation-contract）。
+  //
+  // 它**不是加速器**（加速器已被 req:architecture#bridge-no-cache 删除），是失败降级路径，
+  // 与「进程内会话上下文缓存」是两回事。
+  private cache = new Map<string, string>();
+
+  call<T>(method: string, params: unknown, root: string): Promise<CallResult<T>> {
+    if (Date.now() < this.cooldownUntil) {
+      return Promise.resolve({ ok: false, reason: "dead" } as CallResult<T>);
+    }
+    return this.exchange<T>(method, params, root);
+  }
+
+  // exchange 完成一次「spawn → 发一帧 → 读一帧 → 终止」。
+  private exchange<T>(method: string, params: unknown, root: string): Promise<CallResult<T>> {
+    return new Promise<CallResult<T>>((resolve) => {
+      let child: ReturnType<typeof spawn>;
+      let viaCmd = false;
+      try {
+        const spec = locateSpecruneBinary();
+        viaCmd = spec.viaCmd;
+        // cwd + SPECRUNE_REPO：桥要知道服务哪个仓库，而它不继承宿主的启动目录
+        // （OpenCode 的 location.directory 可能是子目录）。
+        // detached: false —— 父子同生共死，不做后台进程（req:architecture#injection-bridge-process-shape）。
+        child = spawnSpecrune(spec, ["hook-serve"], {
+          cwd: root,
+          windowsHide: true,
+          stdio: ["pipe", "pipe", "ignore"],
+          detached: false,
+          env: { ...process.env, SPECRUNE_REPO: root },
+        });
+      } catch {
+        this.noteFailure();
+        resolve({ ok: false, reason: "dead" } as CallResult<T>);
+        return;
+      }
+
+      // buf 是**这一次调用**的局部累积，不跨调用：进程随调用而生灭。
+      let buf = Buffer.alloc(0);
+      let settled = false;
+      const finish = (result: CallResult<T>): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        // 读完即毁：关 stdin 让 Go 侧读到 EOF 正常退出，再终止兜底。不留活进程是
+        // per-call 的硬要求（req:architecture#injection-bridge-process-shape）。
+        try {
+          child.stdin?.end();
+        } catch {
+          /* 已关闭 */
+        }
+        killSpecrune(child, viaCmd);
+        resolve(result);
+      };
+      // 超时**必须**计入熔断（req:architecture#bridge-degradation-contract）：这段预算防的是「桥还在但不回话」——卡死、
+      // 死锁、git 探测挂起。只计 spawn 失败的话，这类卡死每轮都重试、永不冷却，
+      // 症状恰好是熔断当初要消灭的「注入时灵时不灵且零报错」。
+      const timer = setTimeout(() => {
+        this.noteFailure();
+        finish({ ok: false, reason: "timeout" } as CallResult<T>);
+      }, BRIDGE_FALLBACK_MS);
+
+      // spawn 失败是异步的：二进制不在 PATH 时若没有 'error' 监听者会变成
+      // 未捕获异常。收到即判本轮失败（下一轮是另一个全新进程）。
+      child.on("error", () => {
+        this.noteFailure();
+        finish({ ok: false, reason: "dead" } as CallResult<T>);
+      });
+      child.stdout?.on("data", (chunk: Buffer) => {
+        buf = Buffer.concat([buf, chunk]);
+        const frame = decodeFrame(buf);
+        if (frame === undefined) return; // 半截帧，等下一块
+        if (frame === null) {
+          // 头解不出来：整条流已废，丢弃它。
+          finish({ ok: false, reason: "dead" } as CallResult<T>);
+          return;
+        }
+        // 桥的 error 是**裸字符串**（不是 JSON-RPC 的那个对象）：hook-serve
+        // 刻意不走守护进程那套带 jsonrpc 字段与令牌的自研协议（req:architecture#injection-bridge-process-shape 无鉴权面）。
+        // 两侧形状不同是设计，不是 bug——所以也绝不能复用 ipc/jsonrpc.go。
+        const err = frame["error"];
+        if (typeof err === "string" && err.length > 0) {
+          finish({ ok: false, reason: "error", message: err } as CallResult<T>);
+          return;
+        }
+        // 整帧交给调用方：响应字段按方法互斥（text / stable+volatile / block），
+        // 与 ipc.SessionContextResult、WorkflowStateResult 的 json tag 一一对应。
+        this.noteSuccess();
+        finish({ ok: true, value: frame as unknown as T });
+      });
+
+      // 桥没给出任何帧就收流了（超预算退出、崩溃、半截帧）——立刻判本轮失败，
+      // 不让宿主干等 BRIDGE_FALLBACK_MS 走完。
+      //
+      // 为什么监听 stdout 的 'close' 而不是子进程的 'exit'：'exit' 可能早于
+      // stdout 排空触发（进程已经死了，管道里的字节还没被父进程读走），那一刻
+      // 判失败会把**已经写完、正在路上的**应答丢掉。'close' 保证排在所有
+      // 'data' 之后，于是顺序是确定的：先 data（拿到应答或拿到 error），
+      // 后 close（什么都没拿到）。settled 标志让两者只有一次生效。
+      child.stdout?.on("close", () => finish({ ok: false, reason: "dead" } as CallResult<T>));
+
+      try {
+        // 刻意不带 jsonrpc / token 字段：hook-serve 协议不含这两样。
+        // id 恒为 1 —— 它只是协议要求的字段，不用于配对（每进程只有一个请求）。
+        child.stdin?.write(encodeFrame({ id: 1, method, params }));
+      } catch {
+        this.noteFailure();
+        finish({ ok: false, reason: "dead" } as CallResult<T>);
+      }
+    });
+  }
+
+  // noteFailure 累计失败并决定是否进入冷却。
+  //
+  // 熔断在 per-call 下**比常驻版更要紧**：常驻版一次会话只 spawn 一次，
+  // per-call 每轮都 spawn——二进制缺失会让每轮都失败，熔断是唯一的止血手段。
+  //
+  // 冷却要**显式告警**而不静默失败：降级还在跑（微缓存 / 跳过），用户看到的
+  // 现象只是「规范好像没生效」，没人知道原因（req:architecture#daemon-lifecycle-retired / req:architecture#bridge-degradation-contract）。
+  //
+  // 告警措辞必须覆盖两类失败：spawn 失败（桥起不来）与超时（桥起来了但不回话）。
+  // 只写「无法启动」的话，超时熔断会打出一条与真实故障相反的日志——排障第一步
+  // 就是错的，这正是本任务要消灭的那类「说反话的降级」。
+  private noteFailure(): void {
+    this.failures += 1;
+    if (this.failures < MAX_SPAWN_FAILURES) return;
+    this.cooldownUntil = Date.now() + RETRY_COOLDOWN_MS;
+    this.failures = 0;
+    const binary = locateSpecruneBinary();
+    process.stderr.write(
+      `[specrune] 警告：注入桥已连续 ${MAX_SPAWN_FAILURES} 次没能应答（启动失败或超时未回），接下来 ` +
+        `${Math.round(RETRY_COOLDOWN_MS / 1000)} 秒内不再重试，规范注入降级为「跳过/微缓存」。\n` +
+        `  排查：① 确认 \`${binary.command}\` 在 PATH 上（可用 SPECRUNE_BIN 指定绝对路径）；\n` +
+        `        ② 手动执行 \`${binary.command} hook-serve\` 看前台报错；\n` +
+        `        ③ 若能启动但经常超时，多半是仓库过大或 git 探测挂起，先复现本条告警再调预算。\n`,
+    );
+  }
+
+  // noteSuccess 清零连续失败计数。
+  //
+  // 为什么必须有：超时是**瞬时**故障（机器某刻繁忙、git 探测偶尔挂起），而
+  // 熔断要判的是「连续失败」。若成功不重置，插件进程活得越久、偶发超时攒得越多，
+  // 总有一天凑满三次就把一个基本健康的桥打进 30 秒冷却——而告警里写的却是
+  // 「连续 3 次」，与事实相反。成功后清零让「连续」名副其实，也让真正卡死的桥
+  // （每轮都超时，没有成功可清）照样在三次后冷却。
+  private noteSuccess(): void {
+    this.failures = 0;
+  }
+
+  cacheKey(repoRoot: string, agent?: string): string {
+    return `${repoRoot}|${agent ?? ""}`;
+  }
+
+  cacheGet(key: string): string | undefined {
+    return this.cache.get(key);
+  }
+
+  // cacheSet 是有界的（16 条）：宿主进程可能长时间不退出，不封顶就是无界增长。
+  cacheSet(key: string, block: string): void {
+    if (this.cache.size > 16) {
+      const first = this.cache.keys().next().value;
+      if (first !== undefined) this.cache.delete(first);
+    }
+    this.cache.set(key, block);
+  }
+}
+
+const client = new HookBridge();
+
+// 插件状态（每个 setup 调用一份；OpenCode 可能按目录多次实例化插件）
+
+// 逐轮注入的预算档位表只存在于 Go 侧 `cli/hookserve.go`（按方法查表）：两个宿主共用
+// 同一座桥，预算只能有一个来源（req:architecture#bridge-budget-tiers）。扩展只保留
+// 「等不到响应就降级」的兜底（BRIDGE_FALLBACK_MS），那不是决定成败的预算值。
+
+// SPECRUNE_PLUGIN_DEBUG 打开后，注入的关键节点各打一行到 stderr。插件跑在宿主进程里，
+// 出问题时唯一的观测口就是宿主日志。
+const DEBUG = process.env["SPECRUNE_PLUGIN_DEBUG"] === "1";
+
+function debug(msg: string): void {
+  if (DEBUG) process.stderr.write(`[specrune] ${msg}\n`);
+}
+
+let bridgeDown = false; // 一轮会话里「注入桥不在」只告警一次，不刷屏
+
+// lastPrompt 暂存本会话最近一条用户 prompt。
+//
+// `workflow.state` 需要 prompt 判定跳过关键字（`prompt_injection.skip_keyword`），而
+// `context` 钩子不携带 prompt——同一会话里只有 `prompt` 钩子拿得到。取不到时按空串传，
+// 跳过关键字判定失效（面包屑照发，不是故障，故不告警）。上限 64 条只为防长会话无界
+// 增长；逐轮覆盖同一 sessionID，实际占用是「活跃会话数」量级。
+const lastPrompt = new Map<string, string>();
+const LAST_PROMPT_LIMIT = 64;
+
+function stashPrompt(sessionID: string, text: string | undefined): void {
+  if (!text) return;
+  if (lastPrompt.size >= LAST_PROMPT_LIMIT) {
+    const oldest = lastPrompt.keys().next();
+    if (!oldest.done) lastPrompt.delete(oldest.value);
+  }
+  lastPrompt.set(sessionID, text);
+}
+
+// INJECTION_SENTINEL 标记「以下内容由 specrune 注入」。
+//
+// 值必须与 Go 侧 `context.go` 的 InjectionSentinel 和 pi 扩展三处逐字一致
+// （req:injection-chain#subagent-dispatch 的跨宿主约定）。
+//
+// 刻意不加在 `<workflow-state>` 面包屑上：那是 workflow 块自己的格式，哨兵会让两处的
+// 存在性判定互相干扰（同 workflow.go）。
+const INJECTION_SENTINEL = "<!-- specrune-hook-injected -->";
+
+// SUBAGENT_SKILL_INSTRUCTION 是子代理会话的兜底技能加载指令
+// （req:subagents#subagent-skill-loading）。OpenCode 没有派发钩子，子代理由宿主
+// Task 工具创建；这里在子代理的 system 段补一条，旧模板或用户自定义模板也能生效。
+// 主会话不会看到它（parentID 判定为子代理才注入）。
+const SUBAGENT_SKILL_INSTRUCTION =
+  "Before acting, load your SpecRune role skill: `specrune-before-dev` for the implement role, `specrune-review` for the check role. Also load any skills named in your dispatch prompt. Use your host's skill tool when it has one; otherwise read `.agents/skills/<name>/SKILL.md` (project) or `~/.agents/skills/<name>/SKILL.md` (global) for each. If any is unavailable, report `<name> skill unavailable` and stop. Research may ignore the role-skill sentence.";
+
+// 易变段**不做**逐轮去重，且这是刻意的——不要照抄 pi 侧的 `lastTurn`。
+//
+// 两个宿主的持久化语义相反，所以同一段代码在一侧是优化、在另一侧是信息丢失：
+//
+//   pi       `before_agent_start` 返回 `{ message }`，是 append-only 消息，**进 transcript
+//            历史**。内容逐字节未变时不再重复投递是对的——历史里已经有一份。
+//
+//   opencode `session/context` 的 `ev.messages` **只影响当次模型调用、不进持久历史**。
+//            于是「未变就不投递」等于**这一轮的上下文里根本没有易变段与面包屑**——
+//            模型会突然失去 git 状态、当前任务和 workflow 引导。这不是省 token，是丢信息。
+//
+// 判据（改动这段之前先答）：**这份内容下一轮还在不在？** 在 → 可以去重；不在 → 去重就是丢信息。
+
+// subagentCache 暂存「会话 → 是否子代理」的判定结果（req:injection-runtime#workflow-state-decision）。
+//
+// 判据是宿主持久化的 parentID：子会话创建时写死、此后不变，所以**确定性的**结论（含
+// 「确认主会话」，parentID 为 NULL）可以按 sessionID 缓存，每会话只付一次 SDK 往返。
+// `session.get` 的异常**不缓存**（不是确定性结论，下一轮重试）；失败方向遵循「宁漏关
+// 不误关」——判不出子代理就按主会话处理。
+const subagentCache = new Map<string, boolean>();
+const SUBAGENT_CACHE_LIMIT = 64;
+
+function cacheSubagentFlag(sessionID: string, isSub: boolean): void {
+  if (subagentCache.size >= SUBAGENT_CACHE_LIMIT) {
+    const oldest = subagentCache.keys().next();
+    if (!oldest.done) subagentCache.delete(oldest.value);
+  }
+  subagentCache.set(sessionID, isSub);
+}
+
+// HostSessionApi 是子代理判定用到的最小宿主 SDK 面（ctx 就是 OpenCode server client，
+// `session.get` 返回 Session.Info；这里只声明消费到的字段）。
+interface HostSessionApi {
+  get?: (args: { sessionID: string }) => Promise<{ parentID?: string } | undefined>;
+}
+
+// resolveSubagent 判定会话是否子代理（宿主派生的独立 session）。
+//
+// 判据用 parentID 而不是 agent 名单：名单会漂移（内置改名、用户自定义），只配做辅助
+// 信号；parentID 是宿主持久化的权威事实。宿主没有 `session.get`（老版本）时按主会话处理。
+async function resolveSubagent(sessionApi: HostSessionApi | undefined, sessionID: string): Promise<boolean> {
+  const cached = subagentCache.get(sessionID);
+  if (cached !== undefined) return cached;
+  if (!sessionApi?.get) return false;
+  try {
+    const info = await sessionApi.get({ sessionID });
+    const isSub = typeof info?.parentID === "string" && info.parentID.length > 0;
+    cacheSubagentFlag(sessionID, isSub);
+    return isSub;
+  } catch (e) {
+    debug(`session.get 失败，按主会话处理：${(e as Error).message}`);
+    return false; // 异常不缓存，下轮重试
+  }
+}
+
+interface PromptEvent {
+  sessionID: string;
+  messageID?: string;
+  prompt?: { text?: string };
+}
+
+interface ContextEvent {
+  sessionID: string;
+  agent?: string;
+  // system 是 {type:"text",text} 块数组；追加块 = 注入，前缀保持逐字节稳定。
+  system: Array<{ type: string; text: string }>;
+  // messages 是本次模型调用的消息数组（形状见文件头）。易变段与面包屑走这里。
+  messages?: Array<{ id?: string; role?: string; content?: Array<{ type: string; text: string }>; metadata?: unknown }>;
+}
+
+// session.context 与 workflow.state 的响应形状（对齐 Go 侧 ipc 包）。
+interface SessionCtxResult {
+  // mode="split" 时两段分列；其余 mode 只有 text。
+  text?: string;
+  stable?: string;
+  volatile?: string;
+  status?: string;
+}
+
+interface WorkflowStateResult {
+  block?: string;
+  skipped?: boolean;
+  status?: string;
+}
+
+interface ToolEvent {
+  tool: string;
+  sessionID?: string;
+  input?: unknown;
+}
+
+// resolveRepoRoot 从起点目录向上找 `.specrune`。
+//
+// OpenCode 的项目目录不保证是仓库根（从子目录启动、monorepo），直接把 cwd
+// 当 repoRoot 会让注入桥回答「这不是一个 SpecRune 项目」——注入静默消失，
+// 而症状看起来像桥坏了。向上走到根为止，找不到就原样返回（交给桥去明确报错，
+// 那条错误比这里猜一个仓库强）。
+// SPECRUNE_REPO 是显式覆盖（与 CLI 同名，见 req:cli-contract#env-contract-table），优先于向上查找。
+function resolveRepoRoot(baseDir: string): string {
+  const start = process.env["SPECRUNE_REPO"] || baseDir;
+  let dir = path.resolve(start);
+  for (;;) {
+    if (existsSync(path.join(dir, ".specrune"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(start);
+    dir = parent;
+  }
+}
+
+// projectDisabled 判定项目是否应完全跳过自动注入。
+//
+// 判据与 Go 侧 specrune.ProjectDisabled 一致：没有 `.specrune/`（非项目）或
+// 根目录存在 `.specrune-disabled`（显式禁用）。标记只影响自动注入与宿主插件；
+// 显式 CLI 命令（task / context / session）由用户主动调用，不受影响。
+function projectDisabled(root: string): boolean {
+  try {
+    if (!statSync(path.join(root, ".specrune")).isDirectory()) return true;
+  } catch {
+    return true;
+  }
+  return existsSync(path.join(root, ".specrune-disabled"));
+}
+
+// warnOnceBridgeDown 一轮会话里只告警一次，不刷屏。
+//
+// 降级必须留日志（req:architecture#daemon-lifecycle-retired / req:architecture#bridge-degradation-contract）：
+// 用户看到的现象只是「规范好像没生效」，没人知道原因就跟没修一样。
+function warnOnceBridgeDown(): void {
+  if (bridgeDown) return;
+  bridgeDown = true;
+  process.stderr.write("[specrune] 注入桥不可用，本轮注入降级（不影响 Agent 运行）\n");
+}
+
+// injectContext 在每轮上下文组装时注入会话上下文。
+//
+// 与 Pi 侧同构：稳定段进 system，易变段与 workflow-state 面包屑进 messages
+// （req:injection-chain#injection-pipeline-hard-constraints：二分在两个宿主上必须一致，否则「前缀稳定」
+// 这条承诺只对 Pi 成立）。
+//
+// 每轮都调是因为任务状态在会话中途可能切换（task start / finish），注入内容必须跟着走。
+// 桥超时或不在时回退微缓存，再不行就跳过——本轮注入失败绝不允许阻断 Agent 的推理循环。
+//
+// sessionApi 是宿主 SDK 面（setup 的 ctx.session），供子代理判定用（req:injection-runtime#workflow-state-decision）：
+// 判定成立时 workflow.state 带 `role: "subagent"`，Go 侧对无指针的子代理渲染 delegated。TS 只传
+// 事实（req:injection-chain#injection-pipeline-hard-constraints），delegated 的语义在 Go/模板侧。
+async function injectContext(
+  ev: ContextEvent,
+  repoRoot: string,
+  sessionApi?: HostSessionApi,
+): Promise<void> {
+  // 会话中途才放上禁用标记时也要停下；setup 时已禁用的项目根本不会注册到这里。
+  if (projectDisabled(repoRoot)) {
+    debug("项目已禁用（缺少 .specrune/ 或存在 .specrune-disabled），跳过注入");
+    return;
+  }
+  try {
+    const params = { repoRoot, contextKey: `opencode_${ev.sessionID}`, platform: "opencode" };
+    // 子代理判定提前：parentID 是权威事实，稳定段和 workflow.state 都要用。
+    // ev.agent 只作 debug 观测，不参与判定（名单会漂移）。
+    const isSub = await resolveSubagent(sessionApi, ev.sessionID);
+    if (isSub) {
+      debug(`子代理判定成立（parentID 非空）session=${ev.sessionID} agent=${ev.agent ?? "-"}`);
+    }
+    // 一次 session.context(mode=split) 拿两段，不分两次调：BuildSessionContext 每次都要跑
+    // git（status / for-each-ref / log），两次调用等于把 git 成本翻倍，而 per-call 之后没有
+    // 进程内缓存可省（req:architecture#bridge-no-cache）。
+    const split = await client.call<SessionCtxResult>("session.context", { ...params, mode: "split" }, repoRoot);
+
+    // ① 稳定段 → system。内容是身份/包/路径，逐轮相同即逐字节稳定，进 system
+    //    不破前缀缓存（req:injection-chain#injection-pipeline-hard-constraints）。桥缺席时回退微缓存。
+    if (Array.isArray(ev.system)) {
+      const key = client.cacheKey(repoRoot);
+      const stable = split.ok ? split.value?.stable : undefined;
+      if (stable) {
+        client.cacheSet(key, stable);
+        ev.system.push({ type: "text", text: `${INJECTION_SENTINEL}\n${stable}` });
+        debug(`注入 STABLE ${Buffer.byteLength(stable, "utf8")} 字节 session=${ev.sessionID}`);
+      } else if (!split.ok && split.reason !== "error") {
+        const cached = client.cacheGet(key);
+        if (cached) {
+          ev.system.push({ type: "text", text: `${INJECTION_SENTINEL}\n${cached}` });
+          debug(`注入 STABLE 微缓存 ${Buffer.byteLength(cached, "utf8")} 字节（split ${split.reason}）`);
+        } else {
+          debug(`跳过 STABLE：${split.reason} 且无微缓存`);
+        }
+      } else if (split.ok) {
+        debug("跳过 STABLE：注入桥返回空段");
+      } else {
+        // dead / timeout / error 三种都要说话：降级可以，静默不行（req:architecture#daemon-lifecycle-retired）。
+        // 「没打这行日志」与「注入了但内容为空」在外部看来是同一件事。
+        debug(`跳过 STABLE：${split.reason}${split.reason === "error" ? `（${split.message ?? ""}）` : ""}`);
+      }
+      if (isSub) {
+        ev.system.push({ type: "text", text: `${INJECTION_SENTINEL}\n${SUBAGENT_SKILL_INSTRUCTION}` });
+        debug(`注入子代理技能兜底 ${Buffer.byteLength(SUBAGENT_SKILL_INSTRUCTION, "utf8")} 字节`);
+      }
+    }
+
+    // ② 易变段 + workflow-state 面包屑 → messages。易变内容禁入 system
+    //    （req:injection-chain#injection-pipeline-hard-constraints）；messages 的改动只影响当次模型调用，不进持久历史。
+    //    无活跃任务时 workflow.state 仍会回 no_task 引导块（req:injection-runtime#opencode-rpc-injection）。
+    if (Array.isArray(ev.messages)) {
+      // 子代理判定已在稳定段前完成；这里只消费 isSub 传 workflow.state 的 role。
+      const wf = await client.call<WorkflowStateResult>("workflow.state", {
+        ...params,
+        // role 只在判定成立时出现：缺省（主会话 / 判定失败降级）= 逐字节现行为。
+        ...(isSub ? { role: "subagent" } : {}),
+        prompt: lastPrompt.get(ev.sessionID) ?? "",
+      }, repoRoot);
+      const parts: string[] = [];
+      if (split.ok && split.value?.volatile) parts.push(split.value.volatile);
+      // 面包屑取一次并就地判空：skipped 的空块不是故障，是「本轮按配置不注入」。
+      // 用三元取值而不是 Boolean(...) 中间别名：别名会切断控制流窄化，迫使后面用 `!`
+      // 断言 `wf.value`（tsc TS2339）。
+      const crumb =
+        wf.ok && wf.value?.block && !wf.value.skipped ? wf.value.block : undefined;
+      if (crumb) parts.push(crumb);
+      const hasBreadcrumb = crumb !== undefined;
+      if (parts.length > 0) {
+        const text = parts.join("\n\n");
+        // 每轮**无条件**投递，不做逐字节去重：ev.messages 不进持久历史，未变而不投递 =
+        // 这一轮的上下文里没有易变段与面包屑。判据见 INJECTION_SENTINEL 上方的注释。
+        ev.messages.push({
+          id: `specrune_${ev.sessionID}_${ev.messages.length}`,
+          role: "user",
+          content: [{ type: "text", text: `${INJECTION_SENTINEL}\n${text}` }],
+          metadata: { specrune: true },
+        });
+        debug(`注入易变段 ${Buffer.byteLength(text, "utf8")} 字节（面包屑 ${hasBreadcrumb ? "有" : "无"}）`);
+      } else {
+        debug(`跳过易变段：volatile=${split.ok ? "空段" : split.reason} 面包屑=${hasBreadcrumb ? "有" : "无"}`);
+      }
+    }
+    if (!split.ok && split.reason !== "error") warnOnceBridgeDown();
+  } catch (e) {
+    process.stderr.write(`[specrune] 注入失败（已跳过本轮）：${(e as Error).message}\n`);
+  }
+}
+
+// parseTicketCommands 从 shell 命令串里识别会话敏感的 specrune 命令。
+//
+// 这是 shell 票据的写端。存在理由：**没有任何被调研的平台会把会话 id 导出到 shell
+// 子进程**——OpenCode 也是。于是 `specrune task start <ref>` 在 OpenCode 的 bash 里
+// 跑时无从得知自己属于哪个会话，任务指针写不到 `opencode_<sessionID>` 名下。钩子恰好
+// 在 shell 命令执行**前**触发，这里是唯一能桥接的时机。
+//
+// 只认显式 `specrune task start/current/finish` 与 `specrune session record`；解析不出
+// 任务引用的 start 不写——票据侧 taskRefsMatch 对空引用本来也判不中。
+//
+// `session record` 在名单里：记录头的 session / platform / task 全靠会话身份，票据是
+// OpenCode 下唯一的通道（Pi 走注入变量因而正常）。
+//
+// 路径前缀不是可选项：Windows 上二进制叫 specrune.exe，且 agent 几乎总是用相对路径调它
+// （bin\specrune.exe）。只认裸 `specrune` 会让 Windows 上的票据桥失效，症状是
+// 「OpenCode 绑不上 session」，与 worktree 缺陷表象相同。
+function parseTicketCommands(command: string): Array<{ name: string; task_ref?: string }> {
+  const out: Array<{ name: string; task_ref?: string }> = [];
+  const re =
+    /\b(?:[^\s;&|]*[\\/])?specrune(?:\.exe)?\s+(?:task\s+(start|current|finish)|session\s+(record))\b(?:\s+([^\s;&|]+))?/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(command)) !== null) {
+    const name = m[1] ?? m[2];
+    if (!name) continue;
+    if (name === "start") {
+      const ref = m[3];
+      if (!ref || ref.startsWith("-")) continue;
+      out.push({ name, task_ref: ref });
+    } else {
+      out.push({ name });
+    }
+  }
+  return out;
+}
+
+// writeShellTicket 在 shell 工具执行前写一张 30 秒票据。
+//
+// 字段与 TTL 必须与 Go 侧 lookupShellTicketContextKey 的读取逻辑逐项一致
+// （.specrune/.runtime/shell-tickets/*.json，TTL 对齐 ShellTicketTTLSeconds）。任何一步
+// 失败都静默退化为「无身份」——那是 task start 会显式报错的状态，不是崩溃状态。
+function writeShellTicket(ev: ToolEvent, repoRoot: string): void {
+  try {
+    if (ev.tool !== "shell" || !ev.sessionID) return;
+    const input = ev.input as { command?: string; workdir?: string } | undefined;
+    if (!input?.command) return;
+    const subs = parseTicketCommands(input.command);
+    if (subs.length === 0) return; // 没有会话敏感的命令就不需要桥接
+    // 只看 `.specrune/` 是否存在：票据服务于显式 CLI 命令（task / session），
+    // 项目被禁用时这些命令仍然可用，因此不能因为 `.specrune-disabled` 就
+    // 掐断它们的会话身份。也不能因为没有 `.specrune/` 就在每个项目里凭空
+    // 制造一个（禁用项目本身已有 `.specrune/`，不受影响）。
+    if (!existsSync(path.join(repoRoot, ".specrune"))) return;
+    const dir = path.join(repoRoot, ".specrune", ".runtime", "shell-tickets");
+    mkdirSync(dir, { recursive: true });
+    const now = Date.now() / 1000;
+    const ticket = {
+      context_key: `opencode_${ev.sessionID}`,
+      platform: "opencode",
+      cwd: input.workdir || repoRoot,
+      created_at_epoch: now,
+      expires_at_epoch: now + 30,
+      subcommands: subs,
+    };
+    const file = path.join(dir, `opencode_${ev.sessionID.replace(/[^\w-]/g, "_")}.json`);
+    writeFileSync(file, JSON.stringify(ticket), "utf8");
+    debug(`写 shell 票据：${subs.map((s) => s.name).join(" / ")}`);
+  } catch {
+    /* 票据是尽力而为：失败退化为无身份，命令侧会显式报错，不会静默错绑 */
+  }
+}
+
+// auditToolCall 只读审计：打到 stderr，由 OpenCode 收进日志。不拦截、不改参。
+function auditToolCall(ev: ToolEvent): void {
+  try {
+    let input = "";
+    try {
+      input = JSON.stringify(ev.input ?? "").slice(0, 200);
+    } catch {
+      input = String(ev.input).slice(0, 200);
+    }
+    process.stderr.write(`[specrune-audit] ${ev.tool} ${input}\n`);
+  } catch {
+    /* 审计是旁路，任何失败都不许影响工具调用 */
+  }
+}
+
+// 插件入口
+
+// 钩子注册在 setup 闭包里而不是模块顶层：OpenCode 可能以不同项目目录多次实例化同一份
+// 插件，repoRoot 必须跟各自的 location.directory 走，共享的只有连接与微缓存。
+const setup = async (ctx: {
+  location?: { directory?: string };
+  session: {
+    hook: (name: string, handler: (ev: any) => Promise<void>) => void;
+    // get 是宿主 SDK 面：`session.get({ sessionID })` 返回 Session.Info（本插件只消费
+    // parentID，req:injection-runtime#workflow-state-decision 子代理判定）。可选：宿主缺它时按主会话处理。
+    get?: (args: { sessionID: string }) => Promise<{ parentID?: string } | undefined>;
+  };
+  tool: { hook: (name: string, handler: (ev: any) => Promise<void>) => void };
+}) => {
+  const baseDir = ctx.location?.directory || process.cwd();
+  // 项目级禁用：没有 .specrune/ 或根目录存在 .specrune-disabled 时完全不注册
+  // SpecRune hook。必须在任何 hook 注册之前返回——否则「不激活」只是不注入，
+  // 宿主里仍留着 prompt/工具审计钩子。
+  if (projectDisabled(resolveRepoRoot(baseDir))) return;
+  const repoRoot = () => resolveRepoRoot(baseDir);
+
+  // 只剩 prompt 暂存：注入桥无常驻实例、协议只有一种形状，没有握手要协商的余地。
+  ctx.session.hook("prompt", async (ev: PromptEvent) => {
+    stashPrompt(ev.sessionID, ev.prompt?.text);
+  });
+
+  ctx.session.hook("context", async (ev: ContextEvent) => {
+    await injectContext(ev, repoRoot(), ctx.session);
+  });
+
+  ctx.tool.hook("execute.before", async (ev: ToolEvent) => {
+    const root = repoRoot();
+    // 会话中途放上标记时 hook 无法注销，但审计（stderr）必须停下。票据仍要写：
+    // task / session 这类显式 CLI 命令不因禁用而失效，OpenCode 的会话身份
+    // 只靠这张票据传递。
+    if (!projectDisabled(root)) auditToolCall(ev);
+    writeShellTicket(ev, root);
+  });
+};
+
+export default {
+  id: "specrune",
+  // 字段名必须是 setup：2.0.15 的加载 schema 只认 id + setup/effect 之一，
+  // 名字写错（比如 dev 分支的 server）整份插件会被静默拒载。
+  setup,
+};