opencode-longrun-harness 1.2.22

package/harness/test/toolbehavior.test.mjs

@@ -0,0 +1,75 @@
+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 } from "node:child_process";
+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 PLUG_FILE = path.resolve(import.meta.dirname, "..", "plugin", "longrun.js").split(path.sep).join("/");
+const { F } = await import("./helper.mjs");
+
+function freshState() { const d = fs.mkdtempSync(path.join(os.tmpdir(), "tb-st-")); process.env.LONGRUN_STATE_DIR = d; return d; }
+
+// 1 + 2: help + schema are self-describing; NO action-name guessing is ever required.
+test("help is self-describing (actions + params + version + continuation OFF)", async () => {
+  freshState();
+  const h = await F(PLUG_URL, { client: null });
+  const r = JSON.parse(await h.tool.longrun.execute({ action: "help" }, { sessionID: "s", directory: os.tmpdir(), worktree: os.tmpdir() }));
+  assert.ok(r.actions.every((a) => r.params[a] !== undefined), "every action documents its params");
+  assert.ok(r.actions.includes("start") && r.actions.includes("memory_init"));
+  assert.equal(r.harnessVersion, C.LIFECYCLE_SCHEMA_VERSION, "help reports the harness lifecycle version");
+});
+test("a rejected action tells the model to read the schema, never to guess", async () => {
+  freshState();
+  const h = await F(PLUG_URL, { client: null });
+  const r = JSON.parse(await h.tool.longrun.execute({ action: "frobnicate" }, { sessionID: "s", directory: os.tmpdir(), worktree: os.tmpdir() }));
+  assert.equal(r.error, "unknown_action");
+  assert.match(r.detail, /Do NOT brute-force/, "explicitly discourages action-name guessing");
+});
+
+// 3: probes/tests can never contaminate live evidence (import != load; non-host != host).
+const CHILD_ENV = (state) => { const e = { ...process.env, LONGRUN_STATE_DIR: state }; delete e.LONGRUN_TEST; delete e.NODE_TEST_CONTEXT; delete e.OPENCODE_CLIENT; return e; };
+
+test("importing the plugin creates no live evidence, even with a state dir set", () => {
+  const state = fs.mkdtempSync(path.join(os.tmpdir(), "tb-noev-"));
+  const r = spawnSync(process.execPath, ["--input-type=module", "-e", `await import("file://${PLUG_FILE}");`], { env: CHILD_ENV(state) });
+  assert.equal(r.status, 0, "child import ran: " + r.stderr);
+  assert.deepEqual(fs.readdirSync(state), [], "a bare import writes nothing");
+});
+
+test("a plain-node probe driving real tool actions cannot forge a load record or touch default state", () => {
+  const state = fs.mkdtempSync(path.join(os.tmpdir(), "tb-probe-"));
+  const proj = fs.mkdtempSync(path.join(os.tmpdir(), "tb-proj-"));
+  fs.writeFileSync(path.join(proj, "a.js"), "x");
+  // A non-host child (no OPENCODE_CLIENT/electron): even a full start+verify must not create a
+  // live "load" record, and must not write into the DEFAULT production state dir.
+  const code = `
+    const m = await import("file://${PLUG_FILE}");
+    const C = await import("file://${CONTROLLER}");
+    const hooks = await m.default.server({ client: null });
+    const ctx = { sessionID: "probe", agent: "longrun", directory: "${proj}", worktree: "${proj}" };
+    await hooks.tool.longrun.execute({ action: "start", request: "x", criteria: [{ id: "c1", checks: ["t"] }] }, ctx);
+    const fs = await import("node:fs"); const path = await import("node:path");
+    const st = process.env.LONGRUN_STATE_DIR;
+    process.stdout.write(JSON.stringify({
+      hasLoadDir: fs.existsSync(path.join(st, "load")),
+      stateKeys: fs.readdirSync(st),
+    }));
+  `;
+  const r = spawnSync(process.execPath, ["--input-type=module", "-e", code], { env: CHILD_ENV(state) });
+  assert.equal(r.status, 0, "child ran: " + r.stderr);
+  const out = JSON.parse(r.stdout);
+  assert.equal(out.hasLoadDir, false, "a non-host probe must not create live-load evidence");
+});
+
+test("the longrun tool never accepts arbitrary shell / undeclared work", async () => {
+  freshState();
+  const h = await F(PLUG_URL, { client: null });
+  // verify still refuses anything outside the declared catalogue (no shell bypass)
+  const res = JSON.parse(await h.tool.longrun_verify.execute({ checkId: "rm -rf /" }, { sessionID: "ghost", directory: os.tmpdir(), worktree: os.tmpdir() }));
+  assert.equal(res.error, "NO_RUN", "no run -> nothing to run (still no shell path)");
+});

package/harness/test/v121-commissioning.test.mjs

