border-customs 0.5.0 → 0.5.1

package/README.md

@@ -638,13 +638,20 @@ plugin entry ships as `exports["./server"]`):
 ```jsonc
 {
   // pin the exact version — an @latest channel hits the registry on every cold start
-  "plugin": ["border-customs@0.5.0"]
+  "plugin": ["border-customs@0.5.1"]
 }
 ```
 
 No global install and no PATH entry are required for it: the plugin resolves its CLI from the
-package's own `dist/index.js` sitting next to the plugin module, with `BORDER_BIN` as an
-explicit override that wins first and `border` on `PATH` as the file-drop route's fallback.
+package's own `dist/index.js` sitting next to the plugin module — exec'd directly through its
+shebang, or under `node` from `PATH` if that is not runnable — with `BORDER_BIN` as an explicit
+override that wins alone (a broken override is a loud error, never a silent fallback) and
+`border` on `PATH` as the file-drop route's fallback. Every candidate must first pass an
+**identity handshake**: the adapter spawns `--help` and requires the border banner and
+`usage: border` line before any user argv is handed over; the host binary is never used as a
+runtime (0.5.0 spawned `process.execPath`, which inside a plugin host is opencode itself —
+see the 0.5.1 changelog). Nothing that fails the handshake runs, and no fallback to a
+different binary exists.
 The alternative is the file-drop installer, `border opencode install|status|uninstall`, which
 writes `plugins/border.ts` and `commands/border.md` into `$XDG_CONFIG_HOME/opencode` (with an
 `HOME/.config` fallback) under marker identity: a foreign file at either path is refused with
@@ -656,10 +663,12 @@ What loads is one agent tool `border` plus a `/border` slash command. The tool s
 argv-only (no shell; 300 s cap, 64 KiB per stream) restricted to the closed command list
 `check`, `push`, `status`, `llm-request`, `llm-ingest`, `scan`, `roundtrip`, `--help`, and
 renders the exit-code contract unchanged: 0 pass, 1 gate-blocked or partial push, 2 the gate
-could not answer. The tool REFUSES `--yes` — a real push is the human gate, terminal-only, and
-a bare `border push` from the session is DRY-RUN by the CLI's own contract anyway. `/border`
-self-registers via the plugin `config` hook with `??=`, so a user file command of the same
-name — including a Route-A `commands/border.md` — stays authoritative.
+could not answer — which since 0.5.1 also covers "no border CLI found or verified": the tool
+answers exit 2 cannot-answer and spawns nothing else. The tool REFUSES `--yes` — a real push
+is the human gate, terminal-only, and a bare `border push` from the session is DRY-RUN by the
+CLI's own contract anyway. `/border` self-registers via the plugin `config` hook with `??=`, so
+a user file command of the same name — including a Route-A `commands/border.md` — stays
+authoritative.
 
 **Boundary honesty.** The command allowlist is fool-proofing (UX), not a security boundary: an
 opencode plugin runs with the opencode process's rights, and the gate's teeth are the CLI and
@@ -715,6 +724,24 @@ code.
 
 ## Changelog
 
+### 0.5.1 (2026-09-24)
+- Fix: **plugin impersonation — the `border` tool could spawn the host binary instead of the
+  gate.** On Route B the 0.5.0 adapter resolved its packaged CLI as `process.execPath +
+  dist/index.js`, but inside the opencode plugin host `process.execPath` is the opencode
+  (bun-compiled) binary — sessions saw opencode's banner for `--help` and opencode usage
+  errors for every other command, while the tool's schema still promised border's
+  fail-closed contract. The resolution order is now: `BORDER_BIN` (wins alone; a broken
+  override never silently falls back) → packaged `dist/index.js` exec'd directly via its
+  shebang, else under `PATH` `node` → `border` on `PATH`. `process.execPath` is removed from
+  the adapter, pinned by a source-level regression test, and **every candidate must pass an
+  identity handshake** (`--help` answering with border's banner + `usage: border`, exit 0,
+  20 s cap) before any user argv is spawned — failure reports `cannot-answer` at exit 2 and
+  runs nothing else (spawn failures now map to 2, not 127, aligning the tool with the CLI's
+  exit-code contract). Regression tests cover the unspawnable-override and the
+  opencode-style-impostor fixtures; the impostor logs prove user argv never reaches it.
+  Honest boundary: the handshake catches mistaken identity (host binaries, PATH accidents),
+  not a deliberately forged banner.
+
 ### 0.5.0 (2026-09-12)
 - Add: OpenCode plugin adapter (`exports["./server"]` + `/border` + `border` tool) loadable
   two ways with zero manual install — config-declared `"plugin": ["border-customs@0.5.0"]`
