@tachikomagundam/abathur 0.2.0 → 0.2.1

package/README.md

@@ -151,10 +151,14 @@ abathur opencode install    # copies plugin assets into ~/.config/opencode/
 After a restart the session gets two things:
 
 - 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.
+  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.
 
@@ -416,9 +420,12 @@ abathur opencode install    # 把插件资产复制进 ~/.config/opencode/
 重启后会话获得两样东西：
 
 - 智能体工具 **`abathur`**——以纯 argv 方式 spawn `abathur` CLI（绝不经过
-  shell），顶层命令限定为九个真命令加 `--help`（`genome`、`run`、`status`、
-  `promote`、`tombstone`、`bundle`、`graft`、`self-eval`、`kernel`），120 秒
-  超时、64 KB 输出封顶。二进制从 `PATH` 解析，除非用 `ABATHUR_BIN` 覆盖。
+  shell），顶层命令限定为八个（`genome`、`run`、`status`、`bundle`、`graft`、
+  `self-eval`、`kernel`、`--help`），120 秒超时、64 KB 输出封顶。二进制从
+  `PATH` 解析，除非用 `ABATHUR_BIN` 覆盖。诚实的权限说明：该工具具备与
+  bash 等同的权限——`run` 与 `genome` 按设计就会 spawn 变异器/引擎二进制——
+  所以允许清单限制的是笔误与体验，而非能力。`promote` 与 `tombstone` 刻意
+  不可经由工具触达：它们是人类闸门，必须在终端里运行。
 - 用户命令 **`/abathur <参数…>`**——斜杠命令，指示智能体把参数翻译成工具调用
   并回报退出码。
 

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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tachikomagundam/abathur",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Evolution harness: observe failures, mutate, re-bench, select — human-gated promotion, offline lineage bundles.",
   "author": "TachikomaGundam",
   "type": "module",

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.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
@@ -21,13 +21,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 +88,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 +117,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()