opencode-longrun-harness 1.2.22

package/harness/test/v1214-durable.test.mjs

@@ -0,0 +1,121 @@
+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 { spawn } from 'node:child_process';
+import * as C from '../src/controller.js';
+import { F } from './helper.mjs';
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+test('actual host death cleans the stubborn owned check and leaves genuine recoverable ERROR evidence', async () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1214-crash-')), dir = path.join(base, 'project');
+  fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'value.txt'), 'fixture');
+  const host = spawn(process.execPath, [path.join(import.meta.dirname, 'fixtures/durable-host.mjs'), base], { stdio: ['ignore', 'ignore', 'pipe'] });
+  let diagnostics = ''; host.stderr.on('data', d => diagnostics += d);
+  const exited = new Promise(resolve => host.once('exit', (code, signal) => resolve({ code, signal })));
+  let childPid;
+  try {
+    for (let i = 0; i < 500 && !fs.existsSync(path.join(base, 'child')); i++) await sleep(10);
+    assert.ok(fs.existsSync(path.join(base, 'child')), diagnostics);
+    childPid = Number(fs.readFileSync(path.join(base, 'child'), 'utf8'));
+    const runId = fs.readFileSync(path.join(base, 'run-id'), 'utf8');
+    process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+    process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+    const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), runId);
+    const reserved = store.readJSON(key, 'run.json');
+    assert.equal(reserved.execution.inFlight.ownerPid, host.pid);
+    assert.equal(reserved.execution.inFlight.childPid, childPid);
+    host.kill('SIGKILL'); // Only our directly spawned offline host, never OpenCode/MTPLX.
+    assert.equal((await exited).signal, 'SIGKILL');
+    const token = reserved.execution.inFlight.token;
+    let journal;
+    for (let i = 0; i < 400; i++) {
+      journal = store.readJSON(key, `execution-${token}.json`);
+      if (journal && !C.execution.ownedWorkAlive(childPid)) break;
+      await sleep(10);
+    }
+    assert.ok(journal, 'worker must persist real execution evidence after owner death');
+    assert.equal(C.execution.ownedWorkAlive(childPid), false);
+    assert.equal(journal.result.terminationReason, 'owner_lost');
+    assert.equal(journal.receipt.status, 'ERROR');
+    assert.equal(store.readJSON(key, 'run.json').receipts.length, 0, 'worker journals; explicit reconciliation owns ledger commit');
+    const hooks = await F('../plugin/longrun.js', { client: null, directory: dir, worktree: dir });
+    const ctx = { sessionID: 'fresh-recovery', directory: dir, worktree: dir };
+    const call = async action => JSON.parse(await hooks.tool.longrun.execute({ action, runId }, ctx));
+    assert.equal((await call('reconcile')).reconciled, true);
+    const after = store.readJSON(key, 'run.json');
+    assert.equal(after.receipts.length, 1); assert.equal(after.receipts[0].status, 'ERROR');
+    assert.equal(after.execution.commandAttempts, 1); assert.equal(after.execution.inFlight, null);
+    assert.equal(after.execution.verificationMs, journal.result.finishedAt - journal.result.startedAt);
+    assert.deepEqual(after.budget, reserved.budget); assert.deepEqual(after.contract, reserved.contract);
+    assert.equal(after.createdAt, reserved.createdAt); assert.equal(after.autoEnabled, false);
+    assert.equal((await call('reconcile')).nothingPending, true);
+    assert.equal(store.readJSON(key, 'run.json').receipts.length, 1);
+  } finally {
+    // Baseline failure must not strand the deliberately stubborn fixture.
+    if (childPid && C.execution.ownedWorkAlive(childPid)) { try { process.kill(-childPid, 'SIGKILL'); } catch {} }
+    if (host.exitCode === null && host.signalCode === null) host.kill('SIGKILL');
+    await exited;
+  }
+});
+
+test('host killed after actual completion preserves PASS and commits exactly once without rerunning', async () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1214-finished-')), dir = path.join(base, 'project');
+  fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'value.txt'), 'fixture');
+  const host = spawn(process.execPath, [path.join(import.meta.dirname, 'fixtures/durable-host.mjs'), base, 'complete'], { stdio: 'ignore' });
+  const exited = new Promise(resolve => host.once('exit', (code, signal) => resolve({ code, signal })));
+  try {
+    for (let i = 0; i < 500 && !fs.existsSync(path.join(base, 'run-id')); i++) await sleep(10);
+    const runId = fs.readFileSync(path.join(base, 'run-id'), 'utf8');
+    process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+    process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+    const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), runId);
+    let journal;
+    for (let i = 0; i < 500 && !journal; i++) {
+      const token = store.readJSON(key, 'run.json').execution.inFlight?.token;
+      if (token) journal = store.readJSON(key, `execution-${token}.json`);
+      if (!journal) await sleep(10);
+    }
+    assert.ok(journal); assert.equal(journal.receipt.status, 'PASS');
+    assert.equal(journal.result.status, 0); assert.match(journal.receipt.outputTail, /actual assertion passed/);
+    host.kill('SIGKILL'); assert.equal((await exited).signal, 'SIGKILL');
+    const hooks = await F('../plugin/longrun.js', { client: null, directory: dir, worktree: dir });
+    const ctx = { sessionID: 'after-crash', directory: dir, worktree: dir };
+    const reconcile = async () => JSON.parse(await hooks.tool.longrun.execute({ action: 'reconcile', runId }, ctx));
+    assert.equal((await reconcile()).reconciled, true);
+    const before = fs.readFileSync(store._file(key, 'run.json'));
+    assert.equal((await reconcile()).nothingPending, true);
+    assert.deepEqual(fs.readFileSync(store._file(key, 'run.json')), before);
+    const run = store.readJSON(key, 'run.json');
+    assert.equal(run.receipts.length, 1); assert.equal(run.execution.commandAttempts, 1);
+    assert.equal(run.execution.verificationMs, journal.result.finishedAt - journal.result.startedAt);
+    assert.equal(run.receipts[0].status, 'PASS');
+  } finally {
+    if (host.exitCode === null && host.signalCode === null) host.kill('SIGKILL');
+    await exited;
+  }
+});
+
+test('a live executor reservation cannot be bypassed before it records a child PID', async () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1214-reservation-')), dir = path.join(base, 'project');
+  fs.mkdirSync(dir);
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+  const hooks = await F('../plugin/longrun.js', { client: null, directory: dir, worktree: dir });
+  const ctx = { sessionID: 'reservation-test', directory: dir, worktree: dir };
+  const start = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Offline executor reservation fixture',
+    criteria: [{ id: 'c', checks: ['check'] }], checkCatalogue: { check: { command: [process.execPath, '-e', 'throw Error("must not launch")'] } } }, ctx));
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), start.runId);
+  const worker = spawn(process.execPath, ['-e', 'setTimeout(()=>{},10000)'], { stdio: 'ignore' });
+  const exited = new Promise(resolve => worker.once('exit', resolve));
+  try {
+    store.mutate(key, run => { run.execution.commandAttempts = 1;
+      run.execution.inFlight = { token: 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa', ownerPid: -1, executorPid: worker.pid, childPid: null,
+        checkId: 'check', mode: 'normal', startedAt: Date.now(), generation: 0 }; return { ok: true }; });
+    const before = fs.readFileSync(store._file(key, 'run.json'));
+    assert.equal(JSON.parse(await hooks.tool.longrun_verify.execute({ checkId: 'check', runId: start.runId }, ctx)).error, 'VERIFY_IN_FLIGHT');
+    assert.equal(JSON.parse(await hooks.tool.longrun.execute({ action: 'reconcile', runId: start.runId }, ctx)).error, 'VERIFY_IN_FLIGHT');
+    assert.deepEqual(fs.readFileSync(store._file(key, 'run.json')), before);
+  } finally { worker.kill('SIGTERM'); await exited; }
+});

