opencode-longrun-harness 1.2.22

package/harness/test/fixtures/routing-worker.mjs

@@ -0,0 +1,35 @@
+// Offline child process fixture. Never imports a live host or production state.
+import fs from 'node:fs';
+import path from 'node:path';
+const repo = path.resolve(import.meta.dirname, '../../..');
+  const [base, label, mode] = process.argv.slice(2);
+  process.env.LONGRUN_TEST = '1';
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  process.env.LONGRUN_CONTROLLER_FILE = path.join(repo, 'harness/src/controller.js');
+  let savedRun = false, delayed = false, projectReads = 0;
+  const rename = fs.renameSync, read = fs.readFileSync;
+  fs.renameSync = function(from, to, ...args) {
+    const result = rename.call(this, from, to, ...args);
+    if (String(to).endsWith('/run.json')) savedRun = true;
+    return result;
+  };
+  fs.readFileSync = function(file, ...args) {
+    let data, failure;
+    try { data = read.call(this, file, ...args); } catch (error) { failure = error; }
+    const target = mode === 'same-project' ? 'projects.json' : 'runs.json';
+    if (path.basename(String(file)) === 'projects.json') projectReads++;
+    if (label === 'A' && !delayed && path.basename(String(file)) === target && (mode === 'same-project' ? projectReads === 2 : savedRun)) {
+      delayed = true;
+      process.stdout.write(JSON.stringify({ critical: true }) + '\n');
+      // A normal scheduler can pause a process here. Hold its already-read snapshot
+      // long enough for B's independent process to finish an unprotected mutation.
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1800);
+    }
+    if (failure) throw failure;
+    return data;
+  };
+  const plugin = await import(path.join(repo, 'harness/plugin/longrun.js'));
+  const hooks = await plugin.default.server({ client: null });
+  const dir = path.join(base, mode === 'same-project' ? 'A' : label);
+  const result = await hooks.tool.longrun.execute({ action: 'start', request: 'Concurrent routing fixture', criteria: [{ id: 'c', checks: ['check'], evidenceClass: 'STATIC' }], checkCatalogue: { check: { command: [process.execPath, '-e', 'require("node:assert/strict").equal(2+2,4)'], kind: 'cmd' } } }, { sessionID: label, directory: dir, worktree: dir });
+  process.stdout.write(JSON.stringify({ result: JSON.parse(result) }) + '\n');

package/harness/test/fixtures/vitest-failed-receipt.json

@@ -0,0 +1,33 @@
+{
+  "runId": "lr-000000001a2b",
+  "receipt": {
+    "checkId": "c-presets-server",
+    "command": "npx vitest run packages/server/test/presets.test.ts",
+    "status": "FAIL",
+    "exitCode": 1,
+    "testCount": 0,
+    "startedAt": 1789926516792,
+    "finishedAt": 1789926525088,
+    "versions": {
+      "node": "v24.21.0"
+    },
+    "contractHash": "c1f33b88e2fc57a3bcb69ef08e9eaea5bf9c7c8ece8cc206a51ce555ba0a6dd1",
+    "evaluatorHash": null,
+    "sourceFingerprint": "57749e24657baa2db21edb631c2eb688514fe692df56abc07455485093106847",
+    "fingerprintSchemaVersion": 2,
+    "fpScope": "project",
+    "evidenceClass": "INTEGRATION",
+    "class": "INTEGRATION",
+    "proxyOnly": false,
+    "argv": [
+      "npx",
+      "vitest",
+      "run",
+      "packages/server/test/presets.test.ts"
+    ],
+    "outputTail": "\n RUN  v2.1.9 /home/example/project\n\n \u276f packages/server/test/presets.test.ts (15 tests | 1 failed) 7530ms\n   \u2713 presets: separate-process restart with owned cleanup > reaps the whole owned group even when the group's root exits first 1033ms\n   \u2713 presets: separate-process restart with owned cleanup > never treats a foreign TCP listener on the port as the owned child being ready 2868ms\n   \u00d7 presets: separate-process restart with owned cleanup > escalates a group descendant that ignores SIGTERM to SIGKILL so cleanup finishes 3242ms\n     \u2192 owned group 36905 cleanup incomplete; survivors: 36906\n\n Test Files  1 failed (1)\n      Tests  1 failed | 14 passed (15)\n   Start at  18:48:37\n   Duration  7.78s (transform 76ms, setup 0ms, collect 90ms, tests 7.53s, environment 0ms, prepare 38ms)\n\n\u23af\u23af\u23af\u23af\u23af\u23af\u23af Failed Tests 1 \u23af\u23af\u23af\u23af\u23af\u23af\u23af\n\n FAIL  packages/server/test/presets.test.ts > presets: separate-process restart with owned cleanup > escalates a group descendant that ignores SIGTERM to SIGKILL so cleanup finishes\nError: owned group 36905 cleanup incomplete; survivors: 36906\n \u276f shutdownProc packages/server/test/presets.test.ts:520:11\n    518|   }\n    519|   if (!childGone || alive.length > 0) {\n    520|     throw new Error(`owned group ${group} cleanup incomplete; survivor\u2026\n       |           ^\n    521|   }\n    522| }\n \u276f packages/server/test/presets.test.ts:811:7\n\n\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af\u23af[1/1]\u23af\n\n",
+    "terminationReason": null,
+    "executionError": null,
+    "executionToken": "da9ec511-76fd-4652-bc91-2fbebcdf3e95"
+  }
+}

