opencode-agora 0.1.0__py3-none-any.whl

opencode_agora-0.1.0.data/data/share/opencode-agora/agora-plugin/index.ts

@@ -0,0 +1,160 @@
+/**
+ * opencode v2.1.4 插件入口——T5 探针实证接线（/tmp/opencode/oc-probe.json）：
+ * 稳定运行时＝plain-object `{id, setup(ctx)}`（async-Hooks 形态静默失效，禁用）；
+ * 钩子＝ctx.session.hook("prompt", ev)（ev {sessionID, prompt:{text}, delivery}）＋
+ * ctx.tool.hook("execute.before", ev)（ev {tool, sessionID, input}——MCP 工具同名覆盖，
+ * tool 名＝"<server>_<tool>"；改 ev.input 直达 MCP 服务端，已实测）。
+ * 会话 cwd＝ctx.session.get({sessionID}).location.directory（异步取，失败回落 process.cwd()）。
+ * 语义与 agorad 服务侧一致：豁免面 B3、读引导、主会话例外、服务不可达默认拒。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getCredential, pullCredential, type PullResult } from "./cred";
+import { onShellCreate, type ShellCreatePayload } from "./envPath";
+import { onInject } from "./inject";
+import {
+  AGORAD_TIMEOUT_MS, agoradUrl, ensureOnce, resetLift, LIFT_RECOVER, type LiftResult,
+} from "./lift";
+import { isDormant } from "./scope";
+import { agoraHome, enforceRelevant, isWriteTool, NO_CRED_HINT, readishGated, shouldBlock } from "./hook";
+
+// 稳定运行时 ctx 本地面类型（只注本插件消费面，不引 @opencode 包）
+interface OcToolEvent {
+  tool: string;
+  sessionID: string;
+  input?: Record<string, unknown>;
+}
+interface OcPromptEvent {
+  sessionID: string;
+  prompt?: { text?: string };
+}
+export interface OcCtx {
+  tool: { hook(name: "execute.before", fn: (ev: OcToolEvent) => Promise<void>): void };
+  session: {
+    hook(name: "prompt", fn: (ev: OcPromptEvent) => Promise<void>): void;
+    get(args: { sessionID: string }): Promise<{ location?: { directory?: string } } | undefined>;
+  };
+  /** v2.2.0 起 shell 工具/终端 spawn 前钩子；旧运行时缺省（可选挂载）。 */
+  shell?: {
+    hook(name: "create.before", fn: (ev: ShellCreatePayload) => void | Promise<void>): void;
+  };
+}
+
+let enforceOverride: boolean | null = null; // 测试/特殊接线显式旗；生产置 null 走服务持旗拉取
+
+export function setEnforce(on: boolean | null): void {
+  enforceOverride = on; // null＝清除显式旗，恢复服务持旗拉取
+}
+
+/** root 牌接管文件（F1 唯一落盘点，0600）；缺失/损坏返回 null（调用方按无牌走安全向）。 */
+function readRootToken(): string | null {
+  try {
+    return readFileSync(join(agoraHome(), ".agora", "root.token"), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** 服务持旗拉取（设计 §5.1 核验面，lift/doctor 接线）：lift 定端口→doctor 查询面读
+ * /health.enforce_on（root 牌接管文件授权）；服务不可达/异常一律 true＝默认拒（安全向）。 */
+async function pullEnforce(): Promise<boolean> {
+  const lift = await ensureOnce();
+  if (!lift.ok) return true;
+  try {
+    const tok = readRootToken();
+    if (tok === null) return true;
+    const r = await fetch(agoradUrl(lift.port, "/health"), {
+      headers: { "X-Agora-Token": tok },
+      signal: AbortSignal.timeout(AGORAD_TIMEOUT_MS),
+    });
+    if (!r.ok) return true;
+    return ((await r.json()) as { enforce_on?: boolean }).enforce_on !== false;
+  } catch {
+    return true;
+  }
+}
+
+export default {
+  id: "agora",
+  setup(ctx: OcCtx): void {
+    ctx.session.hook("prompt", async (event) => {
+      onInject({ sessionID: event.sessionID, text: event.prompt?.text ?? "" });
+    });
+    // F18 worker PATH 补全：shell spawn 前 payload.env 按引用直改（补 ~/.bun/bin、~/.local/bin）；
+    // 旧运行时无 shell 命名空间→可选挂载静默跳过。
+    ctx.shell?.hook("create.before", (event) => onShellCreate(event));
+    ctx.tool.hook("execute.before", async (event) => {
+      // R29：休眠分支短路在 lift/pullEnforce/attach/readGuide 之前——休眠仓零 HTTP 零文件读（除名册缓存）。
+      const isAgora = /^agora_/.test(event.tool);
+      let cwd = process.cwd();
+      try {
+        cwd = (await ctx.session.get({ sessionID: event.sessionID }))?.location?.directory || cwd;
+      } catch {
+        // 会话读取失败按服务 cwd 兜底：envDir 含括判定走 deny 安全向
+      }
+      if (isDormant(cwd)) {
+        // F12 启用域：名册内休眠仓——普通工具直通；agora_* 直接拒（不 ensureOnce，零 HTTP）。
+        if (isAgora) throw new Error("此仓未启用 agora");
+        return;
+      }
+      // 服务不可达默认拒：lift 失败静默，判定链按无凭据走引导；拒因携 resetLift 恢复指引。
+      // 旗按需拉取（T6 评审）：预过滤先行——非引导类工具（MCP/grep 等）零开销直过。
+      // F27：agora_* 附牌面也需 lift 端口（attach 分流拉取），不论 enforce 旗。
+      const on = enforceOverride ?? (enforceRelevant(event.tool) ? await pullEnforce() : false);
+      let lift: LiftResult | null = null;
+      if (on || isAgora) lift = await ensureOnce();
+      if (isAgora && !lift.ok) {
+        // 冷启动（设计 §5.4）：首个 agora_* 调用即拉起 agorad；败态即复位 memo——
+        // 下轮 edit 重探自愈（免重启恢复，兑现 lift.ts LIFT_RECOVER 承诺）。
+        resetLift();
+      }
+      const input = event.input ?? {};
+      const target =
+        (typeof input.filePath === "string" && input.filePath) ||
+        (typeof input.path === "string" && input.path) ||
+        "";
+      let cred = getCredential(event.sessionID);
+      let credSrc = cred ? "cache" : "miss";
+      let pull: PullResult | null = null;
+      // F27 拉取闭合三面：write/readish 判定面（enforce on 才消费凭据）＋agora_* 附牌面
+      // （不论旗——附牌语义独立于判定旗）。节流按 sid，多面共用不重复拉。
+      if (!cred && lift?.ok && (isAgora || (on && (isWriteTool(event.tool) || readishGated(event.tool, target))))) {
+        pull = await pullCredential(event.sessionID, lift.port);
+        if (pull.cred) {
+          cred = pull.cred;
+          credSrc = "pulled";
+        }
+      }
+      // 派发方增强①（2026-10-29）：AGORA_HOOK_DEBUG=1 时 stderr 记判定链触发与凭据
+      // 来源——分诊「钩子没触发」vs「缓存空」两态（2.2.0 病灶）；stderr 入服务日志不污染 TUI。
+      if (process.env.AGORA_HOOK_DEBUG) {
+        process.stderr.write(
+          `[agora-plugin] tool=${event.tool} sid=${event.sessionID} cred=${credSrc} pull=${pull?.reason ?? "-"} enforce=${on}\n`);
+      }
+      // 附牌主案（T5 实证②：改 ev.input 直达 MCP）：仅 agora MCP 工具面附 _token。
+      // F27 attach 分流：缓存/拉取命中的 worker 牌优先；拉取 404＝非 worker 会话→维持
+      // root 牌接管文件（主会话合法路径不动）；节流/不可达/lift 败态→不附牌——绝不落
+      // root（堵破口：worker 冷缓存首调不得以 root 身份行动，task_cancel/enforce 级）。
+      // _sid 携调用者真实会话 id（R25-A：服务登记主会话绑定，拍人注入真会话）。
+      if (isAgora) {
+        const token = cred?.token ?? (pull?.reason === "not_worker" ? readRootToken() : null);
+        if (token) {
+          input._token = token;
+          input._sid = event.sessionID;
+        }
+      }
+      let hint = shouldBlock(event.tool, target, cwd, cred, on, pull?.reason ?? null);
+      if (hint) {
+        // F27 拒因分诊（信息量增量，语义不变）：write 面 NO_CRED_HINT 剩不可达/节流两态
+        // ——404（not_worker）已由裁定 A 镜像路由进 DISPATCH_HINT，真非 worker 附文退役。
+        if (hint === NO_CRED_HINT && pull && pull.reason !== "ok") {
+          const why = pull.reason === "throttled"
+            ? "拉取节流中（30s 窗，稍候重试）"
+            : "agorad 拉取不可达/异常（安全向拒）";
+          hint = `${hint}（${why}）`;
+        }
+        throw new Error(lift && !lift.ok ? `${hint}（${LIFT_RECOVER}；拒因：${lift.reason}）` : hint);
+      }
+    });
+  },
+};

opencode_agora-0.1.0.data/data/share/opencode-agora/agora-plugin/inject.ts

@@ -0,0 +1,49 @@
+/**
+ * inject 事件处理（F4）：session.prompt 钩子（T5 实证形状：event {sessionID, messageID,
+ * prompt:{text}, delivery}）→BOOT 环境位登记＋credential 消息提取→cred 缓存填充。
+ * 消息文本形状与 agorad 侧对齐（task.py dispatch 序）：BOOT 先行（"env: {env}" 登记环境位）、
+ * credential 后至（"[agora] credential {tid}\ntoken: {token}"，envDir 取缓存既有值合流）。
+ * env_dir 来源按最小：沿用缓存既有 envDir（重派换牌不丢环境位），缺省 undefined→hook 走 deny 安全向。
+ * 牌只驻内存缓存（T5 实证：v2.1.4 会话无插件可见落盘目录）；进程重启丢牌由服务侧 recover
+ * reinject 重发兜底。
+ */
+import { cacheCredential, getCredential, type Cred } from "./cred";
+
+export interface OcInject {
+  sessionID: string;
+  text: string;
+}
+
+const CRED_MSG = /\[agora\] credential (\S+)\ntoken: (\S+)/;
+const BOOT_MSG = /\[agora\] (gt-\S+|task-\S+|ag-\S+): /;
+const BOOT_ENV = /^env: (\S+)$/m;
+
+export function onInject(msg: OcInject): void {
+  const boot = BOOT_MSG.exec(msg.text);
+  if (boot) {
+    // BOOT 先行（dispatch 序：create 携 boot prompt→credential inject）：登记任务环境位，
+    // credential 随后合流补 token——缺此步 worker 永远无 envDir＝hook 恒 deny 安全向。
+    const env = BOOT_ENV.exec(msg.text);
+    if (env) {
+      cacheCredential({
+        token: getCredential(msg.sessionID)?.token ?? "",
+        sid: msg.sessionID,
+        role: "worker",
+        tid: boot[1],
+        envDir: env[1],
+      });
+    }
+    return;
+  }
+  const m = CRED_MSG.exec(msg.text);
+  if (!m) return;
+  const [, tid, token] = m;
+  const cred: Cred = {
+    token,
+    sid: msg.sessionID,
+    role: "worker",
+    tid,
+    envDir: getCredential(msg.sessionID)?.envDir,
+  };
+  cacheCredential(cred);
+}

opencode_agora-0.1.0.data/data/share/opencode-agora/agora-plugin/lift.ts

@@ -0,0 +1,161 @@
+/**
+ * lift 服务拉起（F4/设计 §4.8）：探测 $AGORA_HOME/.agora/service.json→任意 HTTP 应答（含 401）
+ ＝就绪；未运行则 detached 拉起 agorad（脱会话新会话，F27；env 带 AGORA_HOME＋AGORA_OC_URL[＋AGORA_OC_PASSWORD]）
+ 轮询至 10s 上限。超时拒因两态：没装（main.py 缺）vs 拉不起（起而不就绪／OC 发现落空）。
+ * T5 实证接线：AGORA_OC_URL 发现源＝$XDG_STATE_HOME/opencode/service.json（serve --service 写
+ {url,password,pid,version}）；API 需 Basic opencode:<password>（oc.py 消费，agorad 只透传）。
+ * script 解析序：opts.script → env AGORAD_SCRIPT → $AGORA_HOME/.agora/agorad/main.py（install
+ 载荷）→ 与插件同仓（dev 布局）——插件独立安装场景不再假定同仓。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { agoraHome } from "./hook";
+
+export class LiftTimeout extends Error {}
+
+export interface LiftOpts {
+  home?: string;
+  script?: string;
+  stateHome?: string; // T5 发现源根（测试注入隔离）
+  timeoutMs?: number; // 真值 10s；测试注入短化
+  intervalMs?: number;
+}
+
+const DEFAULT_SCRIPT = join(import.meta.dir, "..", "agorad", "main.py");
+/** proc 只消费 kill：类型收窄免引 Bun 命名空间（测试桩同形）。 */
+interface Killable {
+  kill(): void;
+}
+
+function readPort(home: string): number | null {
+  try {
+    const sj = JSON.parse(readFileSync(join(home, ".agora", "service.json"), "utf8")) as {
+      port?: unknown;
+    };
+    return typeof sj.port === "number" ? sj.port : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 任意 HTTP 应答（含 401）＝就绪；连接拒/超时＝未起。 */
+async function probe(port: number): Promise<boolean> {
+  try {
+    await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(1000) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** opencode 服务发现（T5）：读 $XDG_STATE_HOME/opencode/service.json → {url,password}。 */
+export function discoverOc(
+  stateHome = process.env.XDG_STATE_HOME || join(homedir(), ".local/state"),
+): { url: string; password?: string } | null {
+  try {
+    const sj = JSON.parse(readFileSync(join(stateHome, "opencode", "service.json"), "utf8")) as {
+      url?: unknown;
+      password?: unknown;
+    };
+    return typeof sj.url === "string" && sj.url
+      ? { url: sj.url, password: typeof sj.password === "string" ? sj.password : undefined }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveScript(opts: LiftOpts, home: string): string {
+  return (
+    opts.script ||
+    process.env.AGORAD_SCRIPT ||
+    join(home, ".agora", "agorad", "main.py") || // install.sh 载荷位（独立安装）
+    DEFAULT_SCRIPT // dev 同仓布局兜底
+  );
+}
+
+export async function ensureService(
+  opts: LiftOpts = {},
+): Promise<{ port: number; proc?: Killable }> {
+  const { home = agoraHome(), timeoutMs = 10_000, intervalMs = 100 } = opts;
+  const script = resolveScript(opts, home);
+  let port = readPort(home);
+  if (port !== null && (await probe(port))) return { port };
+  if (!existsSync(script)) throw new LiftTimeout(`agorad 未安装：找不到 ${script}`);
+  let ocUrl = process.env.AGORA_OC_URL;
+  let ocPassword = process.env.AGORA_OC_PASSWORD;
+  if (!ocUrl) {
+    const found = discoverOc(opts.stateHome);
+    if (!found) {
+      throw new LiftTimeout(
+        "agorad 拉起失败：AGORA_OC_URL 未设置且服务发现落空（$XDG_STATE_HOME/opencode/service.json 不存在——opencode serve --service 在运行吗）",
+      );
+    }
+    ocUrl = found.url;
+    ocPassword ??= found.password; // T5 修正：发现的 password 必须随 env 透传（缺它＝agorad 全 401）
+  }
+  const proc = Bun.spawn(["python3", script], {
+    detached: true, // 脱会话＝原 setsid 包装等价（POSIX 新会话/Windows 新进程组），macOS 无 setsid 亦成立（Req: F27）
+    env: {
+      ...process.env,
+      AGORA_HOME: home,
+      AGORA_OC_URL: ocUrl,
+      ...(ocPassword ? { AGORA_OC_PASSWORD: ocPassword } : {}),
+    },
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    port = readPort(home);
+    if (port !== null && (await probe(port))) return { port, proc };
+    if (Date.now() >= deadline) {
+      proc.kill(); // 杀残留：不留给守护孤儿（起而不写/起不来）
+      throw new LiftTimeout(
+        `agorad 拉起失败：${Math.round(timeoutMs / 1000)}s 内未就绪（脚本 ${script}）`,
+      );
+    }
+    await Bun.sleep(intervalMs);
+  }
+}
+
+export type LiftResult = { ok: true; port: number } | { ok: false; reason: string };
+
+let memo: Promise<LiftResult> | null = null;
+
+function fresh(): Promise<LiftResult> {
+  return ensureService()
+    .then((r): LiftResult => ({ ok: true, port: r.port }))
+    .catch((e: unknown): LiftResult => ({ ok: false, reason: e instanceof Error ? e.message : String(e) }));
+}
+
+/** 懒调 memo 版（失败同样 memo：每进程至多一跑，防每次工具调用重吃轮询）；resetLift 后重试。
+ * 成功 memo 每次轻校验（readPort＋probe ~1ms）：agorad 重启换口/死亡即自愈——首见者换血 memo 并重拉，
+ * 并发后来者共享在飞自愈（单飞不重 spawn；resetLift 竞态回填，结果成败照常 memo）。
+ * service.json 瞬态读失（半写/暂缺）不认陈旧：回探 memo 口，活则守 memo（防误判漂移重拉出双守护）。
+ * （事故 2026-10-29：agorad 换随机端口后 memo 指死口，全会话 401 直至重启 serve。） */
+export function ensureOnce(): Promise<LiftResult> {
+  memo ??= fresh();
+  const cached = memo;
+  return cached.then(async (r) => {
+    if (!r.ok) return r;
+    const port = readPort(agoraHome());
+    if ((port === null || port === r.port) && (await probe(port ?? r.port))) return r;
+    if (memo !== cached && memo !== null) return memo; // 他人已换血：共享在飞自愈
+    memo = fresh(); // 首见者发起自愈（或 resetLift 竞态回填）；自愈经 ensureService 自身 probe 恰一次，不递归
+    return memo;
+  });
+}
+
+/** 复位失败 memo：用户救活 agorad 后恢复本会话（T4 doctor 接线）。 */
+export function resetLift(): void {
+  memo = null;
+}
+
+export const LIFT_RECOVER = "agorad 不可达已 memo（每进程一次）：救活服务后经 doctor resetLift 恢复，无需重启会话";
+
+/** agorad 回环面共用寻址＋超时（拉旗 pullEnforce／拉凭据 pullCredential 同源防漂移）。 */
+export const AGORAD_TIMEOUT_MS = 2000;
+export function agoradUrl(port: number, path: string): string {
+  return `http://127.0.0.1:${port}${path}`;
+}

opencode_agora-0.1.0.data/data/share/opencode-agora/agora-plugin/scope.ts

@@ -0,0 +1,36 @@
+/**
+ * scope 启用域（F12，R26/R29）：中央名册 $AGORA_HOME/.agora/inactive-repos 按仓休眠。
+ * 名册＝仓根绝对路径一行一个（尾斜杠容错，空白/相对路径坏行跳过，缺失＝全员活跃）；
+ * 每次调用重读名册（热载，即改即生效——去缓存后行为）；isDormant 精确路径匹配。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { agoraHome } from "./hook";
+
+let cache: string[] | null = null;  // 测试兼容（resetScope 清缓存钩子）；生产已去缓存
+
+function norm(p: string): string {
+  return p.replace(/\/+$/, "");
+}
+
+/** 读名册：缺失/不可读＝空名册（全员活跃，安全向＝现行行为）。每次调用重读（R26 修订：去进程缓存，名册改动即生效）。 */
+export function loadInactiveRepos(): string[] {
+  try {
+    return readFileSync(join(agoraHome(), ".agora", "inactive-repos"), "utf8")
+      .split("\n")
+      .map((l) => norm(l.trim()))
+      .filter((l) => l.startsWith("/"));
+  } catch {
+    return [];
+  }
+}
+
+/** 会话仓根是否休眠：对启动时缓存精确匹配（worktree toplevel≠主检出路径→不受名册影响）。 */
+export function isDormant(repoRoot: string): boolean {
+  return loadInactiveRepos().includes(norm(repoRoot));
+}
+
+/** 新会话重置（R26 不热载：名册变更经重启会话生效；亦供测试隔离）。 */
+export function resetScope(): void {
+  cache = null;
+}

opencode_agora-0.1.0.data/data/share/opencode-agora/install.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# agora 三部件装配＋root 牌接管（F1，T4）。幂等：连跑两遍落盘结果不变。
+# 流程：依赖检查→骨架（含 F12 名册）→MCP 注册（合并不覆盖）→插件/skills 复制→root 牌接管→持牌冒烟→停。
+# 更新路径：git pull 后重跑本脚本——插件（~/.config/opencode/plugins/agora）与 agorad
+# 载荷（$AGORA_HOME/.agora/agorad）是拷贝不是引用，拉新代码不重跑不生效。
+set -euo pipefail
+
+REPO="$(cd "$(dirname "$0")" && pwd)"
+if [ -z "${AGORA_HOME:-}" ] && [ -s "$HOME/.agora-home" ]; then  # 复跑保既有装（评审环）：env > 指针 > 缺省
+  AGORA_HOME="$(python3 -c 'import sys
+try:
+    print(open(sys.argv[1], encoding="utf-8").read().split("\n", 1)[0].strip())
+except (OSError, ValueError):
+    pass' "$HOME/.agora-home" 2>/dev/null || true)"  # 坏指针严格解码失败→空→缺省（读全量取首行，与 pointer_home 同契约，评审环）
+fi
+AGORA_HOME="${AGORA_HOME:-$HOME/plaza}"          # 与 agorad env_config 同缺省（设计 §3）
+# F31 pkg 分发：AGORA_PKG_ROOT 在位＝wheel 数据面（plugin/skills/install.sh/agora 拷贝源，
+# 由 agora-install 注入）；SRC 统一两模式拷贝源（repo 模式即本仓）
+PKG="${AGORA_PKG_ROOT:-}"
+SRC="${PKG:-$REPO}"
+printf '%s\n' "$AGORA_HOME" > "$HOME/.agora-home"  # gt-32c051 指针：无 env 组件统一发现（MCP 壳启动亦写）
+STATE_OC="$HOME/.local/state/opencode/service.json"  # T5 实证：serve --service 写此处 {url,password}
+OC_URL="${AGORA_OC_URL:-}"
+OC_PASSWORD="${AGORA_OC_PASSWORD:-}"
+if [ -z "$OC_URL" ] && [ -r "$STATE_OC" ]; then  # T5 服务发现回填；读不到回落占位（oc 不可达不挡服务）
+  OC_URL="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("url",""))' "$STATE_OC" 2>/dev/null || true)"
+  OC_PASSWORD="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("password",""))' "$STATE_OC" 2>/dev/null || true)"
+fi
+OC_URL="${OC_URL:-http://127.0.0.1:4096}"        # 占位：仅当 service.json 缺失
+OC_DIR="$HOME/.config/opencode"
+PLUGIN_DIR="$OC_DIR/plugins/agora"
+SERVICE_JSON="$AGORA_HOME/.agora/service.json"
+ROOT_TOKEN="$AGORA_HOME/.agora/root.token"
+AD_LOG="$AGORA_HOME/.agora/install-agorad.log"  # 拉起稳定日志唯一权威路径（step6 与 cleanup 扫尾同源，防单侧改名漂移）
+AD_PID=""; LOG=""
+
+fail() { echo "install: $*" >&2; exit 1; }
+cleanup() {
+  [ -n "$AD_PID" ] && { kill "$AD_PID" 2>/dev/null || true; wait "$AD_PID" 2>/dev/null || true; }
+  # 取牌即抹（GNU/BSD 通吃 -i.bak；换 inode，先抹＝丢 fd 后续留痕）。连同 .1 一起抹：
+  # 前轮被信号打断（无 EXIT trap）时牌行滞留旧日志，本轮 mv 成 .1 后会长驻留档
+  [ -n "$LOG" ] && { for f in "$LOG" "$LOG.1"; do
+      sed -i.bak '/^AGORA_ROOT_TOKEN: /d' "$f" 2>/dev/null && rm -f "$f.bak"; done; }
+  # 残牌无条件扫尾（键 AGORA_HOME——复用实例轮 LOG 空亦压着前轮被杀 cleanup 的残留）：
+  # .bak 全清；.1 通常不被活实例持 fd（例外：前轮信号打断的孤儿实例在 alive 探测
+  # 0.5s 窗内恰不可达时仍持 .1 fd——换 inode 会吞其尾部留痕，牌行已不可经路径触达，
+  # 无暴露面，属接受面）；活 .log 本体不抹（sed -i 换 inode 会吞活实例后续留痕，
+  # gt-e38e41）——活轮残牌属接受面，下一轮启动路径必抹
+  [ -n "$AGORA_HOME" ] && {
+    sed -i.bak '/^AGORA_ROOT_TOKEN: /d' "$AD_LOG.1" 2>/dev/null || true
+    rm -f "$AD_LOG.bak" "$AD_LOG.1.bak"; }
+  return 0
+}
+trap cleanup EXIT
+
+# ---- 1) 依赖检查 ----
+missing=""
+for c in python3 git opencode bun; do  # setsid 软依赖（F27）：macOS 原生无，缺位走拉起处 nohup 兜底
+  command -v "$c" >/dev/null 2>&1 || missing="$missing $c"
+done
+[ -z "$missing" ] || fail "缺依赖:$missing —— 安装后重试"
+
+# ---- 2) 骨架 ----
+mkdir -p "$AGORA_HOME/state/messages" "$AGORA_HOME/wiki" "$AGORA_HOME/.agora"
+# F12 名册空骨架：已有不覆盖（用户自录条目不可破坏）；0644 owner 可追加
+[ -e "$AGORA_HOME/.agora/inactive-repos" ] || (umask 022; : > "$AGORA_HOME/.agora/inactive-repos")
+
+# ---- 3) MCP 注册（mcp 段合并不覆盖；注册形状 T5 对账）----
+# F31：pkg 模式命令走 PATH 入口 agora-mcp；repo 模式仍指本仓壳（命令 JSON bash 侧构造作 heredoc 第 4 参）
+mkdir -p "$OC_DIR"
+if [ -n "$PKG" ]; then
+  MCP_CMD='["agora-mcp"]'
+else
+  MCP_CMD="$(python3 -c 'import json,sys;print(json.dumps([sys.argv[1],sys.argv[2]]))' python3 "$REPO/agora_mcp.py")"
+fi
+python3 - "$OC_DIR/opencode.json" "$REPO/agora_mcp.py" "$AGORA_HOME" "$MCP_CMD" <<'PY'
+import json, sys
+from pathlib import Path
+p, mcp_py, home = (Path(a) for a in sys.argv[1:4])
+cfg = {}
+if p.exists():
+    try:
+        cfg = json.loads(p.read_text(encoding="utf-8"))
+    except ValueError:
+        sys.exit(f"install: {p} 非法 JSON——拒改，请手修后重试")
+if not isinstance(cfg, dict):
+    sys.exit(f"install: {p} 顶层须为 JSON 对象——拒改")
+cfg.setdefault("mcp", {})["agora"] = {  # 重跑同值覆写＝幂等；他 server 原样保留
+    "type": "local",
+    "command": json.loads(sys.argv[4]),
+    "environment": {"AGORA_HOME": str(home)},
+}
+p.write_text(json.dumps(cfg, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+PY
+
+# ---- 4) 插件复制（opencode 只扫插件目录；整目录复制保相对导入；测试件不随装）----
+mkdir -p "$PLUGIN_DIR"
+for f in "$SRC"/agora-plugin/*.ts; do
+  case "$f" in *.test.ts) continue ;; esac
+  cp -f "$f" "$PLUGIN_DIR"/
+done
+
+# ---- 4a) skills 复制（主会话编排剧本；纯 md 整目录拷，同值覆写＝幂等）----
+mkdir -p "$OC_DIR/skills"
+for d in "$SRC"/skills/*/; do
+  cp -rf "${d%/}" "$OC_DIR/skills/"
+done
+
+# ---- 4b) agorad 载荷随装（T5 追加项：lift 不再假定与插件同仓——独立安装场景从
+#      $AGORA_HOME/.agora/agorad/main.py 解析；env AGORAD_SCRIPT 可覆写）。
+#      递归拷贝含 access/core/transport 子包（漏子包＝ModuleNotFoundError，lift 必超时）----
+mkdir -p "$AGORA_HOME/.agora" "$HOME/.local/bin"
+if [ -n "$PKG" ]; then
+  # F31 pkg 模式：载荷源＝agora-install 注入的 site-packages agorad 包；
+  # board_tui 载荷＋chmod＋agora-board 符号链接三行跳过（console script 替代）
+  # 收敛 repo→pkg 迁移残留：旧载荷删之防混版；符号链接只清指向本仓载荷位的残留——
+  # pipx 活链接同在 ~/.local/bin（默认 bin 目录），无差别 rm 即自毁 console script（round-2 B 册）
+  rm -f "$AGORA_HOME/.agora/board_tui.py"
+  if [ -L "$HOME/.local/bin/agora-board" ] && [ "$(readlink "$HOME/.local/bin/agora-board")" = "$AGORA_HOME/.agora/board_tui.py" ]; then
+    rm -f "$HOME/.local/bin/agora-board"
+  fi
+  AD_SRC="${AGORA_AGORAD_SRC:?pkg 模式须由 agora-install 注入 AGORA_AGORAD_SRC}"
+  rm -rf "$AGORA_HOME/.agora/agorad"
+  cp -r "$AD_SRC" "$AGORA_HOME/.agora/"
+else
+  rm -rf "$AGORA_HOME/.agora/agorad"
+  cp -r "$REPO/agorad" "$AGORA_HOME/.agora/"
+  cp -f "$REPO/board_tui.py" "$AGORA_HOME/.agora/"
+  chmod +x "$AGORA_HOME/.agora/board_tui.py"
+  ln -sf "$AGORA_HOME/.agora/board_tui.py" "$HOME/.local/bin/agora-board"
+fi
+
+# ---- 4c) agora CLI（F14：wait 阻塞谓词；bin 目录 4b 已建）----
+cp -f "$SRC/agora" "$HOME/.local/bin/agora"
+chmod +x "$HOME/.local/bin/agora"
+find "$AGORA_HOME/.agora/agorad" -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
+
+# ---- 5) AGORA_OC_URL 发现结果落档（lift 运行时自发现同源；此处只留档不作为消费面）----
+cat > "$AGORA_HOME/.agora/env" <<EOF
+# opencode 服务发现（T5 实证：\$XDG_STATE_HOME/opencode/service.json）
+# AGORA_OC_URL=$OC_URL
+EOF
+
+# ---- 6) root 牌接管 ----
+agorad_alive() {  # service.json port 可连＝在运行（任意应答含 401 同义）
+  python3 - "$SERVICE_JSON" <<'PY'
+import json, socket, sys
+try:
+    port = json.load(open(sys.argv[1]))["port"]
+    socket.create_connection(("127.0.0.1", int(port)), timeout=0.5).close()
+except Exception:
+    sys.exit(1)
+PY
+}
+
+if agorad_alive; then
+  echo "install: agorad 已在运行——复用既有实例与 root.token"
+else
+  LOG="$AD_LOG"  # 稳定日志（gt-e38e41）：不随 install 清理，拉起/死因可后验
+  [ -f "$LOG" ] && mv -f "$LOG" "$LOG.1"  # 上一轮留档一轮
+  (umask 077; : > "$LOG")  # 0600：日志含 root 牌行，不得按 umask 0644 落盘
+  # 脱会话（gt-71b6af）：setsid 在位原位 exec（$! 即 daemon pid）；macOS 无 setsid → nohup
+  # 兜底（F27：$! 同为 python pid，cleanup/第 8 步击杀语义两形态一致；SIGHUP 由 main.py handler 留痕退出）。
+  # 凭据经子壳 export 进 environ——不落 argv（env 变参形会随 /proc/<pid>/cmdline 对全体本地用户可读）
+  (
+    export AGORA_HOME="$AGORA_HOME" AGORA_OC_URL="$OC_URL"
+    if [ -n "$OC_PASSWORD" ]; then export AGORA_OC_PASSWORD="$OC_PASSWORD"; fi
+    if [ -n "$PKG" ]; then  # F31 pkg 模式：agorad 走 PATH console script
+      if command -v setsid >/dev/null 2>&1; then exec setsid nohup agorad; fi
+      exec nohup agorad
+    fi
+    if command -v setsid >/dev/null 2>&1; then
+      exec setsid nohup python3 "$REPO/agorad/main.py"
+    fi
+    exec nohup python3 "$REPO/agorad/main.py"
+  ) >"$LOG" 2>&1 &
+  AD_PID=$!
+  ready=""
+  for _ in {1..100}; do  # 10s 上限：等就绪行（root 牌行在其前 flush）
+    if grep -q "^agorad ready" "$LOG" 2>/dev/null; then ready=1; break; fi
+    kill -0 "$AD_PID" 2>/dev/null || break
+    sleep 0.1
+  done
+  # 失败转储抹牌行：token 行先于 ready 行落日志（main.py），起而不就绪的转储
+  # 不得把 root 牌泼进终端/agent 转录（流式过滤，无 -i，GNU/BSD 同形）
+  [ -n "$ready" ] || { sed '/^AGORA_ROOT_TOKEN: /d' "$LOG" >&2; fail "agorad 启动失败（10s 未就绪，见上方输出）"; }
+  tok="$(awk '/^AGORA_ROOT_TOKEN: /{print $2; exit}' "$LOG")"
+  if [ -n "$tok" ]; then
+    (umask 077; printf '%s\n' "$tok" > "$ROOT_TOKEN")  # 0600（F1 root 牌唯一落盘点）
+  elif [ ! -s "$ROOT_TOKEN" ]; then
+    fail "未捕获 root 牌且无既有 root.token——异常态，请清 $AGORA_HOME/tokens 后重装"
+  fi  # else: 复装复用既有 root.token（牌持久化，重启不换）
+fi
+[ -s "$ROOT_TOKEN" ] || fail "root.token 缺失（运行中实例无牌可接管）"
+
+# ---- 7) 冒烟：持 root 牌 /health 只读可达（不碰 enforce——复用既有实例的更新场景
+#      若做 off→on 写冒烟，会在真实例上开毫秒级 enforce OFF 窗；enforce 面由插件/e2e 覆盖）----
+python3 - "$SERVICE_JSON" "$ROOT_TOKEN" <<'PY'
+import json, sys, urllib.request
+port = json.load(open(sys.argv[1]))["port"]
+token = open(sys.argv[2]).read().strip()
+req = urllib.request.Request(
+    f"http://127.0.0.1:{port}/health",
+    headers={"X-Agora-Token": token})
+with urllib.request.urlopen(req, timeout=10) as r:
+    d = json.loads(r.read() or b"{}")
+assert d.get("ok"), f"冒烟失败: {d}"
+PY
+
+# ---- 8) 停（只停本脚本拉起的实例）----
+if [ -n "$AD_PID" ]; then
+  kill "$AD_PID" 2>/dev/null || true
+  wait "$AD_PID" 2>/dev/null || true
+  AD_PID=""
+  echo "install: 冒烟毕已停本脚本拉起的实例（装后服务由插件 lift 按需拉起）——拉起日志 $LOG"
+fi
+
+echo "install: 完成（$AGORA_HOME）"
+[ -n "$PKG" ] && echo "install: 更新＝pipx upgrade opencode-agora 后重跑 agora-install"  # pkg 用户无 git 仓，git pull 指引不适用
+echo "install: 启用域名册 $AGORA_HOME/.agora/inactive-repos（空＝全启用；仓根路径一行一个，新会话生效）"
+echo "install: 更新＝git pull 后重跑本脚本（插件与 agorad 载荷是拷贝不是引用，不重跑不生效）"
+echo "install: lift 失败可重启会话或等 doctor；工具拒因携 resetLift 恢复指引"