package/harness/test/v1215-guidance.test.mjs

@@ -0,0 +1,57 @@
+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(), 'lr1215-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const dir = path.join(root, 'project'); fs.mkdirSync(dir);
+  process.env.LONGRUN_STATE_DIR = path.join(root, 'state');
+  const hooks = await F('../plugin/longrun.js', { client: null });
+  const ctx = { sessionID: 'guidance', directory: dir, worktree: dir };
+  const call = async args => hooks.tool.longrun.execute(args, ctx);
+  const start = JSON.parse(await call({ action: 'start', request: 'Error guidance fixture', criteria: [{ id: 'assertion', checks: ['check'] }], checkCatalogue: { check: { command: ['node', '-e', 'process.exit(0)'] } } }));
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), start.runId);
+  return { call, store, key };
+}
+
+test('actual rejected checkpoint shapes include usable correction and observed lifecycle without mutation', async t => {
+  const s = await setup(t);
+  for (const progress of ['recovered and paused', JSON.stringify({ summary: 'done', status: 'PAUSED' }), { nextAction: 'x'.repeat(1001) }]) {
+    const before = s.store.readJSON(s.key, 'run.json');
+    const result = JSON.parse(await s.call({ action: 'checkpoint', progress }));
+    assert.equal(result.error, 'INVALID_PROGRESS');
+    assert.equal(result.state, 'IMPLEMENTING');
+    assert.equal(result.continuation, false);
+    assert.equal(result.runId, before.runId);
+    assert.equal(result.unchanged, true);
+    assert.deepEqual(Object.keys(result.progressSchema.fields), ['currentSlice', 'nextAction', 'decisions', 'failedHypotheses', 'memoryNodes', 'artifacts']);
+    assert.equal(result.progressSchema.fields.nextAction.maxLength, 1000);
+    assert.equal(result.progressSchema.maxCombinedCharacters, 6000);
+    assert.match(result.lifecycleGuidance, /OFF.*does not.*PAUSED/);
+    assert.deepEqual(s.store.readJSON(s.key, 'run.json'), before);
+    const copy = structuredClone(before);
+    assert.equal(C.saveAgentProgress(copy, result.progressSchema.example).ok, true);
+    assert.equal(copy.status, before.status);
+  }
+  await s.call({ action: 'pause' });
+  const paused = JSON.parse(await s.call({ action: 'checkpoint', progress: { status: 'IMPLEMENTING' } }));
+  assert.equal(paused.state, 'PAUSED');
+  assert.equal(s.store.readJSON(s.key, 'run.json').status, 'PAUSED');
+});
+
+test('help points to actual paginated receipts and identifies attempt cap scope', async t => {
+  const s = await setup(t), help = JSON.parse(await s.call({ action: 'help' }));
+  assert.match(help.receiptInspection, /receipts/);
+  assert.match(help.receiptInspection, /receiptId/);
+  assert.match(help.executionLimits, /toolActionCap.*declared.check attempts/);
+  assert.match(help.lifecycleGuidance, /OFF.*does not.*PAUSED/);
+  const state = JSON.parse(await s.call({ action: 'status' }));
+  assert.equal(state.state, 'IMPLEMENTING');
+  assert.match(state.lifecycleGuidance, /OFF.*does not.*PAUSED/);
+});