@@ -0,0 +1,177 @@
+import { reviewProjectFixture } from "./helper.mjs";
+// v1.2.1 commissioning fixes, verified deterministically.
+// There is NO live OpenCode host in this environment and the plugin deliberately refuses to treat
+// a test/probe process as a host (isHostProcess), so a REAL live-tool run cannot occur here.
+// These tests drive the REAL plugin tool factory + the REAL controller (the harness's own
+// equivalent of the live tool surface) through the full lifecycle, with LONGRUN_TEST armed so no
+// evidence can ever be written into a production state dir. Nothing here touches production
+// source, OpenCode config, model/sampler/context, permissions, compaction or continuation.
+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";
+import { VERSION as INSTALL_VERSION } from "../src/install.mjs";
+
+const CONTROLLER = path.resolve(import.meta.dirname, "..", "src", "controller.js");
+process.env.LONGRUN_CONTROLLER_FILE = CONTROLLER;
+const PLUG_URL = "../plugin/longrun.js";
+const { F } = await import("./helper.mjs");
+
+function freshState() { const d = fs.mkdtempSync(path.join(os.tmpdir(), "v121-st-")); process.env.LONGRUN_STATE_DIR = d; return d; }
+function projWithFile() { const d = fs.mkdtempSync(path.join(os.tmpdir(), "v121-proj-")); fs.writeFileSync(path.join(d, "a.js"), "x"); return d; }
+async function tools() { const h = await F(PLUG_URL, { client: null }); return h.tool; }
+const ctx = (d) => ({ sessionID: "v121", agent: "longrun", directory: d, worktree: d });
+
+// ---- version alignment: single source of truth, no drift (controller/package/plugin/installer) --
+test("v1.2.1 version alignment (package == controller == plugin == installer)", () => {
+  const pkg = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, "..", "..", "package.json"), "utf8"));
+  const plugSrc = fs.readFileSync(path.resolve(import.meta.dirname, "..", "plugin", "longrun.js"), "utf8");
+  assert.equal(pkg.version, "1.2.22", "package.json bumped");
+  assert.equal(C.LIFECYCLE_SCHEMA_VERSION, pkg.version, "controller lifecycle schema version tracks package");
+  assert.equal(INSTALL_VERSION, pkg.version, "installer VERSION tracks package");
+  assert.ok(plugSrc.includes(`const VERSION = "${pkg.version}"`), "plugin VERSION literal matches package");
+  assert.ok(plugSrc.includes(`in v${pkg.version}`), "help continuation note not stale");
+});
+
+// ---- BUG 1: an incomplete contract is refused at START, and no run is created ------------------
+test("start refuses a required criterion with no mapped check (INVALID_CONTRACT, no run created)", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  const res = JSON.parse(await t.longrun.execute({ action: "start", request: "lifecycle check", criteria: [{ id: "LC-001", evidenceClass: "STATIC", weight: 1 }] }, ctx(d)));
+  assert.equal(res.error, "INVALID_CONTRACT", "no run for an unverifiable criterion");
+  assert.ok(Array.isArray(res.problems) && res.problems.length === 1 && res.problems[0].criterionId === "LC-001", "names the incomplete criterion");
+  // no run was written -> a later status is still NO_RUN (prompt alone is not a run)
+  const st = JSON.parse(await t.longrun.execute({ action: "status" }, ctx(d)));
+  assert.equal(st.state, "NO_RUN", "incomplete contract created NO tracked run");
+});
+
+test("start refuses a criterion whose checks are absent from checkCatalogue (INVALID_CONTRACT)", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  const res = JSON.parse(await t.longrun.execute({ action: "start", request: "x", criteria: [{ id: "c1", checks: ["ghost"] }], checkCatalogue: { other: { command: ["node", "-e", "0"], kind: "cmd" } } }, ctx(d)));
+  assert.equal(res.error, "INVALID_CONTRACT");
+  assert.deepEqual(res.problems[0].missingChecks, ["ghost"], "names the missing declared check");
+});
+
+// ---- memory subsystem works WITHOUT a run, into an isolated fixture only ----------------------
+test("memory_status returns success at run=null (was NO_RUN in v1.2.0)", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  const res = JSON.parse(await t.longrun.execute({ action: "memory_status" }, ctx(d)));
+  assert.notEqual(res.state, "NO_RUN", "memory_status is a structural readout, not a run check");
+  assert.equal(res.status, "NO_MEMORY");
+  assert.equal(res.run, null);
+});
+
+test("memory_init at run=null runs; dryRun writes nothing into the fixture", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  const before = fs.readdirSync(d);
+  const dry = JSON.parse(await t.longrun.execute({ action: "memory_init", dryRun: true }, ctx(d)));
+  assert.equal(dry.dryRun, true);
+  assert.equal(dry.state, "MEMORY");
+  assert.deepEqual(fs.readdirSync(d), before, "dryRun wrote nothing");
+  // and a real memory_init still does NOT start a tracked run
+  await t.longrun.execute({ action: "memory_init" }, ctx(d));
+  assert.equal(JSON.parse(await t.longrun.execute({ action: "status" }, ctx(d))).state, "NO_RUN", "memory seeding is not a tracked run");
+});
+
+// ---- the tool contract: verify readout never executes; verify execution is longrun_verify only --
+test("longrun action=verify is a read-only readout and longrun_verify has no shell bypass", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  // no run -> verify readout is not even reached for run state; assert the no-shell invariant holds
+  const v = JSON.parse(await t.longrun_verify.execute({ checkId: "rm -rf /" }, ctx(d)));
+  assert.equal(v.error, "NO_RUN", "verify tool runs nothing without a declared check + run");
+});
+
+// ---- FULL lifecycle through the real tool surface ---------------------------------------------
+test("full lifecycle: memory -> start -> status -> checkpoint -> pause -> resume -> verify -> loss0 -> complete (same runId)", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  const c = ctx(d);
+
+  // memory gate (works at run=null), isolated fixture
+  const ms = JSON.parse(await t.longrun.execute({ action: "memory_status" }, c));
+  assert.equal(ms.status, "NO_MEMORY");
+  await t.longrun.execute({ action: "memory_init" }, c);
+
+  // start a valid, completable contract: one STATIC criterion mapped to a declared check
+  const start = JSON.parse(await t.longrun.execute({
+    action: "start",
+    request: "Verify that longrun v1.2.1 can create, persist, pause, resume, checkpoint and complete a native tracked run.",
+    criteria: [{ id: "LC-001", required: true, weight: 1, evidenceClass: "STATIC", checks: ["lc-static"] }],
+    checkCatalogue: { "lc-static": { command: ["node", "-e", "process.exit(0)"], kind: "cmd", timeoutMs: 15000 } },
+    candidateBudget: 3, timeBudgetHours: 0.25, sameFailureThreshold: 2, noProgressThreshold: 2, autoContinue: false,
+  }, c));
+  assert.ok(start.runId, "start returned a real runId");
+  const RUN = start.runId;
+  assert.equal(start.initialLoss, 1);
+  assert.equal(start.budgets.iterations, 3, "candidate budget honoured");
+  assert.equal(start.budgets.sameFailureLimit, 2);
+  assert.equal(start.budgets.noProgressLimit, 2);
+
+  const key = C.stateKey(C.projectIdentity(d), RUN);
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR);
+  const readRun = () => store.readJSON(key, "run.json");
+  const budgetsOf = () => { const r = readRun(); return JSON.stringify({ it: r.budget.iterations, sf: r.budget.sameFailureLimit, np: r.budget.noProgressLimit, cand: C.candidateCount(r) }); };
+
+  const s1 = JSON.parse(await t.longrun.execute({ action: "status" }, c));
+  assert.equal(s1.runId, RUN); assert.equal(s1.state, "IMPLEMENTING");
+  const budgetBefore = budgetsOf();
+
+  assert.equal(await t.longrun.execute({ action: "checkpoint" }, c), "checkpointed");
+
+  assert.equal(await t.longrun.execute({ action: "pause" }, c), "paused");
+  const sPaused = JSON.parse(await t.longrun.execute({ action: "status" }, c));
+  assert.equal(sPaused.state, "PAUSED", "pause persisted");
+  assert.equal(sPaused.runId, RUN, "runId unchanged by pause");
+
+  const sRes = JSON.parse(await t.longrun.execute({ action: "resume" }, c));
+  assert.equal(sRes.runId, RUN, "runId unchanged by resume");
+  assert.equal(sRes.state, "IMPLEMENTING", "resume returns to an active state");
+  const budgetAfter = budgetsOf();
+  assert.equal(budgetBefore, budgetAfter, "budgets + candidate accounting preserved across pause/resume");
+
+  // record a STATIC PASS via the dedicated verify tool; then completion is possible
+  const vr = JSON.parse(await t.longrun_verify.execute({ checkId: "lc-static", evidenceClass: "STATIC", mode: "normal" }, c));
+  assert.equal(vr.status, "PASS", "declared STATIC check recorded a PASS receipt");
+
+  const sVerified = JSON.parse(await t.longrun.execute({ action: "status" }, c));
+  assert.equal(sVerified.runId, RUN);
+  assert.equal(sVerified.criterionStates.find((x) => x.id === "LC-001").status, "PASS", "criterion derived from a real receipt without rewriting the contract");
+  assert.deepEqual(sVerified.remaining, [], "no required criteria outstanding");
+  reviewProjectFixture(d, RUN);
+  assert.equal(JSON.parse(await t.longrun.execute({ action: "complete" }, c)).complete, true, "loss reached 0 only after verification");
+  assert.equal(readRun().status, "COMPLETE");
+  assert.equal(JSON.parse(await t.longrun.execute({ action: "status" }, c)).state, "COMPLETE");
+});
+
+// ---- completion is blocked while the sole required check is unverified (no fabricated pass) -----
+test("complete refuses while the required check is unverified; no fabricated PASS", async () => {
+  freshState();
+  const t = await tools();
+  const d = projWithFile();
+  const c = ctx(d);
+  const start = JSON.parse(await t.longrun.execute({
+    action: "start", request: "x",
+    criteria: [{ id: "LC-001", required: true, checks: ["lc-static"] }],
+    checkCatalogue: { "lc-static": { command: ["node", "-e", "process.exit(1)"], kind: "cmd" } },
+  }, c));
+  assert.ok(start.runId);
+  const noGo = JSON.parse(await t.longrun.execute({ action: "complete" }, c));
+  assert.equal(noGo.complete, false);
+  assert.equal(noGo.reason, "required_unverified", "blocked on the outstanding required criterion");
+  // a FAIL receipt must not satisfy it either
+  const vr = JSON.parse(await t.longrun_verify.execute({ checkId: "lc-static", evidenceClass: "STATIC" }, c));
+  assert.equal(vr.status, "FAIL");
+  assert.equal(JSON.parse(await t.longrun.execute({ action: "complete" }, c)).complete, false, "still blocked after a FAIL");
+});