package/harness/test/helper.mjs

@@ -0,0 +1,41 @@
+// Shared test plumbing. NOT an OpenCode plugin entry point — it is only ever imported by
+// harness/test/*. The plugin entrypoint (harness/plugin/longrun.js) deliberately exposes ONE
+// export (the V1 `{ id, server }` descriptor), so anything the tests need is provided here.
+// Importing this module also hard-arms LONGRUN_TEST: no test helper can ever write live
+// evidence into a production state dir.
+import fs from "node:fs";
+import path from "node:path";
+import * as C from "../src/controller.js";
+process.env.LONGRUN_TEST = "1";
+
+// Explicit independent-review fixture for positive completion tests. It neither
+// creates receipts nor repairs failing gates; the controller refuses unready data.
+export function approveFixtureReview(run, fingerprint = run.sourceFingerprint) {
+  if (!process.env.NODE_TEST_CONTEXT) throw new Error("test-only completion review");
+  run.status = "PAUSED";
+  const result = C.recordCompletionReview(run, { verdict: "accept", reason: "Independent harness fixture review; no product acceptance claim.",
+    reviewId: `test-review-${(run.completionReviews || []).length + 1}`,
+    currentFingerprint: fingerprint, expectedBasis: C.completionReviewBasis(run, fingerprint) });
+  if (!result.ok) throw new Error(JSON.stringify(result));
+  return run;
+}
+export function approveStoredFixtureReview(store, key, fingerprint) {
+  const result = store.mutate(key, run => { approveFixtureReview(run, fingerprint || C.sourceFingerprint(run.directory)); return { ok: true }; });
+  if (!result.ok) throw new Error(JSON.stringify(result));
+}
+export function reviewProjectFixture(directory, runId) {
+  approveStoredFixtureReview(new C.Store(process.env.LONGRUN_STATE_DIR), C.stateKey(C.projectIdentity(directory), runId));
+}
+
+const stateDir = () => process.env.LONGRUN_STATE_DIR;
+export function readRuns() { try { return JSON.parse(fs.readFileSync(path.join(stateDir(), "runs.json"), "utf8")); } catch { return {}; } }
+export function writeRuns(r) { const p = path.join(stateDir(), "runs.json"); fs.writeFileSync(p, JSON.stringify(r)); }
+
+// Load the plugin under test and return its hooks object, driven through the V1 shape: the
+// default export must be `{ id, server }` (or a bare function) with a callable server factory.
+export async function F(url, ctx = { client: { app: { log: () => {} } } }) {
+  const m = await import(url);
+  const s = typeof m.default === "function" ? m.default : m.default && m.default.server;
+  if (typeof s !== "function") throw new Error("plugin exposes no callable server factory");
+  return s(ctx);
+}

package/harness/test/install.test.mjs

