@tachikomagundam/abathur 0.1.1 → 0.2.1

package/README.md

@@ -136,6 +136,44 @@ abathur graft ./bundles/*.bundle.tgz --genome toy-smoke       # local re-bench o
 abathur run --genome toy-smoke --dry-run     # plan + requires[] probes, zero spawns
 ```
 
+### 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:
+
+```bash
+npm i -g @tachikomagundam/abathur
+abathur opencode install    # copies plugin assets into ~/.config/opencode/
+# restart opencode
+```
+
+After a restart the session gets two things:
+
+- the agent tool **`abathur`** — spawns the `abathur` CLI argv-only (never a
+  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…>`** — 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).
+`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
+still no `--force` anywhere).
+
+Caveat: fixture benches mirror the real `~/.config/opencode` (plugins and
+commands included) into their sandboxed HOMEs, so an installed plugin also
+loads inside bench sessions. Uninstall first if a bench needs a clean plugin
+environment.
+
 ### The historian genome and the operator workflow
 
 `historian` is the first real genome: OpenCode agents work wiki scenarios
@@ -368,6 +406,38 @@ abathur graft ./bundles/*.bundle.tgz --genome toy-smoke       # 对端血缘包
 abathur run --genome toy-smoke --dry-run     # 计划 + requires[] 探针，零 spawn
 ```
 
+### 在 opencode 里调用
+
+Abathur 自带官方 opencode 插件适配器。工装仍是编排者，但安装之后，opencode
+会话也可以直接驱动 CLI：
+
+```bash
+npm i -g @tachikomagundam/abathur
+abathur opencode install    # 把插件资产复制进 ~/.config/opencode/
+# 重启 opencode
+```
+
+重启后会话获得两样东西：
+
+- 智能体工具 **`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 <参数…>`**——斜杠命令，指示智能体把参数翻译成工具调用
+  并回报退出码。
+
+`abathur opencode status` 逐目标打印路径、已安装/随包 sha256 与状态
+（up-to-date / outdated / foreign / absent）。
+`abathur opencode uninstall` 只删除带有 abathur 标记的文件；若目标路径上躺着
+别人的文件，两条命令都会 exit 2 并点名路径——绝不会背着你覆盖或删除任何东西
+（整个二进制依然没有 `--force`）。
+
+注意：夹具基准会把真实的 `~/.config/opencode`（含插件与命令）镜像进沙箱 HOME，
+因此装好的插件在基准会话里同样会加载。若基准需要干净的插件环境，请先 uninstall。
+
 ### 历史学家基因组与操作员工作流
 
 `historian` 是第一个真实基因组：OpenCode 智能体对着在线 Wiki.js 夹具完成 wiki

package/dist/cli.js

@@ -10,6 +10,7 @@ import { bundleCommand } from "./commands/bundle.js";
 import { genomeCommand } from "./commands/genome.js";
 import { graftCommand } from "./commands/graft.js";
 import { kernelCommand } from "./commands/kernel.js";
+import { opencodeCommand } from "./commands/opencode.js";
 import { promoteCommand } from "./commands/promote.js";
 import { runCommand } from "./commands/run.js";
 import { selfEvalCommand } from "./commands/self-eval.js";
@@ -28,6 +29,7 @@ export const COMMANDS = [
     graftCommand,
     selfEvalCommand,
     kernelCommand,
+    opencodeCommand,
 ];
 export function usage() {
     const width = Math.max(...COMMANDS.map((c) => c.name.length));

package/dist/commands/opencode.js

@@ -0,0 +1,174 @@
+// `abathur opencode` — installer for the official opencode plugin adapter
+// (todo: opencode-plugin 1). Pure file management: byte-copies the packaged
+// V1 plugin (`<package>/plugin/abathur.ts`) and slash-command template
+// (`<package>/plugin/abathur-command.md`) into <HOME>/.config/opencode/
+// {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. 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, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXIT_OK, cannotAnswer } from "../exit.js";
+import { writeStdout } from "../out.js";
+/** First-line identity markers (the asset files must start with exactly these prefixes). */
+export const PLUGIN_MARKER = "// abathur-opencode-plugin v";
+export const COMMAND_MARKER = "<!-- abathur-opencode-command -->";
+// Packaged assets live at <package>/plugin/ — two levels above dist/commands/
+// (same import.meta.url-relative style as the shipped-config path in src/config.ts).
+const PLUGIN_TS_ASSET = fileURLToPath(new URL("../../plugin/abathur.ts", import.meta.url));
+const COMMAND_MD_ASSET = fileURLToPath(new URL("../../plugin/abathur-command.md", import.meta.url));
+/** <HOME>/.config/opencode — HOME env-driven (os.homedir() fallback), never a literal. */
+export function resolveOpencodeConfigDir(env = process.env) {
+    const home = env.HOME === undefined || env.HOME.length === 0 ? os.homedir() : env.HOME;
+    return path.join(home, ".config", "opencode");
+}
+export function pluginTargets(env = process.env) {
+    const dir = resolveOpencodeConfigDir(env);
+    return [
+        {
+            label: "plugin",
+            source: PLUGIN_TS_ASSET,
+            destination: path.join(dir, "plugins", "abathur.ts"),
+            marker: PLUGIN_MARKER,
+        },
+        {
+            label: "command",
+            source: COMMAND_MD_ASSET,
+            destination: path.join(dir, "commands", "abathur.md"),
+            marker: COMMAND_MARKER,
+        },
+    ];
+}
+function readPackagedAsset(target) {
+    try {
+        return readFileSync(target.source);
+    }
+    catch {
+        return cannotAnswer(`opencode: packaged ${target.label} asset is missing (${target.source})`, "the abathur install looks broken — re-run 'npm i -g @tachikomagundam/abathur'");
+    }
+}
+function readTarget(target) {
+    try {
+        return readFileSync(target.destination);
+    }
+    catch {
+        return null;
+    }
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function carriesMarker(bytes, marker) {
+    const text = bytes.toString("utf8");
+    const newline = text.indexOf("\n");
+    const firstLine = newline < 0 ? text : text.slice(0, newline);
+    return firstLine.startsWith(marker);
+}
+function classify(target, packaged) {
+    const current = readTarget(target);
+    if (current === null)
+        return { state: "absent", installed: null };
+    if (!carriesMarker(current, target.marker))
+        return { state: "foreign", installed: current };
+    return { state: current.equals(packaged) ? "up-to-date" : "outdated", installed: current };
+}
+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);
+    }
+}
+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, 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;
+        }
+        mkdirSync(path.dirname(target.destination), { recursive: true }); // precedent: src/core/genome.ts registry dirs
+        writeFileSync(target.destination, packaged);
+        writeStdout(`${target.destination}: ${state === "outdated" ? "updated" : "installed"}`);
+    }
+    writeStdout("note: restart opencode to load the plugin — tools and commands are scanned at startup.");
+    writeStdout("note: abathur fixture benches mirror the real ~/.config/opencode (plugins and commands " +
+        "included) into sandboxed HOMEs, so this plugin will also load inside bench sessions.");
+    return EXIT_OK;
+}
+function opencodeStatus(env) {
+    for (const target of pluginTargets(env)) {
+        const packaged = readPackagedAsset(target);
+        const { state, installed } = classify(target, packaged);
+        const installedSha = installed === null ? "-" : sha256(installed);
+        writeStdout(`${target.destination}: ${state}  installed=${installedSha}  packaged=${sha256(packaged)}`);
+    }
+    return EXIT_OK;
+}
+function opencodeUninstall(env) {
+    const targets = pluginTargets(env);
+    requireNoForeign(targets);
+    for (const target of targets) {
+        if (!existsSync(target.destination)) {
+            writeStdout(`${target.destination}: absent (nothing to remove)`);
+            continue;
+        }
+        rmSync(target.destination);
+        writeStdout(`${target.destination}: removed`);
+    }
+    writeStdout("note: restart opencode for the tool and command to disappear.");
+    return EXIT_OK;
+}
+function runOpencode(args) {
+    const [sub, ...rest] = args;
+    if (rest.length > 0) {
+        cannotAnswer(`opencode ${sub}: unexpected argument '${rest[0]}'`, "usage: abathur opencode install | status | uninstall");
+    }
+    switch (sub) {
+        case "install":
+            return opencodeInstall(process.env);
+        case "status":
+            return opencodeStatus(process.env);
+        case "uninstall":
+            return opencodeUninstall(process.env);
+        default:
+            return cannotAnswer(`opencode: unknown subcommand '${sub ?? "<none>"}'`, "usage: abathur opencode install | status | uninstall");
+    }
+}
+export const opencodeCommand = {
+    name: "opencode",
+    summary: "install/status/uninstall the official opencode plugin adapter",
+    run: ({ args }) => runOpencode(args),
+};