package/harness/test/v1216-test-summary.test.mjs

@@ -0,0 +1,39 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import * as C from '../src/controller.js';
+
+test('recorded failing Vitest summary is readable without replacing historical acceptance evidence', () => {
+  const observed = JSON.parse(fs.readFileSync(new URL('./fixtures/vitest-failed-receipt.json', import.meta.url)));
+  const r = observed.receipt;
+  const run = { runId: observed.runId, contractHash: r.contractHash, receipts: [r] };
+  const before = JSON.stringify(run);
+  const detailed = C.receiptReadout(run, { receiptId: C.receiptReadout(run).receipts[0].receiptId }).receipt;
+  assert.equal(detailed.historicalStatus, 'FAIL');
+  assert.equal(detailed.testCount, 0);
+  assert.deepEqual(detailed.reportedTests, {
+    source: 'recorded_output_tail', runner: 'vitest', total: 15, passed: 14, failed: 1,
+    skipped: null, todo: null, summary: 'Tests  1 failed | 14 passed (15)',
+  });
+  assert.match(detailed.testCountMeaning, /zero.*not.*zero discovered/i);
+  assert.equal(JSON.stringify(run), before);
+  assert.equal(C.effectiveStatus(run, r.checkId, r.sourceFingerprint), 'FAIL');
+});
+
+test('summary diagnostics decline ambiguous or incomplete output and never change acceptance', () => {
+  const report = outputTail => C.receiptReadout({ receipts: [{ checkId: 'c', status: 'NOT_RUN', testCount: 0, outputTail }] }).receipts[0];
+  for (const text of [undefined, '', 'Test Files  1 failed (1)', 'Error: Tests  1 failed (1)',
+    'Tests  1 failed | 14 passed (16)', 'Tests  1 failed (1)\nTests  2 passed (2)',
+    'Tests  1 failed | 14 unknown (15)', 'Tests  1 failed | 1 failed (2)']) {
+    assert.equal(report(text).reportedTests, null);
+  }
+  const ansi = report('\u001b[31m      Tests  2 passed | 1 skipped (3)\u001b[0m');
+  assert.equal(ansi.reportedTests.total, 3);
+  assert.equal(ansi.reportedTests.passed, 2);
+  assert.equal(ansi.reportedTests.failed, null);
+  assert.equal(ansi.reportedTests.skipped, 1);
+  assert.equal(ansi.historicalStatus, 'NOT_RUN');
+  assert.equal(report('Tests  0 passed (0)').reportedTests.total, 0);
+  assert.equal(C.parseTestCounts('Tests  1 failed | 14 passed (15)'), 0);
+  assert.equal(C.makeReceipt({ exitCode: 0, testCount: 0, requirementKind: 'test' }).status, 'NOT_RUN');
+});

package/harness/test/v1217-discovery.test.mjs