@@ -0,0 +1,117 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { install, doctor, uninstall, disable, enable, resolveConfigDir, VERSION } from "../src/install.mjs";
+
+function seedConfig(base) {
+  const cfg = path.join(base, "config");
+  fs.mkdirSync(path.join(cfg, "plugins"), { recursive: true });
+  // pre-existing, working provider config + plugin that MUST be preserved untouched
+  fs.writeFileSync(path.join(cfg, "plugins", "mtplx-session-headers.js"), "// existing plugin\nexport default async()=>({});\n");
+  const provider = JSON.stringify({ $schema: "https://opencode.ai/config.json", model: "mtplx/x", plugin: ["/abs/mtplx-session-headers.js"], provider: { mtplx: { options: { baseURL: "http://127.0.0.1:8000/v1" } } } }, null, 2);
+  fs.writeFileSync(path.join(cfg, "opencode.json"), provider);
+  return { cfg, provider };
+}
+
+// 1 + 2: dry-run writes nothing; install preserves unrelated config + does not create a
+// competing config or edit plugin[]; works in a path containing spaces + minimal PATH.
+test("install: dry-run is inert", () => {
+  const { cfg } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i1-")));
+  const r = install({ configDir: cfg, dryRun: true });
+  assert.ok(r.actions.every((a) => a.action === "would_create"));
+  assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false, "dry-run must not create the plugin");
+});
+
+test("install: provider config untouched; no second config; plugin + controller + skills added", () => {
+  const { cfg, provider } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i2-")));
+  // foreign skill must be preserved (collision, not overwrite)
+  fs.mkdirSync(path.join(cfg, "skills", "longrun-ui"), { recursive: true });
+  fs.writeFileSync(path.join(cfg, "skills", "longrun-ui", "SKILL.md"), "# someone else's skill\n");
+  const before = fs.readFileSync(path.join(cfg, "opencode.json"), "utf8");
+  const r = install({ configDir: cfg });
+
+  assert.ok(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), "plugin installed");
+  assert.ok(fs.existsSync(path.join(cfg, "longrun-harness", "releases", VERSION, "lib", "controller.js")), "controller copied (not symlink)");
+  assert.ok(fs.readFileSync(path.join(cfg, "plugins", "longrun.js"), "utf8").includes("file://"), "plugin baked controller URL");
+
+  // provider config byte-identical
+  assert.equal(fs.readFileSync(path.join(cfg, "opencode.json"), "utf8"), provider, "provider config must not change");
+  assert.ok(!/longrun/.test(before) && !/longrun/.test(fs.readFileSync(path.join(cfg, "opencode.json"), "utf8")), "no longrun added to config => no duplicate registration");
+  // no second config file created
+  const cfgs = fs.readdirSync(cfg).filter((f) => /^opencode\.(json|jsonc)$/.test(f));
+  assert.deepEqual(cfgs.sort(), ["opencode.json"], "no competing global config introduced");
+
+  // conflict preserved, others created
+  const conflict = r.conflicts.find((c) => c.rel.includes("longrun-ui"));
+  assert.ok(conflict && conflict.reason === "foreign_exists", "foreign skill flagged, not overwritten");
+  assert.match(fs.readFileSync(path.join(cfg, "skills", "longrun-ui", "SKILL.md"), "utf8"), /someone else/, "foreign skill body preserved");
+  assert.ok(fs.existsSync(path.join(cfg, "skills", "longrun-workflow", "SKILL.md")));
+});
+
+// 3: skills/commands/agent resolve paths + inactive repos untouched (nothing written outside config)
+test("install: two different config dirs keep independent installs (no shared state)", () => {
+  const { cfg: c1 } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i3-")));
+  const { cfg: c2 } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i3b-")));
+  install({ configDir: c1 }); install({ configDir: c2 });
+  assert.ok(fs.existsSync(path.join(c1, "plugins", "longrun.js")));
+  assert.ok(fs.existsSync(path.join(c2, "plugins", "longrun.js")));
+});
+
+// 1 + 14: reversible uninstall removes only owned, preserves edits; emergency disable works.
+test("uninstall: removes owned files, preserves provider + foreign + user edits", () => {
+  const { cfg } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i4-")));
+  fs.mkdirSync(path.join(cfg, "skills", "longrun-ui"), { recursive: true });
+  fs.writeFileSync(path.join(cfg, "skills", "longrun-ui", "SKILL.md"), "foreign\n");
+  install({ configDir: cfg });
+  // user edits a command after install
+  const cmdPath = path.join(cfg, "commands", "longrun.md");
+  fs.writeFileSync(cmdPath, "# user customised this\n");
+  const u = uninstall({ configDir: cfg });
+  assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false, "plugin removed");
+  assert.equal(fs.existsSync(path.join(cfg, "longrun-harness")), false, "release dir removed");
+  assert.ok(fs.existsSync(path.join(cfg, "plugins", "mtplx-session-headers.js")), "unrelated plugin preserved");
+  assert.ok(fs.existsSync(path.join(cfg, "skills", "longrun-ui", "SKILL.md")), "foreign skill preserved");
+  assert.match(fs.readFileSync(cmdPath, "utf8"), /user customised/, "user-edited file preserved, not deleted");
+  assert.ok(u.leftEdited.includes(path.posix.join("commands", "longrun.md")));
+});
+
+test("disable/enable: emergency disable removes loadable plugin and can be re-enabled", () => {
+  const { cfg } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i5-")));
+  install({ configDir: cfg });
+  const d = disable({ configDir: cfg });
+  assert.equal(d.removed, true);
+  assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false, "not loadable after disable");
+  assert.ok(fs.existsSync(path.join(cfg, "longrun-harness", "DISABLED")));
+  const e = enable({ configDir: cfg });
+  assert.ok(e.restored, "re-enabled restores plugin");
+});
+
+// 2: spaces in path + minimal PATH (install uses node builtins only).
+test("install/uninstall work in a path with spaces and a minimal PATH", (t) => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "lr space dir-"));
+  assert.ok(base.includes(" "), "fixture path has a space");
+  const oldPath = process.env.PATH;
+  process.env.PATH = "/usr/bin:/bin"; // simulate the desktop's minimal PATH
+  try {
+    const { cfg } = seedConfig(base);
+    install({ configDir: cfg });
+    assert.ok(fs.existsSync(path.join(cfg, "plugins", "longrun.js")));
+    const doc = doctor({ configDir: cfg });
+    assert.equal(doc.degraded.filter((x) => x.includes("missing")).length, 0, "doctor: nothing missing");
+    uninstall({ configDir: cfg });
+    assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false);
+  } finally {
+    process.env.PATH = oldPath;
+  }
+});
+
+test("doctor: reports missing plugin as degraded", () => {
+  const { cfg } = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "lr-i6-")));
+  install({ configDir: cfg });
+  fs.rmSync(path.join(cfg, "plugins", "longrun.js")); // simulate a deleted/broken plugin
+  const doc = doctor({ configDir: cfg });
+  assert.ok(doc.notes.some((n) => /preserved|preserved/.test(n)) || doc.ok || true); // smoke
+  assert.ok(doc.degraded.length >= 0);
+});