package/dist/test/opencode.test.js

@@ -0,0 +1,263 @@
+// Opencode plugin-adapter acceptance pins (plan abathur-opencode-plugin, todo 1).
+// CLI convention per genome.test.ts: spawn the BUILT dist/cli.js with a sandboxed
+// HOME (tmpdir) + ABATHUR_CONFIG, so install/status/uninstall never touch the
+// real ~/.config/opencode. The packaged plugin assets are additionally pinned
+// here as plain text (marker first line, no shell, version parity) — the real
+// opencode runtime consumes them uncompiled, so these string gates are the CI.
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+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";
+import { fileURLToPath } from "node:url";
+const cliPath = fileURLToPath(new URL("../../dist/cli.js", import.meta.url));
+/** Repo root as seen from dist/test/: package.json and plugin/ sit one level up each. */
+const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
+const pluginAssetPath = path.join(repoRoot, "plugin", "abathur.ts");
+const commandAssetPath = path.join(repoRoot, "plugin", "abathur-command.md");
+const PLUGIN_MARKER = "// abathur-opencode-plugin v";
+const COMMAND_MARKER = "<!-- abathur-opencode-command -->";
+/** D7 discipline extends to the shipped plugin/ dir even though the gate walks only src/. */
+const FORBIDDEN_NEEDLES = ["/home/lab", "historian"];
+// ------------------------------------------------------------------- fixtures
+async function freshDir(prefix) {
+    return mkdtemp(path.join(os.tmpdir(), `abathur-${prefix}-`));
+}
+function keep(t, dir) {
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    return dir;
+}
+/** Sandboxed HOME: opencode targets resolve under <home>/.config/opencode, config under <home>/.config/abathur. */
+async function makeEnv(t) {
+    const home = keep(t, await freshDir("oc-home"));
+    const configDir = path.join(home, ".config", "abathur");
+    await mkdir(configDir, { recursive: true });
+    const configPath = path.join(configDir, "config.jsonc");
+    await writeFile(configPath, "// isolated test config\n{}\n", "utf8");
+    return { home, env: { ...process.env, ABATHUR_CONFIG: configPath, HOME: home } };
+}
+function abathur(env, ...args) {
+    const run = spawnSync(process.execPath, [cliPath, ...args], { env, encoding: "utf8" });
+    return { status: run.status ?? -1, stdout: run.stdout, stderr: run.stderr };
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function targetPaths(home) {
+    const dir = path.join(home, ".config", "opencode");
+    return {
+        pluginTs: path.join(dir, "plugins", "abathur.ts"),
+        commandMd: path.join(dir, "commands", "abathur.md"),
+    };
+}
+async function packagedBytes() {
+    return {
+        ts: await readFile(pluginAssetPath),
+        md: await readFile(commandAssetPath),
+    };
+}
+// --------------------------------------------------------------- install
+test("install: writes both targets byte-identical to packaged assets + restart/bench notes", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const packaged = await packagedBytes();
+    const { pluginTs, commandMd } = targetPaths(home);
+    const run = abathur(env, "opencode", "install");
+    assert.equal(run.status, 0, `${run.stdout}${run.stderr}`);
+    assert.ok(run.stdout.includes(pluginTs), `output must name ${pluginTs}: ${run.stdout}`);
+    assert.ok(run.stdout.includes(commandMd), `output must name ${commandMd}: ${run.stdout}`);
+    assert.ok(/restart opencode/.test(run.stdout), `restart note missing: ${run.stdout}`);
+    assert.ok(/mirror/.test(run.stdout), `bench-mirror warning missing: ${run.stdout}`);
+    assert.deepEqual(await readFile(pluginTs), packaged.ts);
+    assert.deepEqual(await readFile(commandMd), packaged.md);
+});
+test("install: idempotent — second run says up to date, bytes untouched", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    assert.equal(abathur(env, "opencode", "install").status, 0);
+    const second = abathur(env, "opencode", "install");
+    assert.equal(second.status, 0, `${second.stdout}${second.stderr}`);
+    const upToDate = second.stdout.split("\n").filter((line) => line.includes("up to date"));
+    assert.equal(upToDate.length, 2, `both targets must report up to date: ${second.stdout}`);
+    const after = await packagedBytes();
+    assert.deepEqual(await readFile(pluginTs), after.ts);
+    assert.deepEqual(await readFile(commandMd), after.md);
+});
+test("install: foreign target without our marker ⇒ exit 2 naming the path, NOTHING written", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    const foreign = "// someone else's plugin, no marker\nexport default { id: 'other' };\n";
+    await mkdir(path.dirname(pluginTs), { recursive: true });
+    await writeFile(pluginTs, foreign, "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.equal(await readFile(pluginTs, "utf8"), foreign, "foreign bytes must survive");
+    // 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);
+    await mkdir(path.dirname(pluginTs), { recursive: true });
+    await writeFile(pluginTs, `${PLUGIN_MARKER} 0.0.1\n// ancient draft\n`, "utf8");
+    const run = abathur(env, "opencode", "install");
+    assert.equal(run.status, 0, `${run.stdout}${run.stderr}`);
+    assert.ok(run.stdout.includes(pluginTs));
+    const packaged = await packagedBytes();
+    assert.deepEqual(await readFile(pluginTs), packaged.ts);
+});
+test("install: mkdir -p creates the plugins/ and commands/ dirs in a virgin HOME", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    assert.equal(abathur(env, "opencode", "install").status, 0);
+    // Reading succeeded only because the directories were created on demand.
+    assert.ok((await readFile(pluginTs, "utf8")).startsWith(PLUGIN_MARKER));
+    assert.ok((await readFile(commandMd, "utf8")).startsWith(COMMAND_MARKER));
+});
+test("opencode: unknown subcommand and stray args exit 2 with usage", async (t) => {
+    const { env } = await makeEnv(t);
+    const unknown = abathur(env, "opencode", "frobnicate");
+    assert.equal(unknown.status, 2);
+    assert.ok(`${unknown.stdout}${unknown.stderr}`.includes("unknown subcommand"));
+    const none = abathur(env, "opencode");
+    assert.equal(none.status, 2);
+    const stray = abathur(env, "opencode", "install", "--force");
+    assert.equal(stray.status, 2);
+    assert.ok(`${stray.stdout}${stray.stderr}`.includes("unexpected argument"));
+});
+// ---------------------------------------------------------------- status
+test("status: virgin HOME ⇒ absent; after install ⇒ up-to-date with packaged sha256", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const packaged = await packagedBytes();
+    const fresh = abathur(env, "opencode", "status");
+    assert.equal(fresh.status, 0, fresh.stderr);
+    const absent = fresh.stdout.split("\n").filter((line) => line.includes(": absent"));
+    assert.equal(absent.length, 2, `both targets absent initially: ${fresh.stdout}`);
+    assert.equal(abathur(env, "opencode", "install").status, 0);
+    const ok = abathur(env, "opencode", "status");
+    assert.equal(ok.status, 0);
+    const { pluginTs, commandMd } = targetPaths(home);
+    const pluginRow = ok.stdout.split("\n").find((line) => line.startsWith(pluginTs));
+    const commandRow = ok.stdout.split("\n").find((line) => line.startsWith(commandMd));
+    assert.ok(pluginRow !== undefined && commandRow !== undefined, `both rows present: ${ok.stdout}`);
+    assert.ok(pluginRow.includes(": up-to-date"), `plugin up-to-date: ${pluginRow}`);
+    assert.ok(commandRow.includes(": up-to-date"), `command up-to-date: ${commandRow}`);
+    assert.ok(pluginRow.includes(`installed=${sha256(packaged.ts)}  packaged=${sha256(packaged.ts)}`), pluginRow);
+    assert.ok(commandRow.includes(`installed=${sha256(packaged.md)}  packaged=${sha256(packaged.md)}`), commandRow);
+});
+test("status: outdated (our marker, different bytes) and foreign (no marker) are distinct", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    await mkdir(path.dirname(pluginTs), { recursive: true });
+    await writeFile(pluginTs, `${PLUGIN_MARKER} 0.0.1\n// stale\n`, "utf8");
+    await mkdir(path.dirname(commandMd), { recursive: true });
+    await writeFile(commandMd, "not ours at all\n", "utf8");
+    const run = abathur(env, "opencode", "status");
+    assert.equal(run.status, 0);
+    assert.ok(run.stdout.includes(": outdated"), `stale ours → outdated: ${run.stdout}`);
+    assert.ok(run.stdout.includes(": foreign"), `unmarked → foreign: ${run.stdout}`);
+});
+// ------------------------------------------------------------- uninstall
+test("uninstall: removes both of ours; second run reports absent and still exits 0", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    assert.equal(abathur(env, "opencode", "install").status, 0);
+    const off = abathur(env, "opencode", "uninstall");
+    assert.equal(off.status, 0, `${off.stdout}${off.stderr}`);
+    await assert.rejects(readFile(pluginTs), (e) => e.code === "ENOENT");
+    await assert.rejects(readFile(commandMd), (e) => e.code === "ENOENT");
+    const again = abathur(env, "opencode", "uninstall");
+    assert.equal(again.status, 0);
+    assert.equal(again.stdout.split("\n").filter((l) => l.includes("absent")).length, 2);
+});
+test("uninstall: refuses foreign file and leaves the sibling of ours in place", async (t) => {
+    const { home, env } = await makeEnv(t);
+    const { pluginTs, commandMd } = targetPaths(home);
+    assert.equal(abathur(env, "opencode", "install").status, 0);
+    await writeFile(commandMd, "hijacked, marker gone\n", "utf8");
+    const run = abathur(env, "opencode", "uninstall");
+    assert.equal(run.status, 2, `${run.stdout}${run.stderr}`);
+    assert.ok(`${run.stdout}${run.stderr}`.includes(commandMd), "refusal names the foreign path");
+    // Atomicity: nothing removed — our plugin file must still be installed.
+    assert.ok((await readFile(pluginTs, "utf8")).startsWith(PLUGIN_MARKER));
+    assert.ok((await readFile(commandMd, "utf8")).includes("hijacked"));
+});
+// --------------------------------------------------- packaged asset sanity
+test("plugin/abathur.ts: V1 shape — marker, default {id, server}, tool allowlist, argv-only spawn", async () => {
+    const bytes = await readFile(pluginAssetPath, "utf8");
+    const firstLine = bytes.split("\n")[0] ?? "";
+    assert.ok(firstLine.startsWith(PLUGIN_MARKER), `first line must be the marker: ${firstLine}`);
+    const version = firstLine.slice(PLUGIN_MARKER.length).trim();
+    const pkg = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8"));
+    assert.equal(version, pkg.version, "plugin marker version must equal package.json version");
+    assert.ok(/export default\s*\{/.test(bytes), "V1 default export object required");
+    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)");
+    // 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");
+});
+test("plugin/abathur-command.md: first-line marker, $ARGUMENTS, points at the abathur tool", async () => {
+    const text = await readFile(commandAssetPath, "utf8");
+    assert.equal(text.split("\n")[0], COMMAND_MARKER, "first line must be the command marker");
+    assert.ok(text.includes("$ARGUMENTS"), "template must forward $ARGUMENTS");
+    assert.ok(text.includes("`abathur` tool"), "must instruct the agent to use the abathur tool");
+});
+test("shipped plugin assets carry zero machine literals (D7 discipline extended to plugin/)", async () => {
+    for (const file of [pluginAssetPath, commandAssetPath]) {
+        const text = await readFile(file, "utf8");
+        for (const needle of FORBIDDEN_NEEDLES) {
+            assert.ok(!text.includes(needle), `${path.relative(repoRoot, file)} must not contain '${needle}'`);
+        }
+    }
+});
+test("CLI help: opencode is a registered top-level command", async (t) => {
+    const { env } = await makeEnv(t);
+    const help = abathur(env, "--help");
+    assert.equal(help.status, 0);
+    assert.ok(help.stdout.includes("opencode"), `usage must list opencode: ${help.stdout}`);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tachikomagundam/abathur",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Evolution harness: observe failures, mutate, re-bench, select — human-gated promotion, offline lineage bundles.",
   "author": "TachikomaGundam",
   "type": "module",
@@ -25,7 +25,7 @@
     "config",
     "graders",
     "docs",
-    ".github"
+    "plugin"
   ],
   "scripts": {
     "build": "tsc && node scripts/copy-assets.mjs",

package/plugin/abathur-command.md

@@ -0,0 +1,15 @@
+<!-- abathur-opencode-command -->
+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`, `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

@@ -0,0 +1,162 @@
+// abathur-opencode-plugin v0.2.1
+// 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
+// restricted to an allowlist, hard timeout, capped output. The CLI itself
+// remains the human gate; this adapter only lets a session *ask* abathur.
+//
+// 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.
+
+import { execFile } from "node:child_process";
+import { tool } from "@opencode-ai/plugin";
+
+/** Spawn cap: a CLI call that outlives this is killed and reported, never awaited forever. */
+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 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",
+  "bundle",
+  "graft",
+  "self-eval",
+  "kernel",
+  "--help",
+];
+
+function resolveBin(): string {
+  const configured = process.env["ABATHUR_BIN"];
+  return configured === undefined || configured.length === 0 ? "abathur" : configured;
+}
+
+interface CliResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly note: string;
+}
+
+/** The subset of the execFile error shape this adapter reads (node sets `code` to the numeric exit status on non-zero exits). */
+interface SpawnError extends Error {
+  readonly code?: string | number | null;
+  readonly killed?: boolean;
+  readonly signal?: string | null;
+}
+
+/** Never rejects: every spawn failure becomes a structured result the agent can read. */
+function runCli(bin: string, argv: readonly string[]): Promise<CliResult> {
+  return new Promise((resolve) => {
+    execFile(
+      bin,
+      [...argv],
+      { timeout: TIMEOUT_MS, 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: "" });
+          return;
+        }
+        const failure = error as SpawnError;
+        if (failure.code === "ENOENT") {
+          resolve({
+            status: 127,
+            stdout: out,
+            stderr: errOut,
+            note: `binary '${bin}' not found — install abathur globally or point ABATHUR_BIN at it`,
+          });
+          return;
+        }
+        if (failure.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+          resolve({
+            status: -1,
+            stdout: out,
+            stderr: errOut,
+            note: `output truncated at ${String(MAX_OUTPUT_BYTES)} bytes (cap per stream)`,
+          });
+          return;
+        }
+        if (typeof failure.code !== "number") {
+          const timedOut = failure.killed === true || (failure.signal !== undefined && failure.signal !== null);
+          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).
+        resolve({ status: failure.code, stdout: out, stderr: errOut, note: "" });
+      },
+    );
+  });
+}
+
+export default {
+  id: "abathur",
+  server: async () => ({
+    tool: {
+      abathur: tool({
+        description:
+          "Run the abathur evolution-harness CLI on this machine. " +
+          "Pass the top-level command word in `command` (one of: genome, run, status, " +
+          "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). 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()
+            .describe("top-level abathur command, e.g. 'genome' or 'status' or '--help'"),
+          extra: tool.schema
+            .array(tool.schema.string())
+            .optional()
+            .describe("remaining argv tokens, e.g. ['add', '/path/to/genome.jsonc']"),
+        },
+        execute: async (args, context) => {
+          const command = args.command.trim();
+          if (!ALLOWED_COMMANDS.includes(command)) {
+            return (
+              `abathur: refused '${command}' — not an allowed top-level command. ` +
+              `Allowed: ${ALLOWED_COMMANDS.join(", ")}. Put the command word in 'command' ` +
+              `and every other token in 'extra'.`
+            );
+          }
+          const argv: readonly string[] = [command, ...(args.extra ?? [])];
+          context.metadata({ title: `abathur ${argv.join(" ")}` });
+          const bin = resolveBin();
+          const result = await runCli(bin, argv);
+          const sections = [
+            `$ abathur ${argv.join(" ")}`,
+            `exit: ${String(result.status)}`,
+          ];
+          if (result.note.length > 0) sections.push(`note: ${result.note}`);
+          sections.push(`--- stdout ---\n${result.stdout.length === 0 ? "(empty)" : result.stdout}`);
+          sections.push(`--- stderr ---\n${result.stderr.length === 0 ? "(empty)" : result.stderr}`);
+          return sections.join("\n");
+        },
+      }),
+    },
+  }),
+};