@@ -0,0 +1,73 @@
+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';
+
+const observed = JSON.parse(fs.readFileSync(new URL('./fixtures/notes-recovery-run.json', import.meta.url)));
+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(), 'lr1217-'));
+  t.after(() => fs.rmSync(base, { recursive: true, force: true }));
+  const dir = path.join(base, 'project'); fs.mkdirSync(dir);
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  const ctx = { sessionID: 'recovery', directory: dir, worktree: dir };
+  const hooks = await F('../plugin/longrun.js', ctx), store = new C.Store(process.env.LONGRUN_STATE_DIR);
+  // Actual failed-recovery record; only the fixture's project identity is relocated.
+  const run = structuredClone(observed); run.directory = dir;
+  const add = value => {
+    const key = C.stateKey(C.projectIdentity(value.directory), value.runId);
+    store.writeJSON(key, 'run.json', value); return key;
+  };
+  const key = add(run), bytes = () => fs.readFileSync(store._file(key, 'run.json'));
+  return { hooks, ctx, run, add, bytes, dir, base };
+}
+
+test('copied native wrong-ID reads expose exact canonical recovery identity without changing the run', async t => {
+  const s = await setup(t), before = s.bytes();
+  for (const action of ['status', 'receipts', 'resume-context', 'resume', 'pause', 'cancel', 'complete']) {
+    const out = JSON.parse(await s.hooks.tool.longrun.execute({ action, runId: 'lr-20260920T195102Z' }, s.ctx));
+    assert.equal(out.state, 'NO_RUN'); assert.equal(out.runId, 'lr-20260920T195102Z');
+    assert.deepEqual(out.discovery.suggestedRead, { action: 'resume-context', runId: observed.runId });
+    assert.deepEqual(out.discovery.availableRuns, [{ runId: observed.runId, state: 'RECOVERY_REQUIRED' }]);
+    assert.match(out.discovery.detail, /never.*replacement/i);
+    assert.deepEqual(s.bytes(), before, action);
+  }
+  assert.equal(s.run.receipts.length, 6); assert.equal(s.run.state.candidates.length, 5);
+});
+
+test('wrong-ID verification remains NO_RUN and only offers project-local discovery', async t => {
+  const s = await setup(t), before = s.bytes();
+  const foreign = path.join(s.base, 'foreign'); fs.mkdirSync(foreign);
+  s.add({ ...s.run, runId: 'lr-foreign-private', directory: foreign });
+  const out = JSON.parse(await s.hooks.tool.longrun_verify.execute({ runId: 'lr-foreign-private', checkId: 'c-notes-server' }, s.ctx));
+  assert.equal(out.error, 'NO_RUN'); assert.equal(out.ok, false);
+  assert.deepEqual(out.discovery.availableRuns, [{ runId: observed.runId, state: 'RECOVERY_REQUIRED' }]);
+  assert.deepEqual(out.discovery.suggestedRead, { action: 'resume-context', runId: observed.runId });
+  assert.deepEqual(s.bytes(), before);
+});
+
+test('ambiguous recovery discovery is bounded and never recommends an arbitrary run', async t => {
+  const s = await setup(t), before = s.bytes();
+  for (let i = 0; i < 8; i++) s.add({ ...s.run, runId: `lr-extra-${i}` });
+  const out = JSON.parse(await s.hooks.tool.longrun.execute({ action: 'status', runId: 'wrong' }, s.ctx));
+  assert.equal(out.discovery.totalRuns, 9); assert.equal(out.discovery.truncated, true);
+  assert.equal(out.discovery.availableRuns.length, 5); assert.equal(out.discovery.suggestedRead, null);
+  assert.match(out.discovery.detail, /multiple/i); assert.ok(JSON.stringify(out).length < 2200);
+  assert.deepEqual(s.bytes(), before);
+});
+
+test('terminal-only and empty discovery do not invent resumable work', async t => {
+  const s = await setup(t);
+  s.add({ ...s.run, status: 'COMPLETE' });
+  let out = JSON.parse(await s.hooks.tool.longrun.execute({ action: 'status', runId: 'wrong' }, s.ctx));
+  assert.deepEqual(out.discovery.suggestedRead, { action: 'status', runId: s.run.runId });
+  assert.match(out.discovery.detail, /terminal/i);
+  const empty = path.join(s.base, 'empty'); fs.mkdirSync(empty);
+  out = JSON.parse(await s.hooks.tool.longrun.execute({ action: 'status', runId: 'wrong' }, { ...s.ctx, directory: empty, worktree: empty }));
+  assert.equal(out.discovery.totalRuns, 0); assert.equal(out.discovery.suggestedRead, null);
+  assert.deepEqual(out.discovery.availableRuns, []);
+});

package/harness/test/v1218-completion-review.test.mjs