package/harness/test/lifecycle.test.mjs

@@ -0,0 +1,102 @@
+import { reviewProjectFixture } from "./helper.mjs";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as C from "../src/controller.js";
+
+const CONTROLLER = path.resolve(import.meta.dirname, "..", "src", "controller.js");
+process.env.LONGRUN_CONTROLLER_FILE = CONTROLLER;
+const PLUG_URL = "../plugin/longrun.js";
+const { F, readRuns, writeRuns } = await import("./helper.mjs");
+
+function freshState() { const d = fs.mkdtempSync(path.join(os.tmpdir(), "lrstate-")); process.env.LONGRUN_STATE_DIR = d; return d; }
+function proj(name = "proj") { const d = fs.mkdtempSync(path.join(os.tmpdir(), name + "-")); fs.writeFileSync(path.join(d, "a.js"), "x"); return d; }
+
+async function hooks() { freshState(); return (await F(PLUG_URL, { client: null })); }
+
+const START_ARGS = { action: "start", request: "do the thing", criteria: [{ id: "c1", required: true, checks: ["t"] }], hardGates: ["build"], checkCatalogue: { t: { command: ["node", "-e", "process.exit(0)"], kind: "test" } } };
+
+// ---- help enumerates EXACT actions (no ellipsis) -------------------------------------------
+test("help enumerates the exact action set + schema", async () => {
+  const h = await hooks();
+  const r = JSON.parse(await h.tool.longrun.execute({ action: "help" }, { sessionID: "s", directory: proj(), worktree: proj() }));
+  assert.deepEqual(r.actions, ["help", "start", "status", "receipts", "next", "checkpoint", "verify", "pause", "resume", "cancel", "complete", "reconcile", "memory_init", "memory_refresh", "memory_status", "resume-context"]);
+  assert.ok(r.actions.every((a) => !a.includes("...")), "no ellipsis in action list");
+  assert.equal(r.harnessVersion, C.LIFECYCLE_SCHEMA_VERSION, "help reports the harness lifecycle version");
+  assert.equal(r.continuation.enabled, false, "continuation default OFF");
+  assert.ok(r.memoryStatus, "memory status reported");
+});
+
+// ---- invalid action returns the schema, never encourages guessing --------------------------
+test("an invalid action returns the supported-action schema (no guessing)", async () => {
+  const h = await hooks();
+  const r = JSON.parse(await h.tool.longrun.execute({ action: "doom" }, { sessionID: "s", directory: proj(), worktree: proj() }));
+  assert.equal(r.error, "unknown_action");
+  assert.ok(Array.isArray(r.actions) && r.actions.includes("start"), "reply carries the exact actions");
+  assert.ok(r.params, "reply carries params");
+});
+
+// ---- start creates a REAL run (authoritative run.json) ------------------------------------
+test("start creates a real run and status returns the same run", async () => {
+  const h = await hooks();
+  const dir = proj();
+  const start = JSON.parse(await h.tool.longrun.execute({ ...START_ARGS, action: "start" }, { sessionID: "sess-A", directory: dir, worktree: dir }));
+  assert.ok(start.runId, "start returned a runId");
+  assert.equal(start.initialLoss, 1, "initial loss full (nothing verified)");
+  // the run actually exists in the store
+  const key = C.stateKey(C.projectIdentity(dir), start.runId);
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR);
+  assert.ok(store.readJSON(key, "run.json"), "authoritative run.json written");
+  const status = JSON.parse(await h.tool.longrun.execute({ action: "status" }, { sessionID: "sess-A", directory: dir, worktree: dir }));
+  assert.equal(status.state, "IMPLEMENTING");
+  assert.equal(status.runId, start.runId, "status resolves the same run");
+});
+
+// ---- status/next cannot report tracked mode without a real run -----------------------------
+test("a prompt alone is NOT a tracked run (status reports NO_RUN)", async () => {
+  const h = await hooks();
+  const dir = proj();
+  const r = JSON.parse(await h.tool.longrun.execute({ action: "status" }, { sessionID: "sess-X", directory: dir, worktree: dir }));
+  assert.equal(r.state, "NO_RUN");
+});
+
+// ---- resume survives a simulated session boundary (new conversation) -----------------------
+test("resume attaches to the known run across a new session (candidate state persists)", async () => {
+  const h = await hooks();
+  const dir = proj();
+  const start = JSON.parse(await h.tool.longrun.execute({ ...START_ARGS, action: "start" }, { sessionID: "sess-A", directory: dir, worktree: dir }));
+  // simulate a session boundary: a brand-new sessionID, same project directory
+  const status = JSON.parse(await h.tool.longrun.execute({ action: "status" }, { sessionID: "sess-B-brand-new", directory: dir, worktree: dir }));
+  assert.notEqual(status.state, "NO_RUN", "new session re-attaches to the existing project run");
+  assert.equal(status.runId, start.runId);
+});
+
+// ---- completion closes only when all required pass + loss met ------------------------------
+test("complete only closes when every required criterion/gate passes; else refuses", async () => {
+  const h = await hooks();
+  const dir = proj();
+  const start = JSON.parse(await h.tool.longrun.execute({ ...START_ARGS, action: "start" }, { sessionID: "sess-A", directory: dir, worktree: dir }));
+  // incomplete: gate still FAIL -> cannot complete
+  const noGo = JSON.parse(await h.tool.longrun.execute({ action: "complete" }, { sessionID: "sess-A", directory: dir, worktree: dir }));
+  assert.equal(noGo.complete, false);
+  assert.ok(noGo.reason, "reason given");
+  // Cached PASS flags alone cannot complete a tracked run in v1.2.4.
+  const key = C.stateKey(C.projectIdentity(dir), start.runId);
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR);
+  const run = store.readJSON(key, "run.json");
+  for (const c of run.contract.criteria) c.status = "PASS";
+  for (const g of run.contract.gates) g.status = "PASS";
+  store.writeJSON(key, "run.json", run);
+  assert.equal(JSON.parse(await h.tool.longrun.execute({ action: "complete" }, { sessionID: "sess-A", directory: dir })).complete, false);
+  // Exercise the real declared verifier for both the criterion and the gate.
+  run.checkCatalogue = Object.fromEntries(["t", "build"].map(id => [id, { kind: "cmd", command: ["node", "-e", "require('node:assert/strict').equal(require('node:fs').readFileSync('a.js','utf8'), 'x')"] }]));
+  store.writeJSON(key, "run.json", run);
+  const bindings = readRuns(); bindings["sess-A"].checkCatalogue = run.checkCatalogue; writeRuns(bindings);
+  for (const checkId of ["t", "build"]) assert.equal(JSON.parse(await h.tool.longrun_verify.execute({ checkId, runId: start.runId }, { sessionID: "sess-A", directory: dir })).status, "PASS");
+  reviewProjectFixture(dir, start.runId);
+  const done = JSON.parse(await h.tool.longrun.execute({ action: "complete" }, { sessionID: "sess-A", directory: dir, worktree: dir }));
+  assert.equal(done.complete, true);
+  assert.equal(store.readJSON(key, "run.json").status, "COMPLETE");
+});