package/harness/test/v1210-deadline.test.mjs

@@ -0,0 +1,134 @@
+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';
+import { F } from './helper.mjs';
+
+process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+async function setup(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1210-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const dir = path.join(root, 'project'), state = path.join(root, 'state');
+  fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'source.txt'), 'deadline fixture');
+  process.env.LONGRUN_STATE_DIR = state;
+  const hooks = await F('../plugin/longrun.js', { client: null, directory: dir, worktree: dir });
+  const ctx = { sessionID: 'owner', directory: dir, worktree: dir };
+  const marker = path.join(dir, 'must-not-execute');
+  const started = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Offline deadline admission fixture',
+    criteria: [{ id: 'c', evidenceClass: 'STATIC', checks: ['check'] }],
+    checkCatalogue: { check: { kind: 'cmd', command: [process.execPath, '-e', `require('node:fs').writeFileSync(${JSON.stringify(marker)},'executed')`] } } }, ctx));
+  const store = new C.Store(state), key = C.stateKey(C.projectIdentity(dir), started.runId);
+  const file = store._file(key, 'run.json');
+  const guard = (tool, args = {}, sessionID = ctx.sessionID) => hooks['tool.execute.before']({ tool, sessionID }, { args });
+  const expire = status => store.mutate(key, r => { r.createdAt = Date.now() - r.budget.deadlineSeconds * 1000 - 1000; if (status) r.status = status; return { ok: true }; });
+  return { root, dir, state, hooks, ctx, marker, store, key, file, guard, expire, runId: started.runId };
+}
+
+test('expired ordinary tool admission blocks reads, edits, shell and delegation without changing evidence', async t => {
+  const s = await setup(t); s.expire();
+  const before = fs.readFileSync(s.file);
+  for (const tool of ['bash', 'write', 'edit', 'apply_patch', 'task', 'batch', 'read', 'glob', 'grep', 'skill', 'some_mcp_tool']) {
+    await assert.rejects(s.guard(tool), /LONGRUN_DEADLINE_EXPIRED/);
+  }
+  assert.deepEqual(fs.readFileSync(s.file), before);
+  assert.equal(fs.existsSync(s.marker), false);
+});
+
+test('deadline admission uses canonical time at the exact boundary, not cached session flags', async t => {
+  const s = await setup(t), run = s.store.readJSON(s.key, 'run.json');
+  const deadline = run.createdAt + run.budget.deadlineSeconds * 1000, clock = Date.now;
+  try {
+    Date.now = () => deadline - 1; await s.guard('bash');
+    Date.now = () => deadline; await assert.rejects(s.guard('bash'), /LONGRUN_DEADLINE_EXPIRED/);
+  } finally { Date.now = clock; }
+  s.expire('PAUSED');
+  const bindings = JSON.parse(fs.readFileSync(path.join(s.state, 'runs.json')));
+  bindings.owner.paused = true; bindings.owner.disabled = true;
+  fs.writeFileSync(path.join(s.state, 'runs.json'), JSON.stringify(bindings));
+  await assert.rejects(s.guard('edit'), /LONGRUN_DEADLINE_EXPIRED/);
+});
+
+test('fresh sessions cannot bypass a project deadline when routing indices are absent', async t => {
+  const s = await setup(t); s.expire();
+  fs.unlinkSync(path.join(s.state, 'runs.json')); fs.unlinkSync(path.join(s.state, 'projects.json'));
+  const before = fs.readFileSync(s.file);
+  await assert.rejects(s.guard('bash', {}, 'fresh-session'), /LONGRUN_DEADLINE_EXPIRED/);
+  await assert.rejects(s.guard('task', {}, 'fresh-session'), /LONGRUN_DEADLINE_EXPIRED/);
+  assert.deepEqual(fs.readFileSync(s.file), before);
+  const foreign = path.join(s.root, 'other'); fs.mkdirSync(foreign);
+  const other = await F('../plugin/longrun.js', { client: null, directory: foreign, worktree: foreign });
+  await other['tool.execute.before']({ tool: 'bash', sessionID: 'untracked-other' }, { args: {} });
+});
+
+test('expired native bookkeeping and explicit check refusal remain available, while memory writes and replacement start are refused', async t => {
+  const s = await setup(t); s.expire();
+  const before = s.store.readJSON(s.key, 'run.json');
+  for (const action of ['help', 'status', 'next', 'resume-context', 'verify', 'checkpoint', 'pause', 'cancel', 'complete', 'resume', 'reconcile', 'memory_status']) await s.guard('longrun', { action, runId: s.runId });
+  for (const action of ['memory_init', 'memory_refresh', 'start']) await assert.rejects(s.guard('longrun', { action }), /LONGRUN_DEADLINE_EXPIRED/);
+  await s.guard('longrun_verify', { checkId: 'check', runId: s.runId });
+  const refusal = JSON.parse(await s.hooks.tool.longrun_verify.execute({ checkId: 'check', runId: s.runId, evidenceClass: 'STATIC' }, s.ctx));
+  assert.equal(refusal.error, 'BUDGET_EXHAUSTED'); assert.equal(refusal.spent.deadline, true);
+  await s.hooks.tool.longrun.execute({ action: 'checkpoint', runId: s.runId, progress: { nextAction: 'Expired fixture; preserve incomplete evidence.' } }, s.ctx);
+  assert.equal(await s.hooks.tool.longrun.execute({ action: 'pause', runId: s.runId }, s.ctx), 'paused');
+  const after = s.store.readJSON(s.key, 'run.json');
+  for (const key of ['runId', 'contract', 'contractHash', 'budget', 'createdAt', 'state', 'receipts', 'execution']) assert.deepEqual(after[key], before[key], key);
+  assert.equal(after.status, 'PAUSED'); assert.equal(after.autoEnabled, false); assert.equal(fs.existsSync(s.marker), false);
+});
+
+test('unreadable canonical state cannot silently disable admission enforcement for a bound session', async t => {
+  const s = await setup(t);
+  for (const bytes of ['{ corrupt canonical bytes', 'null']) {
+    fs.writeFileSync(s.file, bytes);
+    await assert.rejects(s.guard('bash'), /ROUTING_STORE_ERROR/);
+    assert.equal(fs.readFileSync(s.file, 'utf8'), bytes);
+  }
+  fs.unlinkSync(s.file);
+  await assert.rejects(s.guard('bash'), /ROUTING_STORE_ERROR/);
+});
+
+test('recovery and status expose authoritative wall-clock timing without mutating the persisted run', async t => {
+  const s = await setup(t), run = s.store.readJSON(s.key, 'run.json'), before = structuredClone(run);
+  const deadline = run.createdAt + run.budget.deadlineSeconds * 1000;
+  const view = C.deriveRunView(run, { now: deadline - 1250 });
+  assert.deepEqual(view.timing, { observedAt: deadline - 1250, startedAt: run.createdAt, deadlineAt: deadline, remainingMs: 1250, expired: false, scope: 'absolute_wall_clock_since_run_creation' });
+  const packet = C.buildRecoveryPacket(run, 1500, view).packet;
+  assert.ok(packet.includes(new Date(deadline - 1250).toISOString()));
+  assert.ok(packet.includes(new Date(deadline).toISOString()));
+  assert.match(packet, /DEADLINE REMAINING: 1250 ms/);
+  const expired = C.deriveRunView(run, { now: deadline });
+  assert.equal(expired.timing.expired, true); assert.equal(expired.timing.remainingMs, 0);
+  assert.match(C.buildRecoveryPacket(run, 1500, expired).packet, /DEADLINE EXPIRED.*checkpoint.*pause/);
+  assert.deepEqual(run, before);
+});
+
+test('legacy unknown timestamps are explicit rather than manufactured, including in recovery context', async t => {
+  const s = await setup(t), run = s.store.readJSON(s.key, 'run.json'); delete run.createdAt;
+  const view = C.deriveRunView(run, { now: 1700000000000 });
+  assert.equal(view.timing.deadlineAt, null); assert.equal(view.timing.remainingMs, null); assert.equal(view.timing.expired, null);
+  const packet = C.buildRecoveryPacket(run, 1500, view).packet;
+  assert.match(packet, /DEADLINE: UNKNOWN/); assert.match(packet, /DEADLINE REMAINING: UNKNOWN/);
+  assert.equal(Object.hasOwn(run, 'createdAt'), false);
+});
+
+test('an expired foreign-project binding cannot impose its deadline on the actual host project', async t => {
+  const s = await setup(t); s.expire();
+  const foreign = path.join(s.root, 'foreign-project'); fs.mkdirSync(foreign);
+  const other = await F('../plugin/longrun.js', { client: null, directory: foreign, worktree: foreign });
+  await other['tool.execute.before']({ tool: 'bash', sessionID: s.ctx.sessionID }, { args: {} });
+});
+
+test('native status and recovery observe time afresh, without changing the deadline or source ledger', async t => {
+  const s = await setup(t), run = s.store.readJSON(s.key, 'run.json');
+  let now = run.createdAt + 1000; t.mock.method(Date, 'now', () => now);
+  const first = JSON.parse(await s.hooks.tool.longrun.execute({ action: 'status', runId: s.runId }, s.ctx));
+  now += 8000;
+  const second = JSON.parse(await s.hooks.tool.longrun.execute({ action: 'status', runId: s.runId }, s.ctx));
+  assert.equal(second.timing.observedAt - first.timing.observedAt, 8000);
+  assert.equal(first.timing.remainingMs - second.timing.remainingMs, 8000);
+  assert.equal(first.timing.deadlineAt, second.timing.deadlineAt);
+  const packet = await s.hooks.tool.longrun.execute({ action: 'resume-context', runId: s.runId }, s.ctx);
+  assert.ok(packet.includes(new Date(now).toISOString()));
+  assert.deepEqual(s.store.readJSON(s.key, 'run.json'), run);
+});

