@tachikomagundam/abathur 0.2.0 → 0.2.2

package/README.md

@@ -139,8 +139,10 @@ abathur run --genome toy-smoke --dry-run     # plan + requires[] probes, zero sp
 ### Inside opencode
 
 Abathur ships an official opencode plugin adapter. The harness remains the
-orchestrator, but once installed an opencode session can also drive the CLI
-directly:
+orchestrator, but once set up an opencode session can also drive the CLI
+directly. Two install routes:
+
+**Route A — one command (tool + `/abathur` slash command).**
 
 ```bash
 npm i -g @tachikomagundam/abathur
@@ -148,18 +150,39 @@ abathur opencode install    # copies plugin assets into ~/.config/opencode/
 # restart opencode
 ```
 
-After a restart the session gets two things:
+**Route B — config only (tool, no slash command).** Put the package name in
+your opencode config and restart:
+
+```jsonc
+{ "plugin": ["@tachikomagundam/abathur"] }
+```
+
+opencode then downloads the package from npm at startup into its own cache
+(`~/.cache/opencode/packages/…`) and loads the package's `./server` export —
+no file copying, no uninstall step (delete the line). Two honest limits: the
+`abathur` **CLI** still must exist on `PATH` (or `ABATHUR_BIN`) because the
+tool spawns it, so keep the `npm i -g` install; and slash commands are plain
+markdown files that plugins cannot register upstream, so `/abathur` is Route A
+only.
+
+Either route gives the session:
 
 - the agent tool **`abathur`** — spawns the `abathur` CLI argv-only (never a
-  shell), restricted to the nine top-level commands plus `--help`
-  (`genome`, `run`, `status`, `promote`, `tombstone`, `bundle`, `graft`,
-  `self-eval`, `kernel`), with a 120 s timeout and a 64 KB output cap. The
-  binary resolves from `PATH` unless `ABATHUR_BIN` overrides it.
-- the user command **`/abathur <args…>`** — a slash command that tells the
-  agent to translate its arguments into a tool call and report the exit code.
-
-`abathur opencode status` shows each target's path, installed/packaged sha256,
-and state (up-to-date / outdated / foreign / absent).
+  shell), restricted to eight commands (`genome`, `run`, `status`, `bundle`,
+  `graft`, `self-eval`, `kernel`, `--help`), with a 120 s timeout and a 64 KB
+  output cap. The binary resolves from `PATH` unless `ABATHUR_BIN` overrides
+  it. Honest privilege note: the tool carries bash-equivalent privilege —
+  `run` and `genome` legitimately spawn mutator/engine binaries by design —
+  so the allowlist limits typos and UX, not capability. `promote` and
+  `tombstone` are deliberately NOT reachable through the tool: they are
+  human gates and must be run in a terminal.
+- the user command **`/abathur <args…>`** (Route A only) — a slash command
+  that tells the agent to translate its arguments into a tool call and report
+  the exit code.
+
+Route A ships its own manager commands: `abathur opencode status` shows each
+target's path, installed/packaged sha256, and state (up-to-date / outdated /
+foreign / absent).
 `abathur opencode uninstall` removes only files carrying the abathur marker; a
 foreign file at a target path makes both commands refuse with exit 2 and name
 the path — nothing is ever overwritten or deleted behind your back (there is
@@ -404,8 +427,10 @@ abathur run --genome toy-smoke --dry-run     # 计划 + requires[] 探针，零
 
 ### 在 opencode 里调用
 
-Abathur 自带官方 opencode 插件适配器。工装仍是编排者，但安装之后，opencode
-会话也可以直接驱动 CLI：
+Abathur 自带官方 opencode 插件适配器。工装仍是编排者，但配置之后，opencode
+会话也可以直接驱动 CLI。安装有两条路线：
+
+**路线 A——一条命令（工具 + `/abathur` 斜杠命令）。**
 
 ```bash
 npm i -g @tachikomagundam/abathur
@@ -413,16 +438,34 @@ abathur opencode install    # 把插件资产复制进 ~/.config/opencode/
 # 重启 opencode
 ```
 
-重启后会话获得两样东西：
+**路线 B——纯配置（只有工具，没有斜杠命令）。** 把包名写进 opencode 配置再
+重启：
 
-- 智能体工具 **`abathur`**——以纯 argv 方式 spawn `abathur` CLI（绝不经过
-  shell），顶层命令限定为九个真命令加 `--help`（`genome`、`run`、`status`、
-  `promote`、`tombstone`、`bundle`、`graft`、`self-eval`、`kernel`），120 秒
-  超时、64 KB 输出封顶。二进制从 `PATH` 解析，除非用 `ABATHUR_BIN` 覆盖。
-- 用户命令 **`/abathur <参数…>`**——斜杠命令，指示智能体把参数翻译成工具调用
-  并回报退出码。
+```jsonc
+{ "plugin": ["@tachikomagundam/abathur"] }
+```
+
+opencode 会在启动时自行从 npm 把包下载到它自己的缓存
+（`~/.cache/opencode/packages/…`）并加载该包的 `./server` 导出——不复制文件，
+也没有 uninstall 步骤（删掉那行即可）。两点诚实的限制：工具 spawn 的是
+`abathur` **CLI**，所以 CLI 仍必须在 `PATH`（或 `ABATHUR_BIN`）上可达，
+`npm i -g` 不能省；而斜杠命令在上游只是 markdown 文件、插件无法注册，
+所以 `/abathur` 只有路线 A 提供。
 
-`abathur opencode status` 逐目标打印路径、已安装/随包 sha256 与状态
+任一路线都会让会话获得：
+
+- 智能体工具 **`abathur`**——以纯 argv 方式 spawn `abathur` CLI（绝不经过
+  shell），顶层命令限定为八个（`genome`、`run`、`status`、`bundle`、`graft`、
+  `self-eval`、`kernel`、`--help`），120 秒超时、64 KB 输出封顶。二进制从
+  `PATH` 解析，除非用 `ABATHUR_BIN` 覆盖。诚实的权限说明：该工具具备与
+  bash 等同的权限——`run` 与 `genome` 按设计就会 spawn 变异器/引擎二进制——
+  所以允许清单限制的是笔误与体验，而非能力。`promote` 与 `tombstone` 刻意
+  不可经由工具触达：它们是人类闸门，必须在终端里运行。
+- 用户命令 **`/abathur <参数…>`**（仅路线 A）——斜杠命令，指示智能体把参数
+  翻译成工具调用并回报退出码。
+
+路线 A 自带管理命令：`abathur opencode status` 逐目标打印路径、已安装/随包
+sha256 与状态
 （up-to-date / outdated / foreign / absent）。
 `abathur opencode uninstall` 只删除带有 abathur 标记的文件；若目标路径上躺着
 别人的文件，两条命令都会 exit 2 并点名路径——绝不会背着你覆盖或删除任何东西

package/dist/commands/opencode.js

@@ -5,9 +5,11 @@
 // {plugins,commands}/. No network, no shell, no opencode process contact.
 // Identity rule: a target is ours only if its FIRST LINE carries our marker;
 // a foreign file at a target path is refused (exit 2), never overwritten,
-// never deleted — there is no --force anywhere.
+// never deleted — there is no --force anywhere. Destination rule (0.2.1):
+// a path that exists must be a plain regular file — directories and symlinks
+// are refused via lstat, never followed, entered, or destroyed.
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -79,9 +81,24 @@ function refuseForeign(target) {
     return cannotAnswer(`opencode: refusing to touch ${target.destination} — the file exists but is not ours ` +
         `(its first line lacks the marker '${target.marker}')`, "resolve it manually: move the foreign file aside (or adopt the marker), then re-run 'abathur opencode install'");
 }
+/** Destination shape guard shared by install/uninstall (lstat: links are inspected, not followed). */
+function requirePlainDestination(target) {
+    let shape;
+    try {
+        shape = lstatSync(target.destination);
+    }
+    catch {
+        return; // absent (or a not-yet-existing parent): the write path creates it fresh
+    }
+    if (!shape.isFile() || shape.isSymbolicLink()) {
+        cannotAnswer(`opencode: refusing to touch ${target.destination} — the path exists but is not a regular file ` +
+            `(directories and symlinks are never followed, entered, or destroyed)`, "resolve it manually: move the entry aside (or replace the symlink with a real file), then re-run 'abathur opencode install'");
+    }
+}
 /** Atomicity rule shared by install/uninstall: validate EVERY target before writing to ANY. */
 function requireNoForeign(targets) {
     for (const target of targets) {
+        requirePlainDestination(target);
         const current = readTarget(target);
         if (current !== null && !carriesMarker(current, target.marker))
             refuseForeign(target);
@@ -89,10 +106,15 @@ function requireNoForeign(targets) {
 }
 function opencodeInstall(env) {
     const targets = pluginTargets(env);
+    // Read BOTH packaged assets up front: a missing second asset must fail before anything is written.
+    const prepared = targets.map((target) => ({ target, packaged: readPackagedAsset(target) }));
     requireNoForeign(targets);
-    for (const target of targets) {
-        const packaged = readPackagedAsset(target);
+    for (const { target, packaged } of prepared) {
         const { state } = classify(target, packaged);
+        // TOCTOU: identity is re-checked right before the write — a foreign file planted
+        // since validation is refused, never overwritten.
+        if (state === "foreign")
+            refuseForeign(target);
         if (state === "up-to-date") {
             writeStdout(`${target.destination}: up to date`);
             continue;

package/dist/test/opencode.test.js

@@ -7,7 +7,7 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import * as os from "node:os";
 import path from "node:path";
 import { test } from "node:test";
@@ -98,6 +98,38 @@ test("install: foreign target without our marker ⇒ exit 2 naming the path, NOT
     // Atomicity: the refusal must happen before ANY write, so the command target stays absent.
     await assert.rejects(readFile(commandMd), (error) => error.code === "ENOENT");
 });
+test("install: a DIRECTORY at a target path is refused (exit 2, named) — never entered or destroyed", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    await mkdir(pluginTs, { recursive: true });
+    const inner = path.join(pluginTs, "someone-elses-plugin.ts");
+    await writeFile(inner, "// lives inside, must survive\n", "utf8");
+    const run = abathur(env, "opencode", "install");
+    assert.equal(run.status, 2, `${run.stdout}${run.stderr}`);
+    const combined = `${run.stdout}${run.stderr}`;
+    assert.ok(combined.includes(pluginTs), `refusal must name the path: ${combined}`);
+    assert.ok((await readFile(inner, "utf8")).includes("must survive"), "directory contents untouched");
+    // Atomicity still holds: validation precedes every write, so the sibling stays absent.
+    await assert.rejects(readFile(commandMd), (error) => error.code === "ENOENT");
+});
+test("install: a SYMLINK at a target path is refused (exit 2) — inspected by lstat, never followed", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    // The marker check alone would pass here: readFileSync follows the link, and the
+    // old write would then destroy the external file. lstat must refuse the link itself.
+    const real = path.join(home, "elsewhere", "real-file.ts");
+    await mkdir(path.dirname(real), { recursive: true });
+    const original = `${PLUGIN_MARKER} 0.0.1\n// real file outside the opencode tree\n`;
+    await writeFile(real, original, "utf8");
+    await mkdir(path.dirname(pluginTs), { recursive: true });
+    await symlink(real, pluginTs);
+    const run = abathur(env, "opencode", "install");
+    assert.equal(run.status, 2, `${run.stdout}${run.stderr}`);
+    assert.ok(`${run.stdout}${run.stderr}`.includes(pluginTs), `refusal must name the path: ${run.stdout}${run.stderr}`);
+    assert.equal(await readFile(real, "utf8"), original, "file behind the link must be untouched");
+    assert.equal((await lstat(pluginTs)).isSymbolicLink(), true, "the symlink itself must survive too");
+    await assert.rejects(readFile(commandMd), (error) => error.code === "ENOENT");
+});
 test("install: our marker'd older file is overwritten with packaged bytes", async (t) => {
     const { home, env } = await makeEnv(t);
     const { pluginTs } = targetPaths(home);
@@ -197,20 +229,14 @@ test("plugin/abathur.ts: V1 shape — marker, default {id, server}, tool allowli
     assert.ok(bytes.includes('id: "abathur"'), "file plugins must export id (resolvePluginId)");
     assert.ok(/server:\s*async\s*\(\)/.test(bytes), "server must be an async function (readV1Plugin)");
     assert.ok(bytes.includes("tool.schema"), "args must be built via tool.schema (no local zod dep)");
-    for (const command of [
-        "genome",
-        "run",
-        "status",
-        "promote",
-        "tombstone",
-        "bundle",
-        "graft",
-        "self-eval",
-        "kernel",
-        "--help",
-    ]) {
-        assert.ok(bytes.includes(`"${command}"`), `allowlist must contain ${command}`);
-    }
+    // Exact-array pin (0.2.1): parse the ALLOWED_COMMANDS literal from source — membership
+    // checks alone would let promote/tombstone creep back in via order or extras.
+    const literal = bytes.match(/const ALLOWED_COMMANDS[^=]*=\s*\[([^\]]*)\]/);
+    assert.ok(literal !== null, "ALLOWED_COMMANDS array literal must exist");
+    const allowed = [...(literal[1] ?? "").matchAll(/"([^"]+)"/g)].map((found) => found[1] ?? "");
+    assert.deepEqual(allowed, ["genome", "run", "status", "bundle", "graft", "self-eval", "kernel", "--help"]);
+    assert.ok(!allowed.includes("promote"), "promote is terminal-only — must not be tool-reachable");
+    assert.ok(!allowed.includes("tombstone"), "tombstone is terminal-only — must not be tool-reachable");
     assert.ok(bytes.includes("execFile"), "must spawn via execFile argv-only");
     assert.ok(!/shell\s*:\s*true/.test(bytes), "shell:true is banned");
     assert.ok(bytes.includes("ABATHUR_BIN"), "bin overridable via ABATHUR_BIN");
@@ -229,6 +255,26 @@ test("shipped plugin assets carry zero machine literals (D7 discipline extended
         }
     }
 });
+test("npm name route: exports['./server'] ships the marker'd plugin + runtime dep declared", async () => {
+    const pkg = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8"));
+    // opencode picks the server entry via exports["./server"] (extractExportValue
+    // accepts a plain string; plugin/shared.ts resolvePackageEntrypoint).
+    const serverEntry = pkg.exports?.["./server"];
+    assert.equal(typeof serverEntry, "string", "./server export must be a plain string path");
+    const server = serverEntry;
+    const target = path.resolve(repoRoot, server);
+    const head = (await readFile(target, "utf8")).split("\n")[0] ?? "";
+    assert.ok(head.startsWith(PLUGIN_MARKER), `server entry must start with the plugin marker: ${head}`);
+    // The tarball must actually contain that file or the name route installs nothing to import.
+    assert.ok((pkg.files ?? []).some((entry) => server.startsWith(`./${entry}/`)), "server entry must live under a published files[] directory");
+    // Arborist installs the package's dependencies next to it in opencode's cache —
+    // that sibling copy is how the shipped import of @opencode-ai/plugin resolves (OMO mechanism).
+    const dep = pkg.dependencies?.["@opencode-ai/plugin"];
+    assert.equal(typeof dep, "string", "@opencode-ai/plugin must be a runtime dependency");
+    assert.ok((dep ?? "").length > 0, "dependency range must not be empty");
+    // Route B must serve the same bytes the route A installer copies: both resolve to plugin/abathur.ts.
+    assert.equal(serverEntry, "./plugin/abathur.ts", "server entry and installer asset must be one file");
+});
 test("CLI help: opencode is a registered top-level command", async (t) => {
     const { env } = await makeEnv(t);
     const help = abathur(env, "--help");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tachikomagundam/abathur",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Evolution harness: observe failures, mutate, re-bench, select — human-gated promotion, offline lineage bundles.",
   "author": "TachikomaGundam",
   "type": "module",
@@ -20,6 +20,11 @@
     "abathur": "dist/cli.js"
   },
   "main": "dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js",
+    "./server": "./plugin/abathur.ts",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "config",
@@ -33,6 +38,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@opencode-ai/plugin": "^1.17.4",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/plugin/abathur-command.md

@@ -4,11 +4,12 @@ Drive the abathur evolution harness through the `abathur` tool on this machine.
 User request: $ARGUMENTS
 
 Interpret the request as one `abathur` CLI invocation: the first word is the
-top-level command (`genome`, `run`, `status`, `promote`, `tombstone`, `bundle`,
-`graft`, `self-eval`, `kernel`, or `--help`) and the rest are argv tokens. Call
-the `abathur` tool with `command` set to the first word and `extra` set to the
-remaining tokens, then report the CLI exit code (0 ok / 1 blocked decision /
-2 cannot-answer) and the relevant lines of its output. If no request was given,
-call the tool with `command: "--help"` and summarize the command list. Never
-call `promote` or `tombstone` unless the user asked for exactly that — they are
-human gates.
+top-level command (`genome`, `run`, `status`, `bundle`, `graft`, `self-eval`,
+`kernel`, or `--help`) and the rest are argv tokens. Call the `abathur` tool
+with `command` set to the first word and `extra` set to the remaining tokens,
+then report the CLI exit code (0 ok / 1 blocked decision / 2 cannot-answer)
+and the relevant lines of its output. If no request was given, call the tool
+with `command: "--help"` and summarize the command list. `promote` and
+`tombstone` cannot be called through the tool at all — the tool refuses them.
+They are human gates that belong to a terminal: if the user asks for one,
+tell them to run `abathur promote …` / `abathur tombstone …` there.

package/plugin/abathur.ts

@@ -1,4 +1,4 @@
-// abathur-opencode-plugin v0.2.0
+// abathur-opencode-plugin v0.2.2
 // Official opencode plugin adapter for the abathur evolution harness.
 // Registers ONE agent tool, `abathur`, that shells out to the abathur CLI —
 // argv-only (node:child_process execFile, never a shell), top-level commands
@@ -8,10 +8,15 @@
 // V1 plugin format (opencode >= 1.14): default export { id, server }, where
 // server(input, options) resolves to Hooks; Hooks.tool is a
 // { [name]: ToolDefinition } record (see @opencode-ai/plugin).
-// This file is shipped as-is (package.json "files") and copied into
-// ~/.config/opencode/plugins/ by `abathur opencode install`. It is NOT
-// compiled by abathur's tsc; "@opencode-ai/plugin" resolves inside opencode's
-// own config-directory install.
+// This file is shipped as-is (package.json "files") and reaches a session by
+// two routes, neither compiling it through abathur's tsc:
+// (A) copied into ~/.config/opencode/plugins/ by `abathur opencode install`
+//     (adds the /abathur command too); "@opencode-ai/plugin" then resolves in
+//     opencode's config-directory node_modules.
+// (B) served as the package's "./server" export when the npm package name is
+//     listed in opencode.jsonc "plugin" — opencode's arborist install places
+//     @opencode-ai/plugin (runtime dependency) next to the package in its
+//     cache, so the same import resolves there too.
 
 import { execFile } from "node:child_process";
 import { tool } from "@opencode-ai/plugin";
@@ -21,13 +26,12 @@ const TIMEOUT_MS = 120_000;
 /** Per-stream output cap fed back into the session; keeps one tool call from flooding context. */
 const MAX_OUTPUT_BYTES = 64 * 1024;
 
-/** The nine real top-level commands plus --help. Anything else is refused locally. */
+/** The seven tool-reachable top-level commands plus --help. Anything else is refused locally.
+ * promote/tombstone are human gates and deliberately terminal-only (0.2.1): not reachable here. */
 const ALLOWED_COMMANDS: readonly string[] = [
   "genome",
   "run",
   "status",
-  "promote",
-  "tombstone",
   "bundle",
   "graft",
   "self-eval",
@@ -89,14 +93,18 @@ function runCli(bin: string, argv: readonly string[]): Promise<CliResult> {
         }
         if (typeof failure.code !== "number") {
           const timedOut = failure.killed === true || (failure.signal !== undefined && failure.signal !== null);
-          resolve({
-            status: timedOut ? 124 : -1,
-            stdout: out,
-            stderr: errOut,
-            note: timedOut
-              ? `killed after ${String(TIMEOUT_MS / 1000)}s timeout (signal: ${String(failure.signal ?? "SIGTERM")})`
-              : `spawn failed: ${failure.message}`,
-          });
+          if (timedOut) {
+            let note = `killed after ${String(TIMEOUT_MS / 1000)}s timeout (signal: ${String(failure.signal ?? "SIGTERM")})`;
+            if (argv[0] === "run") {
+              // The timeout kills the CLI only; mutator/bench children are detached by design.
+              note +=
+                " — abathur run spawns detached children (mutator/bench sessions) " +
+                "that may still be running — the next 'abathur run' reaps them";
+            }
+            resolve({ status: 124, stdout: out, stderr: errOut, note });
+            return;
+          }
+          resolve({ status: -1, stdout: out, stderr: errOut, note: `spawn failed: ${failure.message}` });
           return;
         }
         // Ordinary non-zero exit: the CLI's own verdict (blocked / cannot-answer).
@@ -114,11 +122,14 @@ export default {
         description:
           "Run the abathur evolution-harness CLI on this machine. " +
           "Pass the top-level command word in `command` (one of: genome, run, status, " +
-          "promote, tombstone, bundle, graft, self-eval, kernel, --help) and every " +
+          "bundle, graft, self-eval, kernel, --help) and every " +
           "remaining argv token in `extra`. The call is spawned argv-only (no shell) " +
           "with a 120s timeout; the result text always ends with the CLI exit code " +
-          "(0 ok, 1 blocked decision, 2 cannot-answer). Promotion is a human gate — " +
-          "never call `promote` without the user explicitly asking.",
+          "(0 ok, 1 blocked decision, 2 cannot-answer). Honest privilege note: this " +
+          "tool carries bash-equivalent privilege — `run` and `genome` legitimately " +
+          "spawn mutator/engine binaries by design — so the allowlist limits typos " +
+          "and UX, not capability. `promote` and `tombstone` are deliberately NOT " +
+          "reachable here: they are human gates, run in a terminal.",
         args: {
           command: tool.schema
             .string()