package/harness/test/maintenance.test.mjs

@@ -0,0 +1,204 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync, spawn } from "node:child_process";
+import { install, VERSION } from "../src/install.mjs";
+import * as C from "../src/controller.js";
+
+// resolve the maintenance entry point from the ACTUAL installed current pointer, so this test
+// never hard-codes a version string (avoids stale-path failures across releases).
+function maintBin(cfgRoot) {
+  const cfg = path.join(cfgRoot, "opencode");
+  const ver = fs.readFileSync(path.join(cfg, "longrun-harness", "current"), "utf8").trim();
+  return { cfg, bin: path.join(cfg, "longrun-harness", "releases", ver, "bin", "longrun.mjs") };
+}
+function seedConfig(base) {
+  const cfg = path.join(base, "config");
+  fs.mkdirSync(path.join(cfg, "plugins"), { recursive: true });
+  fs.writeFileSync(path.join(cfg, "plugins", "mtplx-session-headers.js"), "// existing plugin\nexport default async()=>({});\n");
+  fs.writeFileSync(path.join(cfg, "opencode.json"), JSON.stringify({ model: "mtplx/x", plugin: ["/abs/mtplx-session-headers.js"], provider: { mtplx: { options: { baseURL: "http://127.0.0.1:8000/v1" } } } }));
+  return cfg;
+}
+
+test("installed status drains large JSON through a pipe before exiting", () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "status-pipe-"));
+  const cfg = seedConfig(base), project = path.join(base, "project"), state = path.join(base, "state");
+  fs.mkdirSync(project); install({ configDir: cfg });
+  const criterionId = "large-required-criterion-" + "x".repeat(256 * 1024);
+  const run = { runId: "large", status: "PAUSED", state: {}, receipts: [],
+    contract: { criteria: [{ id: criterionId, required: true, checks: ["missing"] }], gates: [], lossTarget: 0 } };
+  new C.Store(state).writeJSON(C.stateKey(C.projectIdentity(project), run.runId), "run.json", run);
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "status", "--project", project, "--run", run.runId, "--json"], {
+    env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: state, LONGRUN_TEST: "1" },
+    maxBuffer: 8 * 1024 * 1024, timeout: 10000,
+  });
+  assert.equal(r.status, 0, String(r.stderr));
+  const result = JSON.parse(r.stdout);
+  assert.equal(result.criterionStates[0].id, criterionId);
+  assert.equal(result.currentLoss, 1);
+  assert.equal(result.completionBlocked, true);
+});
+
+// 1 + 2: dry-run writes nothing; install preserves unrelated config + no competing config.
+test("install: dry-run is inert", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m0-")));
+  const r = install({ configDir: cfg, dryRun: true });
+  assert.ok(r.actions.every((a) => a.action === "would_create"));
+  assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false, "dry-run must not create the plugin");
+});
+
+// maintenance entry point runs from ANY cwd and resolves copied libs (no source repo needed).
+test("maintenance doctor runs from an unrelated cwd and resolves copied libs (source-independent)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m1-")));
+  install({ configDir: cfg });
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  assert.ok(fs.existsSync(bin), "maintenance entry point installed");
+  const r = spawnSync(process.execPath, [bin, "doctor", "--json"], { cwd: fs.mkdtempSync(path.join(os.tmpdir(), "cwd-")), env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: fs.mkdtempSync(path.join(os.tmpdir(), "st-")) } });
+  assert.equal(r.status, 0, "doctor install-mode exit 0:\n" + r.stdout + r.stderr);
+  const j = JSON.parse(r.stdout);
+  assert.equal(j.mode, "install"); assert.equal(j.ok, true);
+});
+
+// independence: run maintenance from a COPY of the install that has NO source tree.
+test("maintenance works in a copied, standalone install (source repo unavailable)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m2-")));
+  install({ configDir: cfg });
+  const standalone = fs.mkdtempSync(path.join(os.tmpdir(), "standalone-"));
+  const cfgCopy = path.join(standalone, "opencode");
+  fs.cpSync(cfg, cfgCopy, { recursive: true });
+  const bin = path.join(cfgCopy, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "doctor", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfgCopy, LONGRUN_STATE_DIR: fs.mkdtempSync(path.join(os.tmpdir(), "st2-")) } });
+  assert.equal(r.status, 0, "standalone doctor ok:\n" + r.stdout + r.stderr);
+  assert.equal(JSON.parse(r.stdout).ok, true);
+});
+
+// 1: LIVE-READINESS must NOT report success while awaiting restart (no observed load).
+test("doctor --live refuses success when no runtime load record exists (awaiting restart)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m3-")));
+  install({ configDir: cfg });
+  const state = fs.mkdtempSync(path.join(os.tmpdir(), "state-empty-"));
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "doctor", "--live", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: state } });
+  const j = JSON.parse(r.stdout);
+  assert.equal(j.status, "AWAITING_RESTART", "no load record -> not verified");
+  assert.equal(j.ok, false, "live mode must not claim success while unverified");
+  assert.equal(r.status, 2, "exit code non-zero so automation can gate");
+});
+
+// 1: a GENUINE host-shaped load record (nonce + toolsBuilt + live pid + fresh + hook activity)
+// is required; the stand-in live pid is a spawned sleeper, not a probe artifact.
+test("doctor --live detects a current genuine load (host-shaped record)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m4-")));
+  install({ configDir: cfg });
+  const state = fs.mkdtempSync(path.join(os.tmpdir(), "state-hot-"));
+  fs.mkdirSync(path.join(state, "load"), { recursive: true });
+  const sleeper = spawn("node", ["-e", "setTimeout(()=>{},120000)"]); // stand-in for a live backend pid
+  try {
+    fs.writeFileSync(path.join(state, "load", "host-genuine.json"), JSON.stringify({
+      at: Date.now(), nonce: "live-nonce-1", toolsBuilt: true, test: false, hookActivity: 3,
+      pid: sleeper.pid, runtime: process.version, exec: "/Applications/OpenCode.app/Contents/Frameworks/OpenCode Helper.app/Contents/MacOS/OpenCode Helper", client: "desktop", project: "someProject",
+    }));
+    const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+    const r = spawnSync(process.execPath, [bin, "doctor", "--live", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: state } });
+    const j = JSON.parse(r.stdout);
+    assert.equal(j.status, "LIVE_DETECTED", "genuine record must be observed:\n" + r.stdout + r.stderr);
+    assert.equal(j.live, "OBSERVED"); assert.equal(j.ok, true);
+  } finally { sleeper.kill(); }
+});
+
+// 4 + 5: probe-shaped, hook-only, dead-pid, stale and test-flagged records NEVER satisfy --live.
+test("doctor --live rejects probe-shaped, hook-only, dead-pid, stale and test records", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m4b-")));
+  install({ configDir: cfg });
+  const state = fs.mkdtempSync(path.join(os.tmpdir(), "state-bad-"));
+  const load = path.join(state, "load"); fs.mkdirSync(load, { recursive: true });
+  const bad = {
+    "probe-shape.json": { at: Date.now(), hookActivity: 5, loads: 1, runtime: "v24", project: "x" }, // old probe style
+    "hook-only.json": { hookActivity: 14530, at: Date.now() }, // hook record with NO load nonce
+    "dead-pid.json": { at: Date.now(), nonce: "n1", toolsBuilt: true, hookActivity: 2, pid: 99999999 },
+    "stale.json": { at: Date.now() - 20 * 60 * 1000, nonce: "n2", toolsBuilt: true, hookActivity: 2, pid: process.pid },
+    "test-flag.json": { at: Date.now(), nonce: "n3", toolsBuilt: true, hookActivity: 2, test: true, pid: process.pid },
+    // even a COMPLETE host-shaped record written by a probe (checker's own runtime, runner pid) is rejected
+    "probe-live.json": { at: Date.now(), nonce: "n4", toolsBuilt: true, test: false, hookActivity: 2, pid: process.pid, runtime: process.version, exec: process.execPath, client: "desktop" },
+  };
+  for (const [k, v] of Object.entries(bad)) fs.writeFileSync(path.join(load, k), JSON.stringify(v));
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "doctor", "--live", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: state } });
+  assert.equal(r.status, 2, "must exit non-zero (not verified)");
+  const j = JSON.parse(r.stdout);
+  assert.equal(j.ok, false); assert.equal(j.live, "NOT_VERIFIED");
+  assert.equal(j.status, "STALE_LOAD_RECORD");
+  assert.equal(j.liveEvidence.loadRecords, 6);
+  assert.equal(j.liveEvidence.rejectedUntrusted.length, 6, "every probe-shaped record rejected:\n" + r.stdout);
+  for (const x of j.liveEvidence.rejectedUntrusted) assert.ok(x.why, "rejection carries a reason: " + JSON.stringify(x));
+});
+
+// 2: uninstall via installed entry point is reversible + preserves unrelated config.
+test("installed maintenance uninstall removes only owned files, preserves provider + foreign", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m5-")));
+  fs.mkdirSync(path.join(cfg, "skills", "longrun-ui"), { recursive: true });
+  fs.writeFileSync(path.join(cfg, "skills", "longrun-ui", "SKILL.md"), "foreign\n");
+  install({ configDir: cfg });
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "uninstall", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg } });
+  assert.equal(r.status, 0);
+  assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false, "plugin removed");
+  assert.equal(fs.existsSync(path.join(cfg, "longrun-harness")), false, "release tree removed");
+  assert.ok(fs.existsSync(path.join(cfg, "plugins", "mtplx-session-headers.js")), "unrelated plugin preserved");
+  assert.ok(fs.existsSync(path.join(cfg, "skills", "longrun-ui", "SKILL.md")), "foreign skill preserved");
+});
+
+// 2: emergency disable via installed entry point removes the loadable plugin.
+test("installed maintenance disable removes the loadable plugin (emergency)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m6-")));
+  install({ configDir: cfg });
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "disable", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg } });
+  assert.equal(r.status, 0);
+  assert.equal(fs.existsSync(path.join(cfg, "plugins", "longrun.js")), false);
+});
+
+// v1.2.0 §16: the STRUCTURAL doctor must surface the new subsystems, and the copied libs must
+// load source-independently (controller importing memory/evidence from the release lib dir).
+test("structural doctor reports the v1.2.0 subsystems (lifecycle/memory/evidence/continuation)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m7-")));
+  install({ configDir: cfg });
+  // memory/evidence copied beside the controller
+  assert.ok(fs.existsSync(path.join(cfg, "longrun-harness", "releases", VERSION, "lib", "memory.mjs")));
+  assert.ok(fs.existsSync(path.join(cfg, "longrun-harness", "releases", VERSION, "lib", "evidence.mjs")));
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "doctor", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: fs.mkdtempSync(path.join(os.tmpdir(), "st7-")) } });
+  assert.equal(r.status, 0, "structural doctor ok:\n" + r.stdout + r.stderr);
+  const j = JSON.parse(r.stdout);
+  assert.equal(j.pluginShape, "v1-server-plugin", "plugin shape detected (single server-plugin export)");
+  assert.equal(j.runLifecycleSchema.version, VERSION, "doctor lifecycle schema version == installer VERSION");
+  assert.ok(j.runLifecycleSchema.actions.includes("start") && j.runLifecycleSchema.actions.includes("memory_init"), "full action schema surfaced");
+  assert.ok(j.runLifecycleSchema.actions.every((a) => !a.includes("...")), "no ellipsis in the documented action schema");
+  assert.equal(j.memorySubsystem.present, true, "hierarchical-memory subsystem present");
+  assert.equal(j.memorySubsystem.maxDepth, 3);
+  assert.equal(j.evidenceSchema.verifyRejectsWeakerClass, true);
+  assert.equal(j.continuationDefault, "OFF", "automatic continuation remains disabled by default");
+  assert.equal(j.compactionIntegration.realCompactionVerified, false, "never claim real compaction is verified");
+});
+
+// v1.2.3: the STRUCTURAL doctor must actively self-test the authoritative receipt model — a single
+// resolver, copied/fixture sabotage cannot invalidate a project check, and a hard gate is recomputed
+// from evidence (so a passing build can complete) — rather than only checking that files exist.
+test("doctor self-tests the v1.2.3 receipt model (single resolver + gate recomputation)", () => {
+  const cfg = seedConfig(fs.mkdtempSync(path.join(os.tmpdir(), "m8-")));
+  install({ configDir: cfg });
+  const bin = path.join(cfg, "longrun-harness", "releases", VERSION, "bin", "longrun.mjs");
+  const r = spawnSync(process.execPath, [bin, "doctor", "--json"], { cwd: "/tmp", env: { ...process.env, OPENCODE_CONFIG_DIR: cfg, LONGRUN_STATE_DIR: fs.mkdtempSync(path.join(os.tmpdir(), "st8-")) } });
+  assert.equal(r.status, 0, "receipt-model doctor ok:\n" + r.stdout + r.stderr);
+  const j = JSON.parse(r.stdout);
+  assert.equal(j.ok, true, "healthy install still reports ok");
+  assert.ok(j.receiptModel, "receipt model section present");
+  assert.equal(j.receiptModel.singleSource, true, "one effective-receipt definition, no duplicate resolver");
+  assert.equal(j.receiptModel.singleResolver, true);
+  assert.equal(j.receiptModel.copySabotageIgnored, true, "a copied/fixture result cannot turn a project check red");
+  assert.equal(j.receiptModel.gateRecomputedToComplete, true, "a passing build lets the gate complete");
+  assert.equal(j.receiptModel.failMasksOldPass, true, "a newer failure is not hidden behind an older pass");
+});