@@ -0,0 +1,203 @@
+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');
+
+// Actual recorded, prematurely completed annotations trial. Read-only copied evidence;
+// its real receipts are not fabricated, modified or written into a live store.
+const actual = () => JSON.parse(fs.readFileSync(new URL('./fixtures/notes-premature-complete-run.json', import.meta.url)));
+
+test('actual all-green annotations record distinguishes check success from missing independent completion review', () => {
+  const run = actual(), before = JSON.stringify(run);
+  const view = C.deriveRunView(run, { currentFingerprint: run.sourceFingerprint });
+  assert.equal(view.currentLoss, 0, 'retain the genuine declared-check calculation');
+  assert.ok(view.checks.every(c => c.effectiveStatus === 'PASS'));
+  assert.equal(view.completionBlocked, true, 'unreviewed checks cannot authorize completion');
+  assert.equal(view.blockReason, 'completion_review_required');
+  assert.equal(JSON.stringify(run), before, 'readouts preserve the recorded premature COMPLETE and all evidence');
+});
+
+test('offline plugin tool factory refuses premature completion after real passing command without changing lifecycle or evidence', async () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1218-review-'));
+  const dir = path.join(base, 'project'); fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'app.txt'), 'fixture');
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  const hooks = await F('../plugin/longrun.js', { client: null });
+  const ctx = { sessionID: 'offline-review', directory: dir, worktree: dir };
+  const start = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Complete a reviewed feature; PAUSE for independent review, do not COMPLETE from checks alone.', criteria: [{ id: 'c', checks: ['check'] }], checkCatalogue: { check: { command: [process.execPath, '-e', "require('node:assert/strict').equal(2+2,4)"], kind: 'cmd' } } }, ctx));
+  assert.ok(start.runId);
+  const pass = JSON.parse(await hooks.tool.longrun_verify.execute({ runId: start.runId, checkId: 'check' }, ctx));
+  assert.equal(pass.status, 'PASS');
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), start.runId);
+  const before = store.readJSON(key, 'run.json');
+  const completed = JSON.parse(await hooks.tool.longrun.execute({ action: 'complete', runId: start.runId }, ctx));
+  assert.equal(completed.complete, false);
+  assert.equal(completed.blockReason, 'completion_review_required');
+  assert.deepEqual(store.readJSON(key, 'run.json'), before);
+});
+
+async function fixture(t) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1218-operator-'));
+  t.after(() => fs.rmSync(base, { recursive: true, force: true }));
+  const dir = path.join(base, 'project'); fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'app.txt'), 'valid');
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  const hooks = await F('../plugin/longrun.js', { client: null });
+  const ctx = { sessionID: 'review-fixture', directory: dir, worktree: dir };
+  const start = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Independent completion review fixture', criteria: [{ id: 'c', checks: ['check'] }], checkCatalogue: { check: { command: [process.execPath, '-e', "require('node:assert/strict').equal(require('node:fs').readFileSync('app.txt','utf8'),'valid')"], kind: 'cmd' } } }, ctx));
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), start.runId);
+  const read = () => store.readJSON(key, 'run.json');
+  const call = async (action, extra = {}) => {
+    const value = await hooks.tool.longrun.execute({ action, runId: start.runId, ...extra }, ctx);
+    try { return JSON.parse(value); } catch { return value; }
+  };
+  const verify = async () => JSON.parse(await hooks.tool.longrun_verify.execute({ runId: start.runId, checkId: 'check' }, ctx));
+  assert.equal((await verify()).status, 'PASS');
+  await call('pause');
+  const args = (verdict = 'accept', reviewId = 'operator-review-1') => ({ directory: dir, runId: start.runId, verdict, reviewId,
+    reason: 'Independent offline fixture review', expectedBasis: C.completionReviewBasis(read(), C.sourceFingerprint(dir)) });
+  return { base, dir, store, key, read, call, verify, args, hooks, ctx, start };
+}
+
+test('real checks plus paused operator approval permit completion; a model payload does not', async t => {
+  const s = await fixture(t), before = s.read();
+  assert.equal((await s.call('complete', { completionReview: { verdict: 'accept' } })).complete, false);
+  assert.equal((await s.call('checkpoint', { progress: { completionReview: 'accepted' } })).error, 'INVALID_PROGRESS');
+  assert.deepEqual(s.read(), before);
+  const args = s.args();
+  assert.equal((await C.operatorCompletionReview(s.store, s.key, args)).ok, true);
+  assert.equal((await C.operatorCompletionReview(s.store, s.key, args)).alreadyRecorded, true);
+  assert.equal(s.read().completionReviews.length, 1);
+  assert.equal((await s.call('complete')).complete, true);
+  assert.equal(s.read().status, 'COMPLETE');
+});
+
+test('approval binds source, request, contract, catalogue, budgets and genuine evidence', async t => {
+  const s = await fixture(t);
+  await C.operatorCompletionReview(s.store, s.key, s.args());
+  const run = s.read(), fp = C.sourceFingerprint(s.dir);
+  assert.equal(C.canComplete(run, { currentFingerprint: fp }).complete, true);
+  for (const mutate of [r => r.originalRequest += ' changed', r => r.contract.extra = true,
+    r => r.checkCatalogue.check.timeoutMs = 99, r => r.budget.iterations++, r => r.createdAt--,
+    r => r.receipts.push({ ...r.receipts[0], finishedAt: Date.now() }), r => r.evidence = [{ kind: 'negative_control', ok: false }]]) {
+    const clone = structuredClone(run); mutate(clone);
+    assert.equal(C.completionReviewStatus(clone, fp).status, 'STALE');
+    assert.equal(C.canComplete(clone, { currentFingerprint: fp }).complete, false);
+  }
+  fs.writeFileSync(path.join(s.dir, 'app.txt'), 'changed');
+  assert.equal(C.completionReviewStatus(run, C.sourceFingerprint(s.dir)).status, 'STALE');
+  fs.writeFileSync(path.join(s.dir, 'app.txt'), 'valid');
+  await s.call('resume'); await s.verify();
+  assert.equal((await s.call('complete')).blockReason, 'completion_review_stale');
+});
+
+test('completion recomputes source under the writer lock instead of trusting its initial view', async t => {
+  const s = await fixture(t); await C.operatorCompletionReview(s.store, s.key, s.args());
+  const original = C.Store.prototype.mutate; let changed = false;
+  C.Store.prototype.mutate = function(key, callback) {
+    if (key === s.key && !changed) { changed = true; fs.writeFileSync(path.join(s.dir, 'app.txt'), 'changed'); }
+    return original.call(this, key, callback);
+  };
+  try { assert.equal((await s.call('complete')).error, 'EVIDENCE_CHANGED'); }
+  finally { C.Store.prototype.mutate = original; }
+  assert.equal(s.read().status, 'PAUSED');
+});
+
+test('rejecting copied premature COMPLETE archives every field and preserves exhausted budgets', async t => {
+  const s = await fixture(t), run = actual();
+  run.directory = s.dir; run.runId = s.start.runId;
+  run.createdAt = Date.now() - run.budget.deadlineSeconds * 1000 - 1000;
+  run.budget.iterations = C.candidateCount(run);
+  s.store.writeJSON(s.key, 'run.json', run);
+  const before = s.read(), args = s.args('reject');
+  const result = await C.operatorCompletionReview(s.store, s.key, args);
+  assert.equal(result.ok, true); assert.equal(result.state, 'PAUSED');
+  assert.deepEqual(JSON.parse(fs.readFileSync(result.archivedSnapshot)), before);
+  const after = s.read();
+  for (const key of Object.keys(before).filter(k => !['status', 'autoEnabled', 'controlGeneration', 'completionReviews'].includes(k)))
+    assert.deepEqual(after[key], before[key], key);
+  assert.equal(after.autoEnabled, false); assert.equal(after.controlGeneration, before.controlGeneration + 1);
+  assert.equal(after.completionReviews[0].previousState, 'COMPLETE');
+  const resumed = await s.call('resume'); assert.equal(resumed.error, 'BUDGET_EXHAUSTED'); assert.equal(resumed.spent.deadline, true);
+  assert.equal(s.read().receipts.length, 26);
+});
+
+test('archive conflict, cancellation, in-flight work, stale basis and unready checks fail closed', async t => {
+  const s = await fixture(t);
+  const check = async (mutate, expected, verdict = 'accept', adjust = x => x) => {
+    const original = s.read(); const run = structuredClone(original); mutate(run); s.store.writeJSON(s.key, 'run.json', run);
+    const args = adjust(s.args(verdict)); const before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+    assert.equal((await C.operatorCompletionReview(s.store, s.key, args)).error, expected);
+    assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+    s.store.writeJSON(s.key, 'run.json', original);
+  };
+  await check(r => r.status = 'CANCELLED', 'RUN_CANCELLED', 'reject');
+  await check(r => r.execution.inFlight = { token: 'live' }, 'VERIFY_IN_FLIGHT');
+  await check(r => r.receipts = [], 'REVIEW_CHECKS_NOT_READY');
+  await check(r => r.status = 'IMPLEMENTING', 'REVIEW_REQUIRES_PAUSE');
+  await check(() => {}, 'REVIEW_BASIS_CHANGED', 'accept', a => ({ ...a, expectedBasis: '0'.repeat(64) }));
+  await check(() => {}, 'INVALID_COMPLETION_REVIEW', 'accept', a => ({ ...a, reviewId: '../outside' }));
+  const archive = s.store._file(s.key, 'completion-review-operator-review-1.json'); fs.writeFileSync(archive, 'do not overwrite');
+  await check(r => r.status = 'COMPLETE', 'REVIEW_ARCHIVE_FAILED', 'reject');
+  assert.equal(fs.readFileSync(archive, 'utf8'), 'do not overwrite');
+});
+
+test('operator review uses the existing writer lock and cannot reopen beside a newer task', async t => {
+  const s = await fixture(t), before = s.read();
+  assert.equal(s.store.tryLock(s.key, 'held'), true);
+  try { assert.equal((await C.operatorCompletionReview(s.store, s.key, s.args())).error, 'STATE_BUSY'); }
+  finally { s.store.releaseLock(s.key); }
+  assert.deepEqual(s.read(), before);
+  const run = s.read(); run.status = 'COMPLETE'; s.store.writeJSON(s.key, 'run.json', run);
+  const other = structuredClone(run); other.runId = 'another-active-run'; other.status = 'IMPLEMENTING';
+  s.store.writeJSON(C.stateKey(C.projectIdentity(s.dir), other.runId), 'run.json', other);
+  assert.equal((await C.operatorCompletionReview(s.store, s.key, s.args('reject'))).error, 'EXISTING_RUN');
+  assert.deepEqual(s.read(), run);
+});
+
+test('failed canonical write preserves the archive but grants no review or lifecycle change', async t => {
+  const s = await fixture(t), run = s.read(); run.status = 'COMPLETE'; s.store.writeJSON(s.key, 'run.json', run);
+  const args = s.args('reject'), before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+  const write = s.store.writeJSON.bind(s.store);
+  s.store.writeJSON = (key, name, value) => { if (name === 'run.json') throw new Error('injected write failure'); return write(key, name, value); };
+  await assert.rejects(C.operatorCompletionReview(s.store, s.key, args), /injected write failure/);
+  assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+  const archive = s.store._file(s.key, 'completion-review-operator-review-1.json');
+  assert.deepEqual(fs.readFileSync(archive), before);
+  s.store.writeJSON = write;
+  assert.equal((await C.operatorCompletionReview(s.store, s.key, args)).ok, true);
+  assert.deepEqual(fs.readFileSync(archive), before, 'retry never overwrites a different historical snapshot');
+});
+
+test('concurrent native new-task admission and operator rejection share one project slot', async t => {
+  const s = await fixture(t), run = s.read(); run.status = 'COMPLETE'; s.store.writeJSON(s.key, 'run.json', run);
+  const args = s.args('reject');
+  const [review, started] = await Promise.all([
+    C.operatorCompletionReview(s.store, s.key, args),
+    s.hooks.tool.longrun.execute({ action: 'start', request: 'different task', criteria: [{ id: 'c', checks: ['check'] }], checkCatalogue: run.checkCatalogue }, { ...s.ctx, sessionID: 'different-task' }).then(JSON.parse),
+  ]);
+  const runs = fs.readdirSync(path.join(s.store.dir, 'state')).filter(x => /^[a-f0-9]{32}$/.test(x)).map(key => s.store.readRun(key).run);
+  assert.equal(runs.filter(r => !C.RUN_TERMINAL_STATES.includes(r.status)).length, 1);
+  assert.ok(review.ok ? started.error === 'EXISTING_RUN' : review.error === 'EXISTING_RUN' && started.runId);
+});
+
+test('reviewed completion can be explicitly rejected and resumed with original identity and limits', async t => {
+  const s = await fixture(t);
+  await C.operatorCompletionReview(s.store, s.key, s.args());
+  assert.equal((await s.call('complete')).complete, true);
+  const before = s.read();
+  assert.equal((await s.call('resume')).error, 'RUN_COMPLETE');
+  const rejected = await C.operatorCompletionReview(s.store, s.key, { ...s.args('reject', 'operator-review-2'), reason: 'Independent review discovered an unmet requirement.' });
+  assert.equal(rejected.ok, true); assert.deepEqual(JSON.parse(fs.readFileSync(rejected.archivedSnapshot)), before);
+  assert.equal((await s.call('complete')).blockReason, 'completion_review_rejected');
+  assert.equal((await s.call('resume')).resumed, true);
+  assert.equal((await s.verify()).status, 'PASS');
+  const after = s.read();
+  for (const key of ['runId','originalRequest','contract','contractHash','budget','createdAt']) assert.deepEqual(after[key], before[key]);
+  assert.equal(after.receipts.length, before.receipts.length + 1);
+  assert.deepEqual(after.receipts.slice(0, -1), before.receipts);
+  assert.equal(after.completionReviews.length, 2); assert.equal(after.autoEnabled, false);
+  assert.equal((await s.call('complete')).complete, false);
+});