package/harness/test/v1211-pause.test.mjs

@@ -0,0 +1,81 @@
+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';
+import { F } from './helper.mjs';
+process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+
+async function setup(t) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1211-'));
+  t.after(() => fs.rmSync(base, { recursive: true, force: true }));
+  const dir = path.join(base, 'project'); fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'value.txt'), 'unchanged');
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  const hooks = await F('../plugin/longrun.js', { client: null, directory: dir, worktree: dir });
+  const ctx = { sessionID: 'owner', directory: dir, worktree: dir }, other = { ...ctx, sessionID: 'other' };
+  const run = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Isolated pause admission fixture',
+    criteria: [{ id: 'check', evidenceClass: 'STATIC', checks: ['check'] }],
+    checkCatalogue: { check: { kind: 'cmd', command: [process.execPath, '-e', "require('node:assert/strict').equal(require('node:fs').readFileSync('value.txt','utf8'),'unchanged')"] } } }, ctx));
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), run.runId), file = store._file(key, 'run.json');
+  const call = (action, context = ctx) => hooks.tool.longrun.execute({ action, runId: run.runId }, context);
+  const guard = (tool, args = {}, sessionID = ctx.sessionID) => hooks['tool.execute.before']({ tool, sessionID }, { args });
+  return { hooks, ctx, other, call, guard, store, key, file, runId: run.runId };
+}
+
+test('pause from another host blocks ordinary execution despite the old session active flag', async t => {
+  const s = await setup(t); await s.call('pause', s.other);
+  const before = fs.readFileSync(s.file);
+  for (const tool of ['bash', 'edit', 'write', 'apply_patch', 'task', 'batch', 'unknown_mcp_tool']) {
+    await assert.rejects(s.guard(tool), /LONGRUN_RUN_PAUSED/);
+  }
+  assert.deepEqual(fs.readFileSync(s.file), before);
+});
+
+test('paused inspection, native checkpoint and authorized resume remain usable without resetting evidence', async t => {
+  const s = await setup(t); await s.call('pause');
+  const before = s.store.readJSON(s.key, 'run.json');
+  for (const tool of ['read', 'glob', 'grep', 'list', 'skill', 'question', 'todowrite', 'longrun_verify']) await s.guard(tool);
+  for (const action of ['help', 'status', 'next', 'resume-context', 'verify', 'checkpoint', 'pause', 'resume', 'cancel', 'reconcile']) await s.guard('longrun', { action });
+  for (const action of ['memory_init', 'memory_refresh']) await assert.rejects(s.guard('longrun', { action }), /LONGRUN_RUN_PAUSED/);
+  assert.equal(JSON.parse(await s.call('resume')).resumed, true);
+  await s.guard('edit'); await s.guard('bash');
+  const after = s.store.readJSON(s.key, 'run.json');
+  for (const field of ['runId', 'createdAt', 'contract', 'contractHash', 'budget', 'state', 'receipts', 'execution']) assert.deepEqual(after[field], before[field], field);
+  assert.equal(after.autoEnabled, false);
+});
+
+test('a fresh session in the paused project cannot mutate before explicit resume', async t => {
+  const s = await setup(t); await s.call('pause');
+  await assert.rejects(s.guard('write', {}, 'fresh'), /LONGRUN_RUN_PAUSED/);
+  await s.guard('read', {}, 'fresh');
+  assert.equal(JSON.parse(await s.call('resume', { ...s.ctx, sessionID: 'fresh' })).resumed, true);
+  await s.guard('write', {}, 'fresh');
+});
+
+test('a tracked terminal run cannot continue ordinary implementation, but native new-task admission stays available', async t => {
+  for (const action of ['cancel', 'complete']) {
+    const s = await setup(t);
+    if (action === 'complete') {
+      const checked = JSON.parse(await s.hooks.tool.longrun_verify.execute({ runId: s.runId, checkId: 'check', evidenceClass: 'STATIC' }, s.ctx));
+      assert.equal(checked.status, 'PASS');
+      reviewProjectFixture(s.ctx.directory, s.runId);
+    }
+    const result = await s.call(action); if (action === 'complete') assert.equal(JSON.parse(result).complete, true);
+    const before = fs.readFileSync(s.file);
+    await assert.rejects(s.guard('bash'), action === 'complete' ? /LONGRUN_RUN_COMPLETE/ : /LONGRUN_RUN_CANCELLED/);
+    await s.guard('longrun', { action: 'start' }); await s.guard('read');
+    assert.deepEqual(fs.readFileSync(s.file), before);
+  }
+});
+
+test('non-executing canonical states fail closed while existing compaction recovery keeps its diagnostic', async t => {
+  for (const state of ['READY', 'BLOCKED', 'COMPACTING', 'RECOVERY_REQUIRED', 'INVALID_STATE']) {
+    const s = await setup(t); s.store.mutate(s.key, r => { r.status = state; return { ok: true }; });
+    const before = fs.readFileSync(s.file);
+    await assert.rejects(s.guard('edit'), state === 'RECOVERY_REQUIRED' ? /LONGRUN_RECOVERY_REQUIRED/ : /LONGRUN_RUN_STALLED/);
+    await s.guard('longrun', { action: 'status' }); await s.guard('read');
+    assert.deepEqual(fs.readFileSync(s.file), before);
+  }
+});