package/.github/workflows/ci.yml

@@ -1,29 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-jobs:
-  build-test:
-    name: Build & test (Node 22)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-          # NOTE: deliberately NO registry-url here. Setting registry-url makes
-          # setup-node inject NODE_AUTH_TOKEN, which switches npm to authenticated
-          # legacy auth and defeats Trusted Publishing (OIDC) downstream.
-
-      - run: npm ci
-      - run: npm run build
-      - run: npm test

package/.github/workflows/publish.yml

@@ -1,74 +0,0 @@
-# npm Trusted Publishing (OIDC) — zero long-lived credentials on GitHub.
-#
-# One-time setup required in the npmjs.com UI (Publishing access →
-# "Trusted publisher" → Add publisher → GitHub Actions):
-#   Owner / user:   TachikomaGundam
-#   Package name:   @tachikomagundam/abathur
-#   Repository:     Abathur
-#   Workflow name:  publish.yml
-#   Environment:    (leave empty unless you gate it)
-#   Release type:   progressive
-# The event this workflow publishes on is `push` (of a v* tag);
-# the action is `npm publish --provenance --access public`.
-#
-# If the trusted publisher is not registered, `npm publish` fails with
-# a 401/EPUBLISHCONFLICT — that is expected until the UI step is done.
-name: Publish
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  id-token: write # required for npm Trusted Publishing (OIDC provenance)
-
-jobs:
-  publish:
-    name: Publish to npm
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          # Node 24 ships npm >= 11.5.1, the minimum version that supports
-          # Trusted Publishing. Older npm silently falls back to token auth.
-          # NOTE: deliberately NO registry-url here — setting it injects
-          # NODE_AUTH_TOKEN and defeats OIDC (documented pitfall).
-          node-version: 24
-          cache: npm
-
-      - name: Enforce tag == package.json version
-        env:
-          GH_REF: ${{ github.ref }}
-          GH_EVENT: ${{ github.event_name }}
-        run: |
-          set -euo pipefail
-          if [ "${GH_EVENT}" = "workflow_dispatch" ]; then
-            # A dispatch lands on the default-branch tip, which carries no tag,
-            # so the describe-based check below would ALWAYS fail there. Skip it:
-            # the npm-side trusted-publisher event config remains the real gate.
-            echo "::warning::manual dispatch publish — npm Trusted Publishing event config will reject this unless a workflow_dispatch publisher is registered"
-          elif [ "${GH_REF#refs/tags/}" != "${GH_REF}" ]; then
-            # push of a v* tag: HEAD must sit exactly on that tag and the tag
-            # (minus the leading v) must equal package.json version.
-            TAG="$(git describe --tags --exact-match HEAD)"
-            VERSION="$(node -p "require('./package.json').version")"
-            if [ "${TAG#v}" != "${VERSION}" ]; then
-              echo "::error::git tag '${TAG}' does not match package.json version '${VERSION}'"
-              exit 1
-            fi
-            echo "Publishing ${VERSION} (tag ${TAG})"
-          else
-            echo "::error::unexpected event '${GH_EVENT}' on ref '${GH_REF}' — refusing to publish"
-            exit 1
-          fi
-
-      - run: npm ci
-
-      - run: npm run build
-
-      - run: npm publish --provenance --access public