opencode-agora 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""agora CLI（F14）：bash 可判定的只读条件谓词——看门狗规范条件等待。
+
+wait 子命令阻塞等待任务终态（merged/closed/blocked/cancelled），对齐
+docker wait / kubectl wait 约定。status 子命令（F28 防误杀）单查任务三态
+判读：数据全取既有 /board 单任务视图＋/doctor（零服务端新端点），分类
+客户端推导。取数照抄 board_tui.py 形态：
+$AGORA_HOME/.agora/{root.token,service.json}，零直读状态文件、零格式逆向。
+非 MCP agora.wait(seconds)（那是 agent 回合内本地睡眠，两者不互替）。
+"""
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+TERMINAL = frozenset(("merged", "closed", "blocked", "cancelled"))
+_INFLIGHT = ("todo", "dispatched", "running", "done", "verify_failed", "reopened")
+_INTERVAL = 15        # 内部轮询间隔（秒）
+_HTTP_TIMEOUT = 5     # 单次请求超时（board_tui 同值）
+_TIMEOUT_MSG = "须为非负有限秒数"
+_STALE_AFTER = 1200   # 心跳冷阈值（秒）——与 agorad report._STALE_AFTER 同口径（客户端推导锚）
+
+
+class Fail(Exception):
+    """终局异常（不可重试）——exit 2。"""
+
+
+class Transient(Exception):
+    """瞬时不可达（连接拒等 OSError 族）——阻塞形态内部重试吸收。"""
+
+
+class Rejected(Transient):
+    """认牌失败（401/403）——牌换代窗口瞬态；不跟随换模时仍终局 Fail。"""
+
+
+def _pointer_home():
+    """~/.agora-home 指针回退（gt-32c051 统一发现桥；board_tui 同形）。"""
+    try:
+        return ((Path.home() / ".agora-home").read_text(encoding="utf-8")
+                .split("\n", 1)[0].strip() or None)
+    except (OSError, ValueError):  # ValueError＝坏字节（UnicodeDecodeError 非 OSError 族）
+        return None
+
+
+def discover(home=None):
+    """root 牌＋端口：$AGORA_HOME/.agora/{root.token,service.json}（board_tui 同形）。"""
+    home = Path(home or os.environ.get("AGORA_HOME") or _pointer_home()
+                or Path.home() / "plaza")
+    sj = json.loads((home / ".agora" / "service.json").read_text(encoding="utf-8"))
+    port = int(sj["port"])  # 非数端口（半写形态）在此炸 ValueError/TypeError，不外溢 fetch
+    token = (home / ".agora" / "root.token").read_text(encoding="utf-8").strip()
+    if "\n" in token or "\r" in token:  # 控制符会让 putheader 带牌面炸进 stderr／折叠改头
+        raise ValueError("root 牌撕裂（含换行/回车）")
+    return f"http://127.0.0.1:{port}", token
+
+
+def _call(base, token, path, body):
+    """HTTP 取数缝（fetch/status 共用）：POST <path> 带 root 牌回解析 JSON。
+
+    401/403→Rejected（换模跟随窗按瞬态）、其余 HTTP 错→Fail（404 注任务未知）、
+    网络错（OSError 族）→Transient（可重试）。
+    """
+    req = urllib.request.Request(
+        base + path, data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json", "X-Agora-Token": token},
+        method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as r:
+            return json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:
+        if e.code in (401, 403):  # 认牌失败：牌换代/撕裂对窗口，跟随形态按瞬态
+            raise Rejected(f"HTTP {e.code}: {path}") from None
+        note = "（任务未知）" if e.code == 404 and path == "/board" else ""
+        raise Fail(f"HTTP {e.code}" + note + f": {path}") from None
+    except OSError as e:  # URLError（连接拒等）＝瞬时，可重试
+        raise Transient(str(e)) from None
+
+
+def fetch(base, token, tid):
+    """POST /board 单任务视图 → (state, commit)。报因尾附 tid（看门狗聚合 stderr 可归任务）。"""
+    try:
+        t = _call(base, token, "/board", {"task": tid})["task"]
+    except (Fail, Rejected) as e:
+        raise type(e)(f"{e}: {tid}") from None
+    return t["state"], t.get("commit")
+
+
+def classify(state):
+    """状态分类缝（exit code 决策）：终态→0，在飞（含未知态）→1。"""
+    return 0 if state in TERMINAL else 1
+
+
+def wait(tid, base, token, timeout=1800, once=False, interval=_INTERVAL,
+         clock=time.monotonic, pause=time.sleep, reread=None):
+    """轮询至终态：返回 (exit, stdout 行)；重试至超时仍不可达 raise Fail。
+
+    reread（run_wait 注入 discover）每轮轮询前重读指针——服务换模
+    （杀旧拉新、端口/牌换代）即跟随新端点续等，不对死端口空转到超时；
+    跟随时认牌失败（401/403，撕裂对/换代窗口）按瞬态重试。
+    """
+    deadline = clock() + timeout
+    while True:
+        if reread:
+            try:
+                nb, nt = reread()
+                if nb and nt:  # 半写空端点/空牌不采纳，保持旧端点下轮再读
+                    base, token = nb, nt
+            except (OSError, ValueError, TypeError, KeyError):
+                pass  # 指针半写/缺失（含非 dict JSON）保持旧端点，下轮再读
+        try:
+            state, commit = fetch(base, token, tid)
+        except Transient as e:
+            if isinstance(e, Rejected) and reread is None:
+                raise Fail(str(e)) from None  # 不跟随换模：认牌失败维持终局
+            if once or clock() >= deadline:
+                head = ("认牌失败" if isinstance(e, Rejected)
+                        else "服务不可达" if once else "服务不可达（重试至超时）")
+                raise Fail(f"{head}: {e}") from None
+        else:
+            if classify(state) == 0:
+                return 0, (f"{state} @{commit[:12]}" if commit else state)
+            if once or clock() >= deadline:
+                return 1, f"in-flight: {state}"
+        pause(min(interval, max(0.0, deadline - clock())))
+
+
+def run_wait(a):
+    base, token = discover()
+    if not token:
+        raise Fail("root 牌缺失")
+    code, line = wait(a.task_id, base, token, timeout=a.timeout, once=a.once,
+                      reread=discover)
+    print(line)
+    return code
+
+
+def status_view(tid, task, stale_ids, now):
+    """F28 三态判读（客户端推导，零服务端新端点）：数据＝/board 单任务视图＋/doctor。
+
+    fresh＝心跳近（last_seen 距今≤_STALE_AFTER）；busy_round＝在飞＋心跳冷＋
+    不在 doctor stale_candidates（基线含 env 活性，env 在写＝深潜中）；stale_candidate
+    ＝在 doctor 僵态候选单。终态或无 worker＝无判读（class None）。
+    """
+    state = task["state"]
+    seen = task.get("last_seen")
+    ago = None if not seen else max(0, int(now - seen))
+    if state in TERMINAL or not task.get("worker_sid"):
+        cls = None
+    elif tid in stale_ids:
+        cls = "stale_candidate"
+    elif ago is None or ago > _STALE_AFTER:
+        cls = "busy_round"
+    else:
+        cls = "fresh"
+    return {"task": tid, "state": state, "last_seen_ago": ago, "class": cls}
+
+
+def run_status(a):
+    base, token = discover()
+    if not token:
+        raise Fail("root 牌缺失")
+    now = time.time()
+    try:
+        task = _call(base, token, "/board", {"task": a.task_id})["task"]
+        doc = _call(base, token, "/doctor", {})
+    except Fail as e:  # 报因尾附 tid（镜像 fetch：看门狗聚合 stderr 可归任务）
+        raise type(e)(f"{e}: {a.task_id}") from None
+    except Transient as e:  # 单查不重试：判读要新鲜，旧数据不如报错
+        head = "认牌失败" if isinstance(e, Rejected) else "服务不可达"
+        raise Fail(f"{head}: {e}: {a.task_id}") from None
+    v = status_view(a.task_id, task,
+                    {tid for tid, _ in doc.get("stale_candidates", [])},
+                    now)  # 旧 daemon 无该键→空集降级，不裸 KeyError
+    if a.json:
+        print(json.dumps(v, ensure_ascii=False))
+    else:
+        ago = "-" if v["last_seen_ago"] is None else f"{v['last_seen_ago']}s"
+        print(f"{v['task']} state={v['state']} last_seen={ago} "
+              f"class={v['class'] or '-'}")
+    return 0
+
+
+def _timeout_arg(v):
+    """非负有限秒数；拒 nan/inf/负值（nan 会让 deadline 比较恒 False 变热轮询）。"""
+    try:
+        t = float(v)
+    except (ValueError, TypeError):
+        raise argparse.ArgumentTypeError(_TIMEOUT_MSG) from None
+    if not 0 <= t < float("inf"):
+        raise argparse.ArgumentTypeError(_TIMEOUT_MSG)
+    return t
+
+
+def _parser():
+    ap = argparse.ArgumentParser(
+        prog="agora",
+        description="agora CLI——bash 可判定的只读条件谓词（F14）。")
+    sub = ap.add_subparsers(dest="cmd", required=True, metavar="command")
+    w = sub.add_parser(
+        "wait", help="阻塞等待任务终态（--once 单查）",
+        description="阻塞等待任务终态（--once 单查）；非 MCP agora.wait(seconds)"
+                    "（那是 agent 回合内本地睡眠）。",
+        epilog="退出码：0＝终态到达（merged/closed/blocked/cancelled 任一）\n"
+               f"1＝--timeout 到期仍在飞（{'/'.join(_INFLIGHT)}），"
+               "或 --once 下当前在飞\n"
+               "2＝异常（用法错/任务未知 404/root 牌缺失/认牌失败/重试至超时仍不可达）",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    w.add_argument("task_id", metavar="task-id", help="任务 id（ag-xxxxxx 或历史 task-/gt-xxxxxx）")
+    w.add_argument("--timeout", type=_timeout_arg, default=1800,
+                   help="到期仍在飞退出 1（秒）；缺省 1800（防调用方永挂）")
+    w.add_argument("--once", action="store_true", help="单查形态，立即返回不阻塞")
+    w.set_defaults(fn=run_wait)
+    s = sub.add_parser(
+        "status", help="任务三态判读单查（F28 防误杀：cancel 前先看一眼）",
+        description="单查任务三态判读：state＋last_seen 距今秒＋分类——"
+                    "fresh(心跳近)/busy_round(在飞＋心跳冷＋非僵态候选)/"
+                    "stale_candidate(在 doctor 僵态候选单)；数据取 /board＋/doctor。",
+        epilog="退出码：0＝取数成功（判读读输出，不作退出码）\n"
+               "2＝异常（用法错/任务未知/不可达/认牌失败）",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    s.add_argument("task_id", metavar="task-id", help="任务 id（ag-xxxxxx 或历史 task-/gt-xxxxxx）")
+    s.add_argument("--json", action="store_true", help="机器可读 JSON 形态")
+    s.set_defaults(fn=run_status)
+    return ap
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    try:
+        a = _parser().parse_args(argv)
+        return a.fn(a)
+    except KeyboardInterrupt:
+        return 130  # 打断≠终态：非零防看门狗误判 merged
+    except Exception as e:
+        print(f"agora: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,112 @@
+/**
+ * cred 凭据管家（设计 §5.2）：会话牌缓存＋落盘读取，供 hook 判定链核验。
+ * 牌随任务生死——cancel/重派即废（缓存清理由 inject 侧 T3 对齐）。
+ * F25 修正推改拉：推送通道（inject_silent）证伪后，缓存未命中经 pullCredential
+ * 主动向 agorad /cred_for_sid 拉取自愈（节流，失败安全向 null＝默认拒）。
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGORAD_TIMEOUT_MS, agoradUrl } from "./lift";
+
+export type AgoraRole = "root" | "dispatcher" | "worker";
+export type Cred = { token: string; sid: string; role: AgoraRole; tid?: string; envDir?: string };
+
+const cache = new Map<string, Cred>(); // sid → cred
+
+export function cacheCredential(cred: Cred): void {
+  cache.set(cred.sid, cred);
+}
+
+export function getCredential(sid: string): Cred | undefined {
+  return cache.get(sid);
+}
+
+// 拉取节流：每 sid 每窗至多一拉（未命中也计窗，保护 agorad）；按 sid 而非进程级
+// ——同宿主多 worker 会话共享插件进程，进程级窗口会让别家首拉被误堵一窗
+const PULL_INTERVAL_MS = 30_000;
+const pullSeen = new Map<string, number>(); // sid->上次拉取时刻
+const lastVerdict = new Map<string, PullReason>(); // sid->窗内回放判据（评审 high 修复）
+
+/** 测试注入口：清节流窗。 */
+export function resetCredPull(): void {
+  pullSeen.clear();
+  lastVerdict.clear();
+}
+
+/** 拉取拒因四分支（F27）：ok＝命中；not_worker＝404 服务侧无在飞任务绑本会话（主会话常态）；
+ * unreachable＝连接拒/超时/5xx/形状缺（异常安全向）；throttled＝节流窗内零网络。 */
+export type PullReason = "ok" | "not_worker" | "unreachable" | "throttled";
+export type PullResult = { reason: PullReason; cred: Cred | null };
+
+/** 缓存未命中拉取自愈（F25 修正推改拉）：命中即填缓存并返回；其余按拒因枚举返回
+ * cred=null＝走现有默认拒文案。短超时 2s：不拖垮工具调用判定链。 */
+export async function pullCredential(sid: string, port: number): Promise<PullResult> {
+  const now = Date.now();
+  if (now - (pullSeen.get(sid) ?? 0) < PULL_INTERVAL_MS) {
+    // 窗内零网络但回放上次判据——裸 throttled 会把已知 not_worker 降级：root 牌永不入
+    // 缓存，主会话窗内第二次调用将断附牌/误吃 READ_HINT（≤30s 陈旧度与节流设计同界）。
+    return { reason: lastVerdict.get(sid) ?? "throttled", cred: null };
+  }
+  for (const [k, ts] of pullSeen) { // 出账：只留窗内活跃 sid，防常驻进程无界增长
+    if (now - ts >= PULL_INTERVAL_MS) {
+      pullSeen.delete(k);
+      lastVerdict.delete(k);
+    }
+  }
+  pullSeen.set(sid, now);
+  try {
+    const r = await fetch(agoradUrl(port, "/cred_for_sid"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sid }),
+      signal: AbortSignal.timeout(AGORAD_TIMEOUT_MS),
+    });
+    if (r.status === 404) {
+      lastVerdict.set(sid, "not_worker"); // 非在飞 worker：常态未命中（窗内回放防降级）
+      return { reason: "not_worker", cred: null };
+    }
+    if (!r.ok) {
+      lastVerdict.set(sid, "unreachable");
+      return { reason: "unreachable", cred: null };
+    }
+    const d = (await r.json()) as { tid?: string; env_dir?: string; token?: string };
+    // 形状缺＝异常安全向（归 unreachable：调用方不得回落 root 附牌）
+    if (!d.token || !d.env_dir) {
+      lastVerdict.set(sid, "unreachable");
+      return { reason: "unreachable", cred: null };
+    }
+    const cred: Cred = { token: d.token, sid, role: "worker", tid: d.tid, envDir: d.env_dir };
+    cacheCredential(cred);
+    lastVerdict.delete(sid); // ok 判据随缓存生效（后续走缓存命中，不再进本函数）
+    return { reason: "ok", cred };
+  } catch {
+    lastVerdict.set(sid, "unreachable"); // 服务不可达/超时：默认拒（与判定链服务不可达同口径）
+    return { reason: "unreachable", cred: null };
+  }
+}
+
+const CRED_FILE = ".agora-cred.json";
+
+/** 读会话目录内的落盘凭据；缺失/损坏一律 null（调用方按无凭据拒，安全方向）。 */
+export function readCredential(sessionDir: string): Cred | null {
+  try {
+    const cred = JSON.parse(readFileSync(join(sessionDir, CRED_FILE), "utf8")) as Cred;
+    return cred.token ? cred : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 落盘凭据（0600）；T5 实证 v2.1.4 无插件可见会话目录——inject 路径不落盘（内存缓存＋
+ * 服务侧 reinject 重发兜底），本函数留给未来选定落盘点（如 $AGORA_HOME）时复用。 */
+export function writeCredential(sessionDir: string, cred: Cred): void {
+  writeFileSync(join(sessionDir, CRED_FILE), JSON.stringify(cred) + "\n", { mode: 0o600 });
+}
+
+// 附牌形状（T5 实证）：tool.execute.before 改 ev.input 直达 MCP——index.ts 对 agora_* 工具
+// 直接写 input._token；本函数保留纯函数形态供非钩子面复用与测试。
+export function attachToken(args: Record<string, unknown>, sid: string): Record<string, unknown> {
+  const cred = cache.get(sid);
+  if (cred) args._token = cred.token;
+  return args;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * worker PATH 补全（F18）：opencode 服务层剥离 PATH（worker 实测只剩
+ * ".opencode/bin:/usr/local/bin:/usr/bin:/bin"），bun 等用户级工具失联。
+ * 接缝＝shell spawn 前钩子（v2.2.0 实证：shell 工具/终端同经 Shell.create→
+ * trigger("shell","create.before",payload)，payload.env 按引用直改直达 spawn env）：
+ * 基于既有 PATH 去重前插 $HOME/.bun/bin 与 $HOME/.local/bin，不硬编码全量。
+ */
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+
+const EXTRA = [".bun/bin", ".local/bin"];
+
+/** shell "create.before" 载荷本地形状（运行时未契约化，偏离由 onShellCreate 安全向兜住）。 */
+export type ShellCreatePayload = { env?: Record<string, string | undefined> };
+
+/** 原地补全 env.PATH：只加缺失项（前插保序去重），幂等；无 PATH 视为空；home 空/相对均不动（相对路径前插＝CWD 依赖，安全向）。 */
+export function augmentPath(env: Record<string, string | undefined>): void {
+  const home = env.HOME || homedir();
+  if (!isAbsolute(home)) return;
+  const parts = env.PATH ? env.PATH.split(delimiter) : []; // 保留既有空项（POSIX 空项＝CWD），契约只加不减
+  const missing = EXTRA.map((d) => join(home, d)).filter((p) => !parts.includes(p));
+  env.PATH = [...missing, ...parts].join(delimiter);
+}
+
+/** shell "create.before" 钩子入口：payload 缺 env 或补全异常均静默（安全向＝不动 spawn env，绝不阻断 Shell.create）。 */
+export function onShellCreate(payload: ShellCreatePayload | undefined): void {
+  if (!payload?.env) return;
+  try {
+    augmentPath(payload.env);
+  } catch {
+    // 运行时载荷偏离本地类型（如 PATH 非串）也不得炸钩子——钩子横切每次 shell spawn
+  }
+}

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

@@ -0,0 +1,132 @@
+/**
+ * hook 强制判定链（F1，设计 §5.1）：拦截判定纯函数，opencode 接线形状 T5 已实证收紧
+ * （tool.execute.before 覆盖 MCP 工具＋改参直达；cwd＝会话 location，异步取）。
+ * 语义与 agorad 服务侧一致：豁免面 B3（非 git、/tmp/opencode、enforce off）、
+ * 读引导（state 账本经工具面，events/wiki 开放，主会话例外）、主会话对仓写入同拦。
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import type { Cred, PullReason } from "./cred";
+
+export const DISPATCH_HINT =
+  "被拦：本机 git 仓直改仅限委托的隔离环境（cwd∈任务 env）。请经 agora 任务面派发（task_create/task_dispatch）持凭据作业；直接改仓仅限豁免面。";
+export const NO_CRED_HINT =
+  "被拦：无凭据缓存——可经真实 prompt 通道重注 BOOT+credential 自愈（配方见任务页），或 post(kind=question) 求派发方。";
+export const READ_HINT =
+  "被拦：tasks.jsonl 与 messages/ 属账本面，请走工具面（board/check_mail）；events.jsonl 与 wiki 可直接读。主会话不受此限。";
+
+const TMP_ROOT = "/tmp/opencode"; // B3 设计定值
+const WRITE_TOOLS = new Set(["edit", "write"]);
+const READISH_TOOLS = new Set(["read", "bash"]);
+
+export function agoraHome(homeDir = homedir()): string {
+  // 判定链信任锚仅 env（gt-32c051 裁定 A）：~/.agora-home 指针是被辖方可写文件，
+  // 若跟随则 enforce 旗/读边界可被一行 bash 挪根（终闸 C 册 blocker 实证）——禁加指针回退。
+  // homeDir 参数仅供测试注入口（Bun 缓存 homedir）。
+  if (process.env.AGORA_HOME) return process.env.AGORA_HOME;
+  return join(homeDir, "plaza");
+}
+
+/** realpath 折叠：末端不存在时折叠到最深存在祖先再拼回（write 目标常尚未创建）。 */
+function fold(p: string): string {
+  let cur = resolve(p);
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync.native(cur), ...tail);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return resolve(p);
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function under(root: string, p: string): boolean {
+  const r = fold(root);
+  return p === r || p.startsWith(r + sep);
+}
+
+/** git 仓判定：沿目标向上找 .git（目录或文件——worktree/submodule 形态）。 */
+function inGitRepo(p: string): boolean {
+  let cur = resolve(p);
+  for (;;) {
+    if (existsSync(join(cur, ".git"))) return true;
+    const parent = dirname(cur);
+    if (parent === cur) return false;
+    cur = parent;
+  }
+}
+
+/** 该工具是否落在判定链可能产出 hint 的类（write 引导面＋read/bash 账本读引导面）——
+ * enforce 旗按需拉取的预过滤（T6 评审：豁免类工具不付拉旗开销）。 */
+export function enforceRelevant(tool: string): boolean {
+  return WRITE_TOOLS.has(tool) || READISH_TOOLS.has(tool);
+}
+
+/** write 判定类（F25 修正：仅 write 工具缓存未命中触发 cred_for_sid 拉取）。 */
+export function isWriteTool(tool: string): boolean {
+  return WRITE_TOOLS.has(tool);
+}
+
+/** read/bash 目标落 state 账本子树（READ_HINT 面才消费凭据）——F27 readish 拉取 gate，
+ * 防普通 read 每次白付拉取 HTTP。 */
+export function readishGated(tool: string, targetPath: string): boolean {
+  return READISH_TOOLS.has(tool) && under(join(agoraHome(), "state"), fold(targetPath));
+}
+
+/** wrong-door 拒因＋副本换算（尽力而为）：envDir basename 形如 {repo}__wt-* →
+ * 主仓根＝envDir 父目录/{repo}；cwd 落主仓内则附副本对应路径，推导不出退化为仅列两侧实值。 */
+export function wrongDoorHint(envDir: string, cwd: string): string {
+  const m = basename(envDir).match(/^(.+)__wt-/);
+  const mainRoot = m ? join(dirname(envDir), m[1]) : null;
+  const conv =
+    mainRoot && under(mainRoot, cwd)
+      ? `；若编辑目标在主仓，对应副本路径＝${join(envDir, relative(mainRoot, cwd))}`
+      : "";
+  return `被拦：工作目录 ${cwd} 在任务 env ${envDir} 外${conv}——请在副本内编辑。`;
+}
+
+/**
+ * 判定链（F1）：返回引导文案＝拒，null＝放行。
+ * 凭据"活动"的本地代理＝持牌＋envDir＋cwd∈envDir；活动任务终审在服务侧（T5 接线对齐）。
+ * pull＝本次拉取拒因（F27，缺省 null）：404（not_worker）＝服务侧无在飞 worker 绑定本会话，
+ * 单用户模型下即主会话（root 牌从不入插件缓存，404 是主会话的唯一可判据——裁定 A）。
+ * readish 面：404→按「主会话例外」放行；worker 凭据/不可达/节流→READ_HINT（fail-closed）。
+ * write 面（F27 收殓残留 finding，裁定 A 镜像）：404→DISPATCH_HINT（主会话直改的正确指引
+ * ＝派任务，替代生产不可达的 root 缓存死条文路由）；200→已填缓存按 worker env 判定；
+ * 不可达/节流→NO_CRED_HINT（fail-closed，未知身份不给主会话指引）。
+ */
+export function shouldBlock(
+  tool: string,
+  targetPath: string,
+  cwd: string,
+  cred: Cred | undefined | null,
+  enforceOn: boolean,
+  pull: PullReason | null = null,
+): string | null {
+  if (!enforceOn) return null;
+  const target = fold(targetPath);
+  if (READISH_TOOLS.has(tool)) {
+    if (!under(join(agoraHome(), "state"), target)) return null; // events/wiki/其余裸读开放
+    if (cred?.role === "root") return null; // 主会话例外全开
+    if (pull === "not_worker") return null; // F27 裁定 A：非在飞 worker＝可信主类，放行
+    return READ_HINT;
+  }
+  if (!WRITE_TOOLS.has(tool)) return null;
+  if (under(TMP_ROOT, target) || !inGitRepo(target)) return null; // 豁免面 B3
+  if (cred?.token && cred.envDir && under(cred.envDir, cwd)) return null;
+  // 拒因分流：缓存命中 root 牌＝防御位（生产不入缓存）维持 DISPATCH_HINT；无凭据按拉取
+  // 判据路由（F27 收殓残留 finding，裁定 A 镜像）——404（not_worker）＝主会话直改→
+  // DISPATCH_HINT（「静待重注入」对主会话是死路，正确指引是派任务）；200 命中已填缓存
+  // 走上行 worker env 判定；不可达/节流＝未知身份维持 NO_CRED_HINT fail-closed。
+  // 服务不可达默认拒由 index 在 lift 败态时拼 LIFT_RECOVER 附着，不在此分支。
+  if (cred?.role === "root") return DISPATCH_HINT;
+  if (!cred?.token || !cred.envDir) {
+    if (pull === "not_worker") return DISPATCH_HINT; // F27 裁定 A 镜像：救活写面死条文路由
+    return NO_CRED_HINT;
+  }
+  return wrongDoorHint(cred.envDir, cwd);
+}