package/harness/test/v1212-maintenance-pause.test.mjs

@@ -0,0 +1,76 @@
+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 } from 'node:child_process';
+import * as C from '../src/controller.js';
+import { install, VERSION } from '../src/install.mjs';
+
+function fixture(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1212-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const project = path.join(root, 'project'), config = path.join(root, 'config'), state = path.join(root, 'state');
+  fs.mkdirSync(project); fs.writeFileSync(path.join(project, 'value.txt'), 'fixture');
+  install({ configDir: config });
+  const store = new C.Store(state), runId = 'maintenance-fixture', key = C.stateKey(C.projectIdentity(project), runId);
+  const run = { runId, directory: project, status: 'IMPLEMENTING', autoEnabled: false, controlGeneration: 4,
+    createdAt: Date.now(), budget: { iterations: 2, deadlineSeconds: 600 },
+    contract: { criteria: [], gates: [], lossTarget: 0 }, contractHash: 'retained-mapping',
+    state: { candidates: [] }, receipts: [], execution: { commandAttempts: 0, verificationMs: 0, inFlight: null },
+    agentProgress: { fields: { nextAction: 'preserve this plan' } } };
+  store.writeJSON(key, 'run.json', run);
+  const file = store._file(key, 'run.json');
+  const invoke = action => {
+    const result = spawnSync(process.execPath, [path.join(config, 'longrun-harness', 'releases', VERSION, 'bin', 'longrun.mjs'),
+      action, '--json', '--project', project, '--run', runId], {
+      cwd: root, env: { ...process.env, LONGRUN_TEST: '1', LONGRUN_STATE_DIR: state, OPENCODE_CONFIG_DIR: config },
+      encoding: 'utf8', timeout: 10000,
+    });
+    assert.equal(result.error, undefined);
+    return { exit: result.status, output: JSON.parse(result.stdout) };
+  };
+  return { run, store, key, file, invoke };
+}
+
+test('installed maintenance pause preserves terminal state instead of resurrecting it', t => {
+  const s = fixture(t);
+  for (const status of ['COMPLETE', 'CANCELLED']) {
+    s.store.writeJSON(s.key, 'run.json', { ...s.run, status });
+    const before = fs.readFileSync(s.file), result = s.invoke('pause');
+    assert.equal(result.exit, 2);
+    assert.equal(result.output.error, `RUN_${status}`);
+    assert.deepEqual(fs.readFileSync(s.file), before);
+  }
+});
+
+test('installed maintenance pause respects an active verifier writer lock', t => {
+  const s = fixture(t); assert.equal(s.store.tryLock(s.key, 'verifier'), true);
+  const before = fs.readFileSync(s.file), holder = s.store.whoHoldsLock(s.key);
+  try {
+    const result = s.invoke('pause');
+    assert.equal(result.exit, 2); assert.equal(result.output.error, 'STATE_BUSY');
+    assert.deepEqual(fs.readFileSync(s.file), before);
+    assert.deepEqual(s.store.whoHoldsLock(s.key), holder);
+  } finally { s.store.releaseLock(s.key); }
+});
+
+test('installed maintenance pause advances the control generation and preserves all evidence', t => {
+  const s = fixture(t), result = s.invoke('pause');
+  assert.equal(result.exit, 0); assert.equal(result.output.state, 'PAUSED');
+  const after = s.store.readJSON(s.key, 'run.json');
+  assert.equal(after.controlGeneration, 5);
+  assert.deepEqual(after, { ...s.run, status: 'PAUSED', autoEnabled: false, controlGeneration: 5 });
+});
+
+test('installed maintenance cannot call corrupt canonical state an absent run', t => {
+  const s = fixture(t);
+  for (const bytes of ['{broken', 'null', '[]']) {
+    fs.writeFileSync(s.file, bytes);
+    for (const action of ['status', 'pause']) {
+      const result = s.invoke(action);
+      assert.equal(result.exit, 2); assert.equal(result.output.error, 'STATE_CORRUPT');
+      assert.equal(fs.readFileSync(s.file, 'utf8'), bytes);
+    }
+  }
+});