@@ -855,4 +882,4 @@ border 是一个 fail-closed(失败即拦截)的推送前门禁 CLI:`npm install
 
 发布一致性(0.4.1):起因是 aihr 事故——PyPI 上标为 0.2.2 的 wheel 里 `__init__.__version__` 却写着 0.2.1,构件名、元数据与实际模块行为三者不一致,所有 `==0.2.2` 的用户静默装上了旧行为;同类漂移在本仓库也出现过两次(npm tarball 的 User-Agent 停在 0.3.0 而 package.json 是 0.3.1;package-lock.json 根版本两个 release 一直躺在 0.1.0)。发布阶段扫描器因此在构件内部逐源交叉核对版本号:`release-coherence-version-drift` 为 CRITICAL(package.json 与被强制打包的 package-lock、wheel 文件名对 dist-info 目录对 METADATA `Version:` 对 `__init__` 字面量、sdist 的 pyproject 对 PKG-INFO/setup 系字面量、Cargo.toml 对已打包的 Cargo.lock、.gemspec 对 metadata.gz、dist 文件名对 sdist 内 PKG-INFO);版本源存在但无法静态解析(动态 `__version__`、`attr:`、`dynamic = ["version"]`、坏 lockfile)判 MEDIUM `release-coherence-unverifiable-source`——不可核查绝不静默算干净;第二版本源根本没被打包时不发现在内,缺源不是漂移,这条边界是承重的,误报的门禁会把用户训练成 `--force`。唯一可静态强制的跨包管理器声明是 opt-in `release.twin`(`{pypi, npm}` 严格 zod 对列表,未知键 exit 2):同一 run 的 dist 里孪生版本不等 ⇒ CRITICAL `release-coherence-twin-drift`,消息点名两个构件。规则源文件与 residue 指纹表一样并入 rulesHash,改一个匹配器即令全部缓存 PASS 失效。
 
-OpenCode 插件适配层(0.5.0):零手工装载两条路线——主路是在 `opencode.jsonc` 声明 `"plugin": ["border-customs@0.5.0"]`(建议钉具体版本,@latest 每次冷启动都打注册表),opencode 自行下载构件,插件入口走 `exports["./server"]`;插件自带 CLI 解析,顺序为 `BORDER_BIN` 覆盖 > 包内同侧 `dist/index.js` > PATH 上的 `border`,免全局安装、免 PATH 配置。备路是 `border opencode install|status|uninstall` 文件投递,落盘 `$XDG_CONFIG_HOME/opencode` 下的 `plugins/border.ts` 与 `commands/border.md`(无 XDG 回退 HOME/.config):受管文件凭 marker 行识别身份,同名外人文件 exit 2 拒绝、绝不覆盖,卸载只删自己带 marker 的文件,字节相同即 `up to date`。装载面只有一个 `border` 工具(argv-only 生成、无 shell、300 秒与每流 64 KiB 上限,命令闭集 check/push/status/llm-request/llm-ingest/scan/roundtrip/--help)与一条 `/border` 斜杠命令(config 钩子以 `??=` 自注册,用户同名文件命令保持权威)。边界如实说:allowlist 是 UX/防呆而非安全边界——插件进程与 opencode 进程同权,门禁的牙齿在 CLI 与账本,不在适配层;`push --yes` 按设计留在终端人审,工具端机械拒绝,会话内裸 push 本就是 CLI 合同的 DRY-RUN。装载验证走 opt-in 探针 `BORDER_OPENCODE_PROBE=1`(临时 HOME/XDG 起 `opencode serve` 对照组,断言 `border` 工具 id 与恰好一条 border 命令,重复即 FAIL;插件加载失败是静默的,只认 HTTP 响应不认退出码)。两条路线装载后都需重启 opencode:工具与命令在启动时扫描。
+OpenCode 插件适配层(0.5.0):零手工装载两条路线——主路是在 `opencode.jsonc` 声明 `"plugin": ["border-customs@0.5.0"]`(建议钉具体版本,@latest 每次冷启动都打注册表),opencode 自行下载构件,插件入口走 `exports["./server"]`;插件自带 CLI 解析,顺序为 `BORDER_BIN` 覆盖(独占,坏了就报错、绝不静默回退)> 包内同侧 `dist/index.js`(shebang 直接执行,不可执行则回退 PATH 上的 `node` 承载)> PATH 上的 `border`,免全局安装、免 PATH 配置;0.5.1 起任何候选都必须先过**身份握手**(以 `--help` 应答出 border 横幅与 `usage: border` 才算数),通过之前绝不投递用户 argv,握手不过即 cannot-answer exit 2、不运行任何其他二进制——0.5.0 曾用 `process.execPath` 承载包内 dist,而在插件宿主里 execPath 是 opencode 本体,边检门被静默冒充为宿主(2026-09-22 事故,见 0.5.1 变更日志)。备路是 `border opencode install|status|uninstall` 文件投递,落盘 `$XDG_CONFIG_HOME/opencode` 下的 `plugins/border.ts` 与 `commands/border.md`(无 XDG 回退 HOME/.config):受管文件凭 marker 行识别身份,同名外人文件 exit 2 拒绝、绝不覆盖,卸载只删自己带 marker 的文件,字节相同即 `up to date`。装载面只有一个 `border` 工具(argv-only 生成、无 shell、300 秒与每流 64 KiB 上限,命令闭集 check/push/status/llm-request/llm-ingest/scan/roundtrip/--help)与一条 `/border` 斜杠命令(config 钩子以 `??=` 自注册,用户同名文件命令保持权威)。边界如实说:allowlist 是 UX/防呆而非安全边界——插件进程与 opencode 进程同权,门禁的牙齿在 CLI 与账本,不在适配层;`push --yes` 按设计留在终端人审,工具端机械拒绝,会话内裸 push 本就是 CLI 合同的 DRY-RUN。装载验证走 opt-in 探针 `BORDER_OPENCODE_PROBE=1`(临时 HOME/XDG 起 `opencode serve` 对照组,断言 `border` 工具 id 与恰好一条 border 命令,重复即 FAIL;插件加载失败是静默的,只认 HTTP 响应不认退出码)。两条路线装载后都需重启 opencode:工具与命令在启动时扫描。

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "border-customs",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "border-customs",
-      "version": "0.5.0",
+      "version": "0.5.1",
       "license": "MIT",
       "dependencies": {
         "@opencode-ai/plugin": "^1.17.4",

package/dist/index.js

@@ -44162,7 +44162,7 @@ import { createHash as createHash16 } from "node:crypto";
 import { basename as basename5 } from "node:path";
 var SCAN_MAX_ARTIFACT_BYTES = 200 * 1024 * 1024;
 var SCAN_REQUEST_TIMEOUT_MS = 6e4;
-var SCAN_USER_AGENT = "border-customs/0.5.0 (+https://github.com/sumteclab/border; border scan)";
+var SCAN_USER_AGENT = "border-customs/0.5.1 (+https://github.com/sumteclab/border; border scan)";
 var CRATES_DOWNLOAD_HOST = "https://static.crates.io";
 var defaultScanFetcher = async (url2, init) => {
   if (!/^https?:\/\//.test(url2)) throw new EngineRunError(`border scan refuses non-http(s) URL: ${url2}`, null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "border-customs",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "//": "publint is a runtime dep (exact pin): the npm-stage engine is invoked via bin resolution against the installed layout, so consumers get the publint-fail leg out of the box; the dev suite resolves the same node_modules/.bin/publint — no devDependencies entry is needed for it to stay green.",
   "description": "Fail-closed git push gate: secret scanning + supply-chain checks before any remote leaves the machine",
   "type": "module",

package/plugin/border.ts

@@ -1,4 +1,4 @@
-// border-opencode-plugin v0.5.0
+// border-opencode-plugin v0.5.1
 // Official opencode plugin adapter for the border fail-closed push gate.
 // Registers ONE agent tool, `border`, that drives the border CLI — argv-only
 // (node:child_process execFile, never a shell), top-level commands restricted
@@ -22,6 +22,17 @@
 //     On this route the CLI is spawned FROM THE PACKAGE ITSELF (../dist/index.js
 //     lives inside the same tarball), so no global install or PATH entry is
 //     needed — that is what makes Route B genuinely install-free.
+//
+// NEVER spawn the host: this module runs inside the opencode process, whose
+// process.execPath is the opencode (bun-compiled) binary, not node. The 0.5.0
+// packaged-sibling route used process.execPath + dist/index.js as argv — on
+// Route B that spawned opencode with the dist path as a subcommand: the gate
+// was silently replaced by the host (impersonation incident, 2026-09-22; the
+// node --test seam was blind because there execPath really is node). Since
+// 0.5.1 the packaged dist is exec'd DIRECTLY (shebang) or under PATH `node`,
+// and every candidate must pass an identity handshake (`--help` answering as
+// border) before any user argv is ever spawned. Unverifiable ⇒ exit 2
+// cannot-answer, never a fallback to some other binary.
 
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -30,6 +41,8 @@ import { tool, type Config } from "@opencode-ai/plugin";
 
 /** Spawn cap: a CLI call that outlives this is killed and reported, never awaited forever. */
 const TIMEOUT_MS = 300_000;
+/** Identity-handshake cap: a `--help` needing longer than this is not a border CLI. */
+const PROBE_TIMEOUT_MS = 20_000;
 /** Per-stream output cap fed back into the session; keeps one tool call from flooding context. */
 const MAX_OUTPUT_BYTES = 64 * 1024;
 
@@ -47,24 +60,36 @@ const ALLOWED_COMMANDS: readonly string[] = [
   "--help",
 ];
 
-/** How to reach the CLI: a binary name/absolute path, optionally under node itself. */
+/** How to reach the CLI: a binary name/absolute path, optionally a script prefix. */
 interface BinResolution {
   readonly bin: string;
-  /** argv to prepend before the CLI's own argv (the dist entry when hosted by node). */
+  /** argv to prepend before the CLI's own argv (the dist entry when hosted by PATH node). */
   readonly prefix: readonly string[];
+  /** Human-readable candidate identity, named in the cannot-answer note. */
+  readonly label: string;
 }
 
 /**
- * Resolution order: BORDER_BIN (non-empty) wins on every route; else the dist
- * bundle sitting next to this module in the package/repo layout (Route B and
- * dev checkout, spawned under node); else the `border` bin from PATH (Route A).
+ * Candidate order: BORDER_BIN (non-empty) wins alone on every route — a broken
+ * explicit override is a loud error, never a silent fallback; else the dist
+ * bundle sitting next to this module, exec'd directly through its shebang and,
+ * if that is not runnable, under PATH `node` (Route B + dev checkout); else the
+ * `border` bin from PATH (Route A). process.execPath is deliberately absent:
+ * inside a plugin host it is the HOST binary, not a JS runtime.
  */
-function resolveBin(): BinResolution {
+function candidateList(): readonly BinResolution[] {
   const configured = process.env["BORDER_BIN"];
-  if (configured !== undefined && configured.length > 0) return { bin: configured, prefix: [] };
+  if (configured !== undefined && configured.length > 0) {
+    return [{ bin: configured, prefix: [], label: `BORDER_BIN=${configured}` }];
+  }
   const distEntry = fileURLToPath(new URL("../dist/index.js", import.meta.url));
-  if (existsSync(distEntry)) return { bin: process.execPath, prefix: [distEntry] };
-  return { bin: "border", prefix: [] };
+  const candidates: BinResolution[] = [];
+  if (existsSync(distEntry)) {
+    candidates.push({ bin: distEntry, prefix: [], label: "packaged dist/index.js (shebang exec)" });
+    candidates.push({ bin: "node", prefix: [distEntry], label: "packaged dist/index.js under PATH node" });
+  }
+  candidates.push({ bin: "border", prefix: [], label: "border on PATH" });
+  return candidates;
 }
 
 interface CliResult {
@@ -72,6 +97,8 @@ interface CliResult {
   readonly stdout: string;
   readonly stderr: string;
   readonly note: string;
+  /** The child could not be spawned at all (ENOENT/EACCES/ENOEXEC) — never a gate verdict. */
+  readonly spawnFailed: boolean;
 }
 
 /** The subset of the execFile error shape this adapter reads (node sets `code` on failures). */
@@ -82,29 +109,27 @@ interface SpawnError extends Error {
 }
 
 /** Never rejects: every spawn failure becomes a structured result the agent can read. */
-function runCli(bin: string, prefix: readonly string[], argv: readonly string[]): Promise<CliResult> {
+function runCli(resolution: BinResolution, argv: readonly string[], timeoutMs: number): Promise<CliResult> {
   return new Promise((resolve) => {
     execFile(
-      bin,
-      [...prefix, ...argv],
-      { timeout: TIMEOUT_MS, maxBuffer: MAX_OUTPUT_BYTES, shell: false },
+      resolution.bin,
+      [...resolution.prefix, ...argv],
+      { timeout: timeoutMs, maxBuffer: MAX_OUTPUT_BYTES, shell: false },
       (error, stdout, stderr) => {
         const out = stdout.slice(0, MAX_OUTPUT_BYTES);
         const errOut = stderr.slice(0, MAX_OUTPUT_BYTES);
         if (error === null) {
-          resolve({ status: 0, stdout: out, stderr: errOut, note: "" });
+          resolve({ status: 0, stdout: out, stderr: errOut, note: "", spawnFailed: false });
           return;
         }
         const failure = error as SpawnError;
-        if (failure.code === "ENOENT") {
+        if (failure.code === "ENOENT" || failure.code === "EACCES" || failure.code === "ENOEXEC") {
           resolve({
-            status: 127,
+            status: 2,
             stdout: out,
             stderr: errOut,
-            note:
-              "the border CLI could not be spawned. Three remedies: set BORDER_BIN to a " +
-              "real border binary, or run 'border opencode install' (route A), or " +
-              "npm i -g border-customs (route A, PATH entry).",
+            spawnFailed: true,
+            note: `cannot-answer: the border CLI could not be spawned (${String(failure.code)}).`,
           });
           return;
         }
@@ -114,6 +139,7 @@ function runCli(bin: string, prefix: readonly string[], argv: readonly string[])
             stdout: out,
             stderr: errOut,
             note: `output exceeded ${MAX_OUTPUT_BYTES} bytes per stream and was truncated.`,
+            spawnFailed: false,
           });
           return;
         }
@@ -123,9 +149,10 @@ function runCli(bin: string, prefix: readonly string[], argv: readonly string[])
             stdout: out,
             stderr: errOut,
             note:
-              `killed after ${TIMEOUT_MS / 1000}s timeout (signal ${failure.signal ?? "SIGTERM"}). ` +
+              `killed after ${timeoutMs / 1000}s timeout (signal ${failure.signal ?? "SIGTERM"}). ` +
               "border check and roundtrip can be long — if you need a long roundtrip, " +
               "prefer running it in a terminal.",
+            spawnFailed: false,
           });
           return;
         }
@@ -135,12 +162,56 @@ function runCli(bin: string, prefix: readonly string[], argv: readonly string[])
           stderr: errOut,
           note:
             typeof failure.code === "number" ? "" : `spawn failed: ${failure.message}`,
+          spawnFailed: false,
         });
       },
     );
   });
 }
 
+/**
+ * border's --help contract (src/cli.ts): exit 0, banner line starts with
+ * `border`, usage line names `usage: border`. An impostor answering the spawn
+ * slot (the 2026-09-22 incident: the opencode host banner) fails this test, so
+ * user argv is never handed to a binary that cannot prove it is the gate.
+ * Honest boundary: this catches mistaken identity, not a forged banner.
+ */
+function isBorderHelp(result: CliResult): boolean {
+  if (result.status !== 0) return false;
+  const firstLine = (result.stdout.match(/^\s*(.*)/) ?? ["", ""])[1] ?? "";
+  return firstLine.startsWith("border") && result.stdout.includes("usage: border");
+}
+
+type Resolution =
+  | { readonly ok: true; readonly resolution: BinResolution }
+  | { readonly ok: false; readonly reasons: readonly string[] };
+
+/** Positive handshakes are cached per BORDER_BIN key for the host process's
+ * life; failures are never cached, so a mid-session install recovers on the
+ * next call. */
+let verified: { readonly key: string; readonly resolution: BinResolution } | null = null;
+
+async function resolveVerified(): Promise<Resolution> {
+  const key = process.env["BORDER_BIN"] ?? "";
+  if (verified !== null && verified.key === key) {
+    return { ok: true, resolution: verified.resolution };
+  }
+  const reasons: string[] = [];
+  for (const candidate of candidateList()) {
+    const probe = await runCli(candidate, ["--help"], PROBE_TIMEOUT_MS);
+    if (isBorderHelp(probe)) {
+      verified = { key, resolution: candidate };
+      return { ok: true, resolution: candidate };
+    }
+    reasons.push(
+      probe.status === 0
+        ? `${candidate.label}: spawned but --help did not answer as border (impostor?)`
+        : `${candidate.label}: probe exit ${String(probe.status)}${probe.note === "" ? "" : ` — ${probe.note}`}`,
+    );
+  }
+  return { ok: false, reasons };
+}
+
 /**
  * The /border slash-command template. ALSO published verbatim (after the marker
  * line) as plugin/border-command.md — test/opencode.test.ts pins the byte-mirror.
@@ -186,7 +257,10 @@ export default {
           "llm-request, llm-ingest, scan, roundtrip, --help) and every remaining argv " +
           "token in `extra`. The call is spawned argv-only (no shell) with a 300s " +
           "timeout; the result always ends with the CLI exit code: 0 pass, 1 " +
-          "gate-blocked or partial push, 2 gate could not answer. Honest privilege " +
+          "gate-blocked or partial push, 2 gate could not answer. Before running your " +
+          "argv the tool handshakes its binary candidate with `--help` and refuses " +
+          "everything (exit 2, cannot-answer) unless the responder provably is the " +
+          "border CLI — it never falls back to another binary. Honest privilege " +
           "note: this tool runs the border CLI, and the CLI IS the gate that decides " +
           "what leaves this machine — it carries the same power as the binary, so an " +
           "agent may only *ask* the gate, never bypass it. `push --yes` is " +
@@ -222,8 +296,19 @@ export default {
           }
           const argv: readonly string[] = [command, ...extra];
           context.metadata({ title: `border ${argv.join(" ")}` });
-          const resolution = resolveBin();
-          const result = await runCli(resolution.bin, resolution.prefix, argv);
+          const resolution = await resolveVerified();
+          if (!resolution.ok) {
+            return [
+              `$ border ${argv.join(" ")}`,
+              "exit: 2",
+              `note: cannot-answer — no border CLI passed the identity handshake, so nothing was run. Tried: ${resolution.reasons.join("; ")}. ` +
+                "Remedies: point BORDER_BIN at a real border CLI, run 'border opencode install' (route A), or npm i -g border-customs (PATH entry).",
+              "--- stdout ---\n(empty)",
+              "--- stderr ---\n(empty)",
+            ].join("\n");
+          }
+          const result = await runCli(resolution.resolution, argv, TIMEOUT_MS);
+          if (result.spawnFailed) verified = null;
           const sections = [
             `$ border ${argv.join(" ")}`,
             `exit: ${String(result.status)}`,