Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

10.8 KB
Raw Blame
/** Refusals give concrete recovery steps that work in real checkouts [P4,I1,I2]. */
import assert from 'node:assert/strict';
import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { after, test } from 'node:test';
import { Refused } from '../src/refused.js';
import { recordedRefusal, refusalFromReceipt, RECORDED_GENERIC_NEXT } from '../src/recorded-refusal.js';
import { refusalDocument } from '../src/json.js';
import { commandOutput as lightCommandOutput } from '../src/json-output.js';
import { createE2eHelpers } from './e2e-helpers.js';

const e2e = createE2eHelpers();
after(e2e.cleanup);

/** Keep both command streams in an assertion so a refusal is never hidden by fixture diagnostics. */
function succeeded(result) {
  assert.equal(result.code, 0, `${result.out}\n${result.err}`);
  return result;
}

/** File a real build with a frozen check that fails only when the fixture arms its gate. */
function addBuild(box, repo, title, check) {
  const result = succeeded(box.run(repo, 'add', 'web', title, '--specs', 'G1',
    '--criterion', 'the real fixture gate passes', '--check', check, '--json'));
  return JSON.parse(result.out).item.item_id;
}

test('every refusal names a next step that works [P4,I1,I2]', async () => {
  const sourceRoot = resolve(import.meta.dirname, '../src');
  const codes = new Set(['API_LISTEN', 'CORE_BARE', 'VIEW_SIGN_IN_STOPPED']);
  for (const file of readdirSync(sourceRoot).filter(name => name.endsWith('.js'))) {
    const source = readFileSync(join(sourceRoot, file), 'utf8');
    for (const match of source.matchAll(/new Refused\(\s*['"]([A-Z][A-Z0-9_]*)['"]/gu)) codes.add(match[1]);
  }
  for (const code of codes) {
    const { next } = refusalDocument(new Refused(code, 'This operation was refused.')).error;
    assert.ok(next.trim(), `${code} supplies a recovery action`);
    assert.doesNotMatch(next, /Run pullboard help, correct the reported problem/u, `${code} has its own recovery`);
  }
  const { NEXT_STEPS } = await import('../src/next-steps.js');
  for (const code of codes) assert.ok(Object.hasOwn(NEXT_STEPS, code), `${code} has an explicit recovery entry`);
  assert.equal(refusalDocument({ code: 'FUTURE_REMOTE_RULE', message: 'The service refused.', next: 'ask the service owner to restore this board' }).error.next,
    'ask the service owner to restore this board', 'remote recovery guidance survives serialization');
  assert.match(refusalDocument(new Refused('FUTURE_REMOTE_RULE', 'The service refused.')).error.next, /service owner.*FUTURE_REMOTE_RULE/u,
    'an unknown remote rule names its owner and code rather than inventing a command');
  assert.equal(refusalDocument(new Refused('REMOTE_COORDINATOR_MODEL',
    "the coordinator's model is declared on its own checkout; run pullboard join coordinator there")).error.next,
  'run pullboard join coordinator there', 'a coordinator description does not hide the later recovery action');
  assert.equal(refusalDocument(new Refused('PENDING_REFREEZE',
    'item #12 has a pending correction.\nnext: pullboard refreeze 12')).error.next,
  'pullboard refreeze 12', 'an existing specific next line survives serialization');
  assert.equal(refusalDocument(new Refused('GATE_RED',
    'the submission proof is red.\nnext: land #12 first, then submit again', 'fix the gate and retry')).error.next,
  'land #12 first, then submit again', 'an inherited failure retains its specific recovery');
  assert.equal(refusalDocument(new Refused('GATE_RED',
    'the submission proof is red.\nnext: land #12 first, then submit again')).error.message,
  'the submission proof is red.\nnext: land #12 first, then submit again', 'JSON retains the original message');
  assert.equal(refusalDocument(new Refused('GATE_RED',
    'reported output:\nnext: an unrelated printed line\nend of report', 'repair this fixture')).error.next,
  'repair this fixture', 'nonterminal report text cannot override contextual recovery');
  assert.equal(refusalDocument(new Refused('GATE_RED',
    'the submission proof is red.', 'repair this fixture, commit, and submit again')).error.next,
  'repair this fixture, commit, and submit again', 'contextual recovery remains explicit without a message next line');
  const oldReceipt = recordedRefusal(new Refused('NOT_SUBMITTED', 'item #12 is verified, not submitted'));
  assert.equal(oldReceipt.next, RECORDED_GENERIC_NEXT, 'canonical receipts keep their original wire guidance');
  assert.doesNotMatch(refusalDocument(refusalFromReceipt(oldReceipt)).error.next, /Run pullboard help, correct the reported problem/u,
    'presenting an old receipt computes current guidance');
  assert.equal(refusalDocument(new Refused(oldReceipt.code, oldReceipt.message, oldReceipt.next)).error.next,
    refusalDocument(refusalFromReceipt(oldReceipt)).error.next, 'an old generic remote fallback is never displayed');
  const oldDiagnostic = recordedRefusal(new Refused('GATE_RED', 'the proof is red; fix it, commit, submit again\nfailure: fixture output'));
  assert.match(oldDiagnostic.next, /\nfailure: fixture output/u, 'the historical serializer retains its multiline value');
  assert.equal(refusalDocument(refusalFromReceipt(oldDiagnostic)).error.next, 'fix it, commit, submit again',
    'a derived historical diagnostic tail is not repeated in the current footer');
  const remoteStep = { code: 'FUTURE_REMOTE_RULE', message: 'The service refused.', next: 'ask the service owner to restore this board' };
  assert.equal(refusalDocument(refusalFromReceipt(remoteStep)).error.next, remoteStep.next,
    'a remote explicit action distinct from historical derivation survives reconstruction');

  const box = e2e.sandbox();
  box.env.PULLBOARD_MODEL = 'Refusal Fixture Model';
  const gateFile = join(box.dir, 'fixture-gate.cjs');
  writeFileSync(gateFile, "if (require('node:fs').existsSync('web/RED')) { console.log('GATE_FAILURE_MARKER'); process.exit(1); }\n");
  const gate = `'${process.execPath.replaceAll("'", "'\\''")}' '${gateFile.replaceAll("'", "'\\''")}'`;
  const { repo, web } = e2e.project(gate, box);
  const id = addBuild(box, repo, 'Independent review recovery', gate);
  succeeded(box.run(web, 'claim', String(id)));
  mkdirSync(join(web, 'web'), { recursive: true });
  writeFileSync(join(web, 'web', 'receipt.txt'), 'a real build\n');
  box.git(web, 'add', '-A');
  box.git(web, 'commit', '-q', '-m', 'test: build review fixture [G1]');
  succeeded(box.run(web, 'submit', String(id)));

  const mainRefusal = box.run(repo, 'next', '--verify', String(id), '--json');
  assert.equal(mainRefusal.code, 1, `${mainRefusal.out}\n${mainRefusal.err}`);
  const mainError = JSON.parse(mainRefusal.out).error;
  assert.equal(mainError.code, 'MAIN_IS_COORDINATOR');
  assert.match(mainError.next, /git worktree add --detach/u);
  assert.match(mainError.next, /reviewer.*(?:did not|not).*build/iu, 'the step requires an independent reviewer');
  const reviewer = join(repo, '.claude', 'worktrees', 'reviewer');
  box.git(repo, 'worktree', 'add', '-q', '--detach', reviewer, 'HEAD');
  succeeded(box.run(reviewer, 'join', 'web', '--model', 'Independent Reviewer Model'));
  const selected = succeeded(box.run(reviewer, 'next', '--verify', String(id), '--json'));
  assert.equal(JSON.parse(selected.out).item.item_id, id, 'the recovery reaches review without SELF_VERIFY');

  const gateBox = e2e.sandbox();
  gateBox.env.PULLBOARD_MODEL = 'Gate Fixture Model';
  const { repo: gateRepo, web: gateWeb } = e2e.project(gate, gateBox);
  const redId = addBuild(gateBox, gateRepo, 'Gate failure recovery', gate);
  succeeded(gateBox.run(gateWeb, 'claim', String(redId)));
  mkdirSync(join(gateWeb, 'web'), { recursive: true });
  writeFileSync(join(gateWeb, 'web', 'RED'), 'armed\n');
  gateBox.git(gateWeb, 'add', '-A');
  gateBox.git(gateWeb, 'commit', '-q', '-m', 'test: arm gate fixture [G1]');
  const red = gateBox.run(gateWeb, 'submit', String(redId));
  assert.equal(red.code, 1, `${red.out}\n${red.err}`);
  assert.equal((red.err.match(/\[GATE_RED\]/gu) ?? []).length, 1, `${red.out}\n${red.err}`);
  assert.equal((red.err.match(/GATE_FAILURE_MARKER/gu) ?? []).length, 1, `the failure report appears once\n${red.out}\n${red.err}`);
  assert.match(red.err, /next: .*fix.*commit.*submit/iu);
  assert.equal((red.err.match(/^next: /gmu) ?? []).length, 1, 'plain refusals print one recovery footer');
  rmSync(join(gateWeb, 'web', 'RED'));
  gateBox.git(gateWeb, 'add', '-u');
  gateBox.git(gateWeb, 'commit', '-q', '-m', 'test: fix gate fixture [G1]');
  succeeded(gateBox.run(gateWeb, 'submit', String(redId)));

  box.env.CODEX_THREAD_ID = 'main-owner-session';
  succeeded(box.run(repo, 'join', 'coordinator', '--model', 'Coordinator Fixture Model'));
  const bindingPath = join(repo, '.git', 'pullboard-checkout-session.json');
  const binding = readFileSync(bindingPath, 'utf8');
  box.env.CODEX_THREAD_ID = 'new-agent-session';
  const foreign = box.run(repo, 'claim', String(id), '--json');
  assert.equal(foreign.code, 1, `${foreign.out}\n${foreign.err}`);
  const foreignError = JSON.parse(foreign.out).error;
  assert.equal(foreignError.code, 'NOT_YOUR_CHECKOUT');
  assert.match(foreignError.next, /git worktree add --detach/u, 'recovery does not call Pullboard from the blocked checkout');
  const recovery = join(repo, '.claude', 'worktrees', 'new-agent');
  box.git(repo, 'worktree', 'add', '-q', '--detach', recovery, 'HEAD');
  succeeded(box.run(recovery, 'join', 'web', '--model', 'New Agent Fixture Model'));
  succeeded(box.run(recovery, 'whoami', '--json'));
  assert.equal(readFileSync(bindingPath, 'utf8'), binding, 'recovery leaves the main owner binding unchanged');
});


test('the light collector preserves prepared JSON refusal documents and a single success output [A1,P4,B26,C7]', async () => {
  const cases = [
    { code: 'NO_ITEM', message: 'No item exists.' },
    { code: 'FUTURE_REMOTE_RULE', message: 'The service refused.', next: 'ask its owner to restore the board' },
    { code: 'SPEC_NOT_APPROVED', message: 'The rule is pending; ask the person to approve it.' },
    refusalFromReceipt(recordedRefusal(new Refused('GATE_RED', 'gate red; fix it, commit, submit again'))),
  ];
  for (const error of cases) {
    let text = '';
    const io = lightCommandOutput(['show', '1', '--json'], { stdout: { write(value) { text += value; } }, stderr: { write() {} } });
    io.caller('seat', '/fixture');
    io.refusal(error);
    await io.prepareRefusal();
    io.flush(1);
    io.flush(1);
    assert.deepEqual(JSON.parse(text), refusalDocument(error, { caller: 'seat' }), 'lazy preparation preserves the synchronous public envelope and caller guidance');
  }
  let text = '';
  const io = lightCommandOutput(['version', '--json'], { stdout: { write(value) { text += value; } }, stderr: { write() {} } });
  io.result({ release: '0.9.2' });
  io.flush(0);
  io.flush(0);
  assert.deepEqual(JSON.parse(text), { version: 1, release: '0.9.2' }, 'success needs no refusal preparation and flushes once');
});