package/harness/test/v1213-readout.test.mjs

@@ -0,0 +1,82 @@
+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';
+import { F } from './helper.mjs';
+
+async function setup() {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1213-'));
+  const project = path.join(base, 'project'), sd = path.join(base, 'state');
+  fs.mkdirSync(project); fs.writeFileSync(path.join(project, 'app.txt'), 'isolated readout');
+  process.env.LONGRUN_STATE_DIR = sd;
+  process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+  const run = JSON.parse(fs.readFileSync(new URL('./fixtures/presets-readout-run.json', import.meta.url)));
+  run.directory = project;
+  const store = new C.Store(sd), key = C.stateKey(C.projectIdentity(project), run.runId);
+  store.writeJSON(key, 'run.json', run);
+  fs.writeFileSync(path.join(sd, 'runs.json'), JSON.stringify({ offline: { runKey: key, directory: project, runId: run.runId } }));
+  const hooks = await F('../plugin/longrun.js', { client: null });
+  const ctx = { sessionID: 'offline', directory: project, worktree: project };
+  return { run, project, store, key, hooks, ctx, call: args => hooks.tool.longrun.execute({ runId: run.runId, ...args }, ctx) };
+}
+
+test('observed 13-receipt readout stays usable without hiding stale or failed evidence', async () => {
+  const s = await setup(), before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+  const full = C.deriveRunView(s.run, { currentFingerprint: C.sourceFingerprint(s.project) });
+  const raw = await s.call({ action: 'status' }), status = JSON.parse(raw);
+  assert.ok(Buffer.byteLength(raw) < 24000, `status was ${Buffer.byteLength(raw)} bytes`);
+  assert.ok(Math.max(...raw.split('\n').map(x => Buffer.byteLength(x))) < 8192);
+  for (const k of ['state', 'currentLoss', 'bestLoss', 'remaining', 'candidateCount', 'historicalReceiptCount', 'completionBlocked', 'hardGateBlockers']) assert.deepEqual(status[k], full[k]);
+  assert.deepEqual(status.checks.map(c => [c.checkId, c.effectiveStatus, c.selectedReceiptId, c.staleReason, c.historicalReceiptCount]),
+    full.checks.map(c => [c.checkId, c.effectiveStatus, c.selectedReceiptId, c.staleReason, c.historicalReceiptCount]));
+  assert.equal(status.receiptDetails.action, 'receipts');
+  assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+});
+
+test('receipt pages cover all genuine history once; individual retrieval retains actual failure output', async () => {
+  const s = await setup(), before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+  const seen = []; let offset = 0;
+  do {
+    const page = JSON.parse(await s.call({ action: 'receipts', offset, limit: 4 }));
+    assert.equal(page.ok, true); assert.equal(page.total, 13);
+    assert.ok(page.receipts.length <= 4);
+    seen.push(...page.receipts); offset = page.nextOffset;
+  } while (offset !== null);
+  assert.equal(seen.length, 13); assert.equal(new Set(seen.map(r => r.receiptId)).size, 13);
+  const failure = seen.find(r => r.historicalStatus === 'FAIL' && r.checkId === 'c-presets-e2e'); assert.ok(failure);
+  const detail = JSON.parse(await s.call({ action: 'receipts', receiptId: failure.receiptId }));
+  assert.equal(detail.receipt.exitCode, 1);
+  assert.equal(detail.receipt.outputTail, s.run.receipts[failure.order - 1].outputTail.slice(-6000));
+  assert.equal(detail.receipt.classification, 'SOURCE_FINGERPRINT_MISMATCH');
+  assert.equal(detail.receipt.historicalStatus, 'FAIL');
+  assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+});
+
+test('receipt selection and pagination fail clearly; detailed reads remain allowed while paused', async () => {
+  const s = await setup();
+  for (const args of [{ offset: -1 }, { limit: 0 }, { limit: 21 }, { offset: 0.5 }])
+    assert.equal(JSON.parse(await s.call({ action: 'receipts', ...args })).error, 'INVALID_RECEIPT_PAGE');
+  assert.equal(JSON.parse(await s.call({ action: 'receipts', receiptId: 'missing' })).error, 'RECEIPT_NOT_FOUND');
+  const page = JSON.parse(await s.call({ action: 'receipts', checkId: 'c-presets-server' }));
+  assert.equal(page.total, 2); assert.equal(page.receipts.length, 2);
+  const before = s.store.readJSON(s.key, 'run.json'); before.status = 'PAUSED'; s.store.writeJSON(s.key, 'run.json', before);
+  await s.hooks['tool.execute.before']({ tool: 'longrun', sessionID: s.ctx.sessionID }, { args: { action: 'receipts', runId: s.run.runId } });
+  assert.equal(JSON.parse(await s.call({ action: 'receipts' })).ok, true);
+  assert.equal(s.store.readJSON(s.key, 'run.json').status, 'PAUSED');
+});
+
+test('paging reaches history older than twenty receipts and never invents missing legacy fields', () => {
+  // Synthetic offline ledger exercises pagination, not application acceptance.
+  const run = { runId: 'offline-pages', sourceFingerprint: 'now', receipts: Array.from({ length: 47 }, (_, i) => ({
+    checkId: 'legacy', status: 'FAIL', finishedAt: i + 1, command: 'offline fixture', exitCode: 1,
+  })) };
+  const before = JSON.stringify(run), ids = [];
+  for (let offset = 0; offset < 47; offset += 20) ids.push(...C.receiptReadout(run, { offset, limit: 20 }).receipts.map(r => r.receiptId));
+  assert.equal(ids.length, 47); assert.equal(new Set(ids).size, 47);
+  const oldest = C.receiptReadout(run, { receiptId: ids[0] }).receipt;
+  assert.equal(oldest.classification, 'LEGACY_STALE_MISSING_FINGERPRINT');
+  assert.equal(oldest.receiptFingerprint, null); assert.equal(oldest.outputTail, null);
+  assert.equal(JSON.stringify(run), before);
+});