package/harness/test/v1219-budget-pause.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 fixture(t, budget = {}) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr1219-'));
+  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'), 'baseline');
+  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: 'budget-fixture', directory: dir, worktree: dir };
+  const command = [process.execPath, '-e', "require('node:assert/strict').match(require('node:fs').readFileSync('value.txt','utf8'),/^valid/)"];
+  const start = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Isolated budget-refusal stopping regression', criteria: [{ id: 'c', checks: ['check'] }], checkCatalogue: { check: { command, kind: 'cmd', gate: true } }, ...budget }, ctx));
+  assert.ok(start.runId);
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), start.runId);
+  const read = () => store.readJSON(key, 'run.json');
+  const verify = async (args = {}) => JSON.parse(await hooks.tool.longrun_verify.execute({ runId: start.runId, checkId: 'check', ...args }, ctx));
+  return { base, dir, hooks, ctx, start, store, key, read, verify };
+}
+function preservedPause(before, after) {
+  assert.equal(after.status, 'PAUSED'); assert.equal(after.autoEnabled, false);
+  assert.equal(after.controlGeneration, (before.controlGeneration || 0) + 1);
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (!['status', 'autoEnabled', 'controlGeneration'].includes(key)) assert.deepEqual(after[key], before[key], key);
+  }
+}
+
+test('actual copied annotations refusal pauses without rewriting 24 candidates, 37 receipts or missing evidence', async t => {
+  const s = await fixture(t);
+  const run = JSON.parse(fs.readFileSync(new URL('./fixtures/notes-budget-exhausted-run.json', import.meta.url)));
+  assert.equal(run.status, 'IMPLEMENTING'); assert.equal(C.candidateCount(run), 24); assert.equal(run.receipts.length, 37);
+  // Relocation only: genuine catalogue and evidence remain historical. Budget
+  // refusal prevents these application commands from running in this tiny copy.
+  run.directory = s.dir; run.runId = s.start.runId;
+  s.store.writeJSON(s.key, 'run.json', run);
+  // A fresh factory discovers canonical catalogue instead of fixture routing.
+  fs.writeFileSync(path.join(s.store.dir, 'runs.json'), '{}');
+  const hooks = await F('../plugin/longrun.js', { client: null, directory: s.dir, worktree: s.dir });
+  const result = JSON.parse(await hooks.tool.longrun_verify.execute({ runId: run.runId, checkId: Object.keys(run.checkCatalogue)[0] }, { ...s.ctx, sessionID: 'fresh-copy' }));
+  assert.equal(result.error, 'BUDGET_EXHAUSTED'); assert.equal(result.spent.candidates, true);
+  assert.equal(result.state, 'PAUSED'); assert.equal(result.cancelledContinuations, true);
+  preservedPause(run, s.read());
+});
+
+test('last counted candidate can finish checks; new source refusal stops edits across stale routing and fresh hosts', async t => {
+  const s = await fixture(t, { candidateBudget: 1 });
+  fs.writeFileSync(path.join(s.dir, 'value.txt'), 'valid-one');
+  assert.equal((await s.verify()).status, 'PASS');
+  assert.equal((await s.verify()).status, 'PASS');
+  assert.equal(s.read().status, 'IMPLEMENTING'); assert.equal(C.candidateCount(s.read()), 1);
+  fs.writeFileSync(path.join(s.dir, 'value.txt'), 'valid-two');
+  const before = s.read();
+  assert.equal((await s.verify()).error, 'BUDGET_EXHAUSTED');
+  preservedPause(before, s.read());
+  const frozen = fs.readFileSync(s.store._file(s.key, 'run.json'));
+  assert.equal((await s.verify()).error, 'RUN_PAUSED');
+  assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), frozen);
+  const fresh = await F('../plugin/longrun.js', { client: null, directory: s.dir, worktree: s.dir });
+  for (const [hooks, sessionID] of [[s.hooks, s.ctx.sessionID], [fresh, 'fresh-unbound']]) {
+    for (const tool of ['edit', 'bash', 'task']) await assert.rejects(hooks['tool.execute.before']({ tool, sessionID }, { args: {} }), /LONGRUN_RUN_PAUSED/);
+    await hooks['tool.execute.before']({ tool: 'longrun', sessionID }, { args: { action: 'status' } });
+  }
+});
+
+test('deadline, attempt and active-time refusals pause normal and negative checks without spending anything', async t => {
+  for (const reason of ['deadline', 'toolActions', 'activeSeconds']) {
+    const s = await fixture(t), run = s.read();
+    if (reason === 'deadline') run.createdAt -= run.budget.deadlineSeconds * 1000 + 1000;
+    if (reason === 'toolActions') run.budget.toolActionCap = run.execution.commandAttempts;
+    if (reason === 'activeSeconds') run.budget.activeSeconds = 0;
+    s.store.writeJSON(s.key, 'run.json', run);
+    const dir = path.join(s.base, 'negative'); fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'value.txt'), 'invalid');
+    const result = await s.verify(reason === 'deadline' ? { mode: 'negative', fixture: dir } : {});
+    assert.equal(result.error, 'BUDGET_EXHAUSTED'); assert.equal(result.spent[reason], true);
+    preservedPause(run, s.read());
+  }
+});
+
+test('terminal, paused and live or orphaned reservations take precedence over exhaustion', async t => {
+  for (const [status, inFlight, expected] of [
+    ['PAUSED', null, 'RUN_PAUSED'], ['COMPLETE', null, 'RUN_COMPLETE'], ['CANCELLED', null, 'RUN_CANCELLED'],
+    ['IMPLEMENTING', { ownerPid: process.pid }, 'VERIFY_IN_FLIGHT'],
+    ['IMPLEMENTING', { ownerPid: -1, childPid: null }, 'EXECUTION_RECOVERY_REQUIRED'],
+  ]) {
+    const s = await fixture(t), run = s.read();
+    run.status = status; run.budget.activeSeconds = 0; run.execution.inFlight = inFlight;
+    s.store.writeJSON(s.key, 'run.json', run);
+    const before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+    assert.equal((await s.verify()).error, expected);
+    assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+  }
+});
+
+test('refusal uses writer lock and never reports a pause if canonical write fails', async t => {
+  const s = await fixture(t), run = s.read(); run.budget.activeSeconds = 0; s.store.writeJSON(s.key, 'run.json', run);
+  const before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+  s.store.tryLock(s.key, 'concurrent-writer');
+  try { assert.equal((await s.verify()).error, 'STATE_BUSY'); }
+  finally { s.store.releaseLock(s.key); }
+  const write = C.Store.prototype.writeJSON;
+  C.Store.prototype.writeJSON = function(key, name, value) {
+    if (key === s.key && name === 'run.json') throw new Error('injected canonical write failure');
+    return write.call(this, key, name, value);
+  };
+  try { await assert.rejects(s.verify(), /injected canonical write failure/); }
+  finally { C.Store.prototype.writeJSON = write; }
+  assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+  assert.equal(s.store.whoHoldsLock(s.key), null);
+  assert.equal((await s.verify()).state, 'PAUSED');
+});
+
+test('a concurrent cancellation wins; competing budget refusals increment pause generation only once', async t => {
+  const s = await fixture(t), initial = s.read(); initial.budget.activeSeconds = 0; s.store.writeJSON(s.key, 'run.json', initial);
+  const mutate = C.Store.prototype.mutate; let intercepted = false;
+  C.Store.prototype.mutate = function(key, callback) {
+    if (key === s.key && !intercepted) {
+      intercepted = true;
+      mutate.call(this, key, run => { run.status = 'CANCELLED'; return { ok: true }; });
+    }
+    return mutate.call(this, key, callback);
+  };
+  try { assert.equal((await s.verify()).error, 'RUN_CANCELLED'); }
+  finally { C.Store.prototype.mutate = mutate; }
+  assert.deepEqual(s.read(), { ...initial, status: 'CANCELLED' });
+  s.store.writeJSON(s.key, 'run.json', initial);
+  const results = await Promise.all([s.verify(), s.verify()]);
+  assert.deepEqual(results.map(r => r.error).sort(), ['BUDGET_EXHAUSTED', 'RUN_PAUSED']);
+  preservedPause(initial, s.read());
+});