gstack/test/gstack-ship-receipt.test.ts

/**
 * C5: the handoff record. `write` renders the fenced block identifiers-first
 * and places it at the top of a PR body; `read` parses it back from a body or
 * a PR (RECEIPT_MISSING / RECEIPT_INVALID); `census` computes the P7 adoption
 * number over merged PRs, deduplicated by run and thread, against a cohort.
 */
import { afterEach, describe, expect, test } from 'bun:test';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { EXIT } from '../lib/headless-artifacts';
import { bindReceipt, computeCensus, extractReceipt, placeReceiptFirst, receiptSummaryLine, renderReceiptBlock } from '../lib/ship-receipt';
import { cleanup, ghShim, makeFixtureRepo, makePr, recordAndBundle, restamp, runBin, type FixtureRepo } from './helpers/restamp-fixture';

const repos: FixtureRepo[] = [];
const fixture = () => { const r = makeFixtureRepo({ prefix: 'ship-receipt-' }); repos.push(r); return r; };
afterEach(() => { while (repos.length) cleanup(repos.pop()!); });

const HEAD = 'a'.repeat(40);
const block = (receipt: Record<string, unknown>) => renderReceiptBlock(receipt as any);

describe('gstack-ship-receipt write', () => {
  test('writes the block identifiers-first, validates it against the ship-receipt schema, and puts it at the top of the PR body', () => {
    const repo = fixture();
    makePr(repo, 'pr-a', { expects: '1.2.4.0' });
    expect(restamp(repo, ['--version', '1.2.4.0']).status).toBe(EXIT.ok);
    repo.git('commit', '-qam', 'stamp');
    const head = repo.git('rev-parse', 'HEAD');
    const bundle = path.join(repo.root, 'bundle.json');
    recordAndBundle(repo, repo.work, [{ label: 'tests', command: 'true' }], bundle);
    const treeReceipt = path.join(repo.root, 'tree-receipt.json');
    const tr = runBin(repo, 'gstack-tree-receipt', ['--base', 'main', '--gated', head, '--bundle', bundle, '--predecessor', 'b'.repeat(40), '--json']);
    fs.writeFileSync(treeReceipt, tr.out);
    const body = path.join(repo.root, 'body.md');
    fs.writeFileSync(body, '## Summary\n\nProse that a truncated message may lose.\n');
    const w = runBin(repo, 'gstack-ship-receipt', ['write', '--pr', '42', '--base', 'main', '--receipt', treeReceipt,
      '--gate', '{"tests":{"pass":1,"fail":0,"skip":0}}', '--ci', '@' + path.join(repo.root, 'ci.json'), '--spend-usd', '0.42',
      '--session-kind', 'unattended', '--artifacts-consumed', '2/3', '--run', 'run-1', '--thread', 'jam_1', '--queue-mode', 'stamp-at-merge',
      '--preregistration', 'none (no preregistration_shas)', '--history', 'squash-ok', '--body', body, '--out', path.join(repo.root, 'receipt.md')]);
    expect(w.status).toBe(EXIT.usage);
    fs.writeFileSync(path.join(repo.root, 'ci.json'), '{"checks":{"pass":3,"fail":0,"pending":0}}');
    const ok = runBin(repo, 'gstack-ship-receipt', ['write', '--pr', '42', '--base', 'main', '--receipt', treeReceipt,
      '--gate', '{"tests":{"pass":1,"fail":0,"skip":0}}', '--ci', '@' + path.join(repo.root, 'ci.json'), '--spend-usd', '0.42',
      '--session-kind', 'unattended', '--artifacts-consumed', '2/3', '--run', 'run-1', '--thread', 'jam_1', '--queue-mode', 'stamp-at-merge',
      '--preregistration', 'none (no preregistration_shas)', '--history', 'squash-ok', '--body', body, '--out', path.join(repo.root, 'receipt.md')]);
    expect(ok.status).toBe(EXIT.ok);
    expect(ok.err.trim()).toBe(`SHIP_RECEIPT: pr=42 head=${head.slice(0, 12)} version=1.2.4.0 base=main gated_tree=${repo.git('rev-parse', 'HEAD^{tree}').slice(0, 12)} tree=same-modulo-stamps gate-reuse=eligible (reusable: tests; rerun: -) predecessor=${'b'.repeat(12)} session_kind=unattended artifacts_consumed=2/3`);
    const parsed = extractReceipt(ok.out);
    expect(parsed.found).toBe(true);
    expect(parsed.errors).toEqual([]);
    expect(Object.keys(parsed.receipt!)).toEqual(['schema_version', 'pr', 'head', 'version', 'base', 'gated_tree', 'predecessor', 'tree', 'gate_reuse', 'gate', 'ci', 'spend_usd', 'session_kind', 'artifacts_consumed', 'run', 'thread', 'policy', 'queue_mode', 'preregistration', 'history']);
    expect(parsed.receipt).toMatchObject({ schema_version: 1, pr: 42, head, version: '1.2.4.0', base: 'main', tree: 'same-modulo-stamps', spend_usd: 0.42, ci: { checks: { pass: 3 } } });
    expect(parsed.receipt!.policy).toMatch(/^origin\/main@[0-9a-f]{12}:\.gstack\/ship-policy\.json$/);
    const written = fs.readFileSync(body, 'utf8');
    expect(written.startsWith('```gstack-ship-receipt\n{\n  "schema_version": 1,\n  "pr": 42,\n  "head": "' + head + '"')).toBe(true);
    expect(written).toContain('\n```\n\n## Summary\n\nProse that a truncated message may lose.\n');
    expect(fs.readFileSync(path.join(repo.root, 'receipt.md'), 'utf8')).toBe(ok.out);
    const art = runBin(repo, 'gstack-artifact', ['validate', path.join(repo.root, 'receipt.json'), '--as', 'ship-receipt']);
    expect(art.status).not.toBe(EXIT.ok);
    fs.writeFileSync(path.join(repo.root, 'receipt.json'), JSON.stringify(parsed.receipt));
    expect(runBin(repo, 'gstack-artifact', ['validate', path.join(repo.root, 'receipt.json'), '--as', 'ship-receipt']).status).toBe(EXIT.ok);
    const again = runBin(repo, 'gstack-ship-receipt', ['write', '--pr', '43', '--base', 'main', '--body', body, '--session-kind', 'interactive', '--json']);
    expect(again.status).toBe(EXIT.ok);
    const j = JSON.parse(again.out);
    expect(j).toMatchObject({ pr: 43, head, session_kind: 'interactive' });
    expect('tree' in j).toBe(false);
    const rewritten = fs.readFileSync(body, 'utf8');
    expect(rewritten.match(/```gstack-ship-receipt/g)).toHaveLength(1);
    expect(rewritten).toContain('"pr": 43');
    expect(rewritten).toContain('## Summary');
  });

  test('refuses an invalid receipt before writing (RECEIPT_INVALID) and a non-integer --pr', () => {
    const repo = fixture();
    const body = path.join(repo.root, 'body.md');
    fs.writeFileSync(body, 'prose\n');
    const r = runBin(repo, 'gstack-ship-receipt', ['write', '--pr', 'seven', '--base', 'main', '--session-kind', 'x', '--body', body]);
    expect(r.status).toBe(EXIT.usage);
    expect(r.err).toContain('--pr must be an integer');
    const receiptFile = path.join(repo.root, 'tree-receipt.json');
    fs.writeFileSync(receiptFile, JSON.stringify({ tree: 'sideways', gate_reuse: 'eligible', gate_reuse_reason: 'x' }));
    const inv = runBin(repo, 'gstack-ship-receipt', ['write', '--pr', '7', '--base', 'main', '--session-kind', 'x', '--receipt', receiptFile, '--body', body]);
    expect(inv.status).toBe(EXIT.fail);
    expect(inv.err).toMatch(/\(RECEIPT_INVALID\)/);
    expect(inv.err).toContain('nothing written');
    expect(fs.readFileSync(body, 'utf8')).toBe('prose\n');
  });
});

describe('gstack-ship-receipt read', () => {
  test('read --body and read --pr (through gh) return the block; a missing block is RECEIPT_MISSING, a broken one RECEIPT_INVALID', () => {
    const repo = fixture();
    const receipt = { schema_version: 1, pr: 5, head: HEAD, version: '1.2.4.0', base: 'main', session_kind: 'unattended', artifacts_consumed: '1/1', run: 'run-5', thread: 'jam_5' };
    const body = path.join(repo.root, 'body.md');
    fs.writeFileSync(body, placeReceiptFirst('Prose.\n', receipt as any));
    const b = runBin(repo, 'gstack-ship-receipt', ['read', '--body', body, '--json']);
    expect(b.status).toBe(EXIT.ok);
    expect(JSON.parse(b.out)).toEqual(receipt);
    expect(b.err.trim()).toBe(receiptSummaryLine(receipt as any));
    const env = ghShim(repo, {
      5: { body: fs.readFileSync(body, 'utf8') },
      6: { body: 'No receipt here.\n' },
      7: { body: block({ schema_version: 2, head: HEAD, base: 'main' }) },
      8: { body: '```gstack-ship-receipt\n{not json\n```\n' },
    });
    const p = runBin(repo, 'gstack-ship-receipt', ['read', '--pr', '5', '--repo', 'o/r'], env);
    expect(p.status).toBe(EXIT.ok);
    expect(p.out).toBe(renderReceiptBlock(receipt as any));
    const missing = runBin(repo, 'gstack-ship-receipt', ['read', '--pr', '6', '--json'], env);
    expect(missing.status).toBe(EXIT.fail);
    expect(missing.err).toMatch(/PR #6.*\(RECEIPT_MISSING\)/);
    expect(JSON.parse(missing.out)).toEqual({ found: false, errors: [] });
    const invalid = runBin(repo, 'gstack-ship-receipt', ['read', '--pr', '7', '--json'], env);
    expect(invalid.status).toBe(EXIT.fail);
    expect(invalid.err).toMatch(/\(RECEIPT_INVALID\)/);
    expect(JSON.parse(invalid.out)).toMatchObject({ found: true, valid: false });
    const broken = runBin(repo, 'gstack-ship-receipt', ['read', '--pr', '8'], env);
    expect(broken.status).toBe(EXIT.fail);
    expect(broken.err).toMatch(/block is not JSON.*\(RECEIPT_INVALID\)/);
    expect(runBin(repo, 'gstack-ship-receipt', ['read', '--pr', '9'], env).status).toBe(EXIT.fail);
    expect(runBin(repo, 'gstack-ship-receipt', ['read']).status).toBe(EXIT.usage);
  });

  test('the unattended handoff write lands in the file docs/unattended.md tells the parent to read --body, at HEAD and with no pr (GSTA-88)', () => {
    const root = path.resolve(import.meta.dir, '..');
    const tmpl = fs.readFileSync(path.join(root, 'ship/sections/handoff.md.tmpl'), 'utf8');
    const write = tmpl.match(/gstack-ship-receipt (write [^\n`]*)/)![1].trim();
    const out = write.match(/--out (\S+)/)?.[1];
    expect(out).toBe('.gstack/tmp/ship-receipt.md');
    expect(fs.readFileSync(path.join(root, 'ship/sections/handoff.md'), 'utf8')).toContain(write);
    const docs = fs.readFileSync(path.join(root, 'docs/unattended.md'), 'utf8').replace(/\s+/g, ' ');
    expect(docs).toContain(`gstack-ship-receipt read --body ${out} --json`);
    expect(docs).toMatch(/read --pr <n> --json` only once a PR exists/);

    const repo = fixture();
    const env = { GSTACK_SESSION_KIND: 'unattended' };
    fs.mkdirSync(path.join(repo.work, '.gstack/tmp'), { recursive: true });
    fs.writeFileSync(path.join(repo.work, '.gstack/tmp/ship-gate.json'), '{"free":{"pass":1,"fail":0,"skip":0}}');
    expect(runBin(repo, 'gstack-issue-links', ['--base', 'main', '--out', '.gstack/tmp/issues.json'], env).status).toBe(EXIT.ok);
    const w = runBin(repo, 'gstack-ship-receipt', write.replace('<base>', 'main').split(' '), env);
    expect(w.status).toBe(EXIT.ok);
    expect(fs.readFileSync(path.join(repo.work, out!), 'utf8')).toBe(w.out);
    const r = runBin(repo, 'gstack-ship-receipt', ['read', '--body', out!, '--json'], env);
    expect(r.status).toBe(EXIT.ok);
    const receipt = JSON.parse(r.out);
    expect(receipt).toMatchObject({ head: repo.git('rev-parse', 'HEAD'), base: 'main', session_kind: 'unattended' });
    expect(receipt).not.toHaveProperty('pr');
  });
});

describe('gstack-ship-receipt result (/ship terminal line, GBRA-108)', () => {
  test('binds the receipt to HEAD, writes the run record with the head and the receipt path, and ends with GSTACK_RESULT: skill=ship; a missing or stale receipt is status=refused run=-', () => {
    const repo = fixture();
    const head = repo.git('rev-parse', 'HEAD');
    const state = path.join(repo.root, 'state');
    const env = { ...ghShim(repo, {
      5: { headRefOid: head, body: placeReceiptFirst('Prose.\n', { schema_version: 1, pr: 5, head, base: 'main', queue_mode: 'stamp-at-merge' } as any) },
      6: { headRefOid: head, body: placeReceiptFirst('Prose.\n', { schema_version: 1, pr: 6, head: 'b'.repeat(40), base: 'main' } as any) },
      7: { headRefOid: head, body: 'No receipt here.\n' },
      9: { headRefOid: 'd'.repeat(40), body: placeReceiptFirst('Prose.\n', { schema_version: 1, pr: 9, head, base: 'main' } as any) },
      10: { body: placeReceiptFirst('Prose.\n', { schema_version: 1, pr: 10, head, base: 'main' } as any) },
    }), GSTACK_STATE_ROOT: state, GSTACK_SESSION_KIND: 'unattended' };
    const ok = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '5'], env);
    expect(ok.status).toBe(EXIT.ok);
    const last = ok.out.trim().split('\n').at(-1)!;
    const m = /^GSTACK_RESULT: skill=ship status=complete run=(.+)$/.exec(last);
    expect(m).not.toBeNull();
    const dir = m![1]!;
    expect(dir.startsWith(path.join(state, 'ship', 'runs'))).toBe(true);
    expect(dir.endsWith(`-${head.slice(0, 12)}`)).toBe(true);
    const run = JSON.parse(fs.readFileSync(path.join(dir, 'ship-run.json'), 'utf8'));
    expect(fs.existsSync(path.join(dir, 'run.json'))).toBe(false);
    expect(run).toMatchObject({ schema_version: 1, skill: 'ship', status: 'complete', head, pr: 5, base: 'main', queue_mode: 'stamp-at-merge', receipt: path.join(dir, 'ship-receipt.md'), receipt_source: 'PR #5' });
    expect(extractReceipt(fs.readFileSync(run.receipt, 'utf8')).receipt).toMatchObject({ pr: 5, head });
    expect(ok.err.trim()).toBe(`SHIP_RECEIPT: pr=5 head=${head.slice(0, 12)} version=- base=main`);

    const stale = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '6'], env);
    expect(stale.status).toBe(EXIT.refused);
    expect(stale.out.trim()).toBe('GSTACK_RESULT: skill=ship status=refused run=-');
    expect(stale.err).toMatch(new RegExp(`PR #6's ship receipt is for bbbbbbbbbbbb, not the head ${head.slice(0, 12)} being merged.*\\(QUEUE_RECEIPT_STALE; https://github.com/garrytan/gstack/blob/main/docs/troubleshooting.md#queue-receipt-stale\\)`));
    const missing = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '7', '--json'], env);
    expect(missing.status).toBe(EXIT.refused);
    expect(JSON.parse(missing.out)).toMatchObject({ skill: 'ship', status: 'refused', run: '-', code: 'QUEUE_RECEIPT_MISSING' });
    const unpushed = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '9'], env);
    expect([unpushed.status, unpushed.out.trim()]).toEqual([EXIT.refused, 'GSTACK_RESULT: skill=ship status=refused run=-']);
    expect(unpushed.err).toContain(`HEAD ${head.slice(0, 12)} is not PR #9's pushed head dddddddddddd; push it, then rerun gstack-ship-receipt result`);
    const noOid = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '10'], env);
    expect([noOid.status, noOid.out.trim()]).toEqual([EXIT.fail, 'GSTACK_RESULT: skill=ship status=incomplete run=-']);
    expect(noOid.err).toContain('gh pr view returned no headRefOid for PR #10');
    expect(runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '--repo'], env).status).toBe(EXIT.usage);
    const bothFlags = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '5', '--body', path.join(repo.work, 'any.md')], env);
    expect([bothFlags.status, bothFlags.out]).toEqual([EXIT.usage, '']);
    expect(bothFlags.err).toContain('not both');
    const dirBody = runBin(repo, 'gstack-ship-receipt', ['result', '--body', repo.work], env);
    expect([dirBody.status, dirBody.out.trim()]).toEqual([EXIT.fail, 'GSTACK_RESULT: skill=ship status=incomplete run=-']);
    expect(dirBody.err).toContain(`cannot read ${repo.work}`);

    const bodyFile = path.join(repo.work, '.gstack/tmp/ship-receipt.md');
    fs.mkdirSync(path.dirname(bodyFile), { recursive: true });
    fs.writeFileSync(bodyFile, renderReceiptBlock({ schema_version: 1, head, base: 'main' } as any));
    const handoff = runBin(repo, 'gstack-ship-receipt', ['result', '--body', bodyFile, '--out', path.join(repo.root, 'run-out')], env);
    expect(handoff.status).toBe(EXIT.ok);
    expect(handoff.out.trim()).toBe(`GSTACK_RESULT: skill=ship status=complete run=${path.join(repo.root, 'run-out')}`);
    expect(JSON.parse(fs.readFileSync(path.join(repo.root, 'run-out', 'ship-run.json'), 'utf8'))).toMatchObject({ head, pr: null, receipt_source: bodyFile, session_kind: 'unattended' });
    expect(runBin(repo, 'gstack-ship-receipt', ['result', '--body', path.join(repo.root, 'absent.md')], env).status).toBe(EXIT.refused);
    expect(runBin(repo, 'gstack-ship-receipt', ['result'], env).status).toBe(EXIT.usage);
    const relative = runBin(repo, 'gstack-ship-receipt', ['result', '--body', bodyFile, '--out', 'rel-out'], env);
    expect(relative.status).toBe(EXIT.ok);
    expect(relative.out.trim()).toBe(`GSTACK_RESULT: skill=ship status=complete run=${path.join(repo.work, 'rel-out')}`);
    expect(fs.existsSync(path.join(repo.work, 'rel-out', 'ship-run.json'))).toBe(true);
    const blocker = path.join(repo.root, 'not-a-dir');
    fs.writeFileSync(blocker, 'file\n');
    const unwritable = runBin(repo, 'gstack-ship-receipt', ['result', '--body', bodyFile, '--out', path.join(blocker, 'sub')], env);
    expect([unwritable.status, unwritable.out.trim()]).toEqual([EXIT.fail, 'GSTACK_RESULT: skill=ship status=incomplete run=-']);
    expect(unwritable.err).toContain(`cannot write the run record under ${path.join(blocker, 'sub')}`);
    expect(fs.readdirSync(path.join(state, 'ship', 'runs')).length).toBe(1);
  });

  // Value: protects=a --body handoff refusal names "the receipt", never "PR #-", and a gh failure is EXIT.fail, not a refusal;
  // fails_when=the PR #-'s rewrite stops matching or gh errors are mapped to status=refused; why_new=the result test covers
  // only the --pr refusals, an absent file and a bound handoff; seam=none; no_claim=real gh (the shim stands in; unit only)
  test('a --body file with no block or a stale head is refused in the receipt\'s own words, and a gh failure is a plain failure, not a refusal', () => {
    const repo = fixture();
    const head = repo.git('rev-parse', 'HEAD');
    const env = { ...ghShim(repo, {}), GSTACK_STATE_ROOT: path.join(repo.root, 'state') };
    const dir = path.join(repo.work, '.gstack/tmp');
    fs.mkdirSync(dir, { recursive: true });
    const noBlock = path.join(dir, 'no-block.md');
    fs.writeFileSync(noBlock, 'Handoff prose without a receipt.\n');
    const missing = runBin(repo, 'gstack-ship-receipt', ['result', '--body', noBlock], env);
    expect(missing.status).toBe(EXIT.refused);
    expect(missing.out.trim()).toBe('GSTACK_RESULT: skill=ship status=refused run=-');
    expect(missing.err).toContain("the receipt's body carries no ship receipt");
    expect(missing.err).not.toContain('PR #-');
    const staleFile = path.join(dir, 'stale.md');
    fs.writeFileSync(staleFile, renderReceiptBlock({ schema_version: 1, head: 'c'.repeat(40), base: 'main' } as any));
    const stale = runBin(repo, 'gstack-ship-receipt', ['result', '--body', staleFile], env);
    expect(stale.status).toBe(EXIT.refused);
    expect(stale.err).toContain(`the receipt's ship receipt is for cccccccccccc, not the head ${head.slice(0, 12)} being merged`);
    const invalidFile = path.join(dir, 'invalid.md');
    fs.writeFileSync(invalidFile, '```gstack-ship-receipt\n{"schema_version":1}\n```\n');
    const invalid = runBin(repo, 'gstack-ship-receipt', ['result', '--body', invalidFile], env);
    expect([invalid.status, invalid.out.trim()]).toEqual([EXIT.refused, 'GSTACK_RESULT: skill=ship status=refused run=-']);
    expect(invalid.err).toMatch(/the receipt's ship receipt is invalid \(.*\).*\(QUEUE_RECEIPT_MISSING/);
    const otherPrEnv = { ...env, ...ghShim(repo, { 8: { headRefOid: head, body: placeReceiptFirst('Prose.\n', { schema_version: 1, pr: 99, head, base: 'main' } as any) } }) };
    const otherPr = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '8'], otherPrEnv);
    expect([otherPr.status, otherPr.out.trim()]).toEqual([EXIT.refused, 'GSTACK_RESULT: skill=ship status=refused run=-']);
    expect(otherPr.err).toContain("PR #8's ship receipt names pr=99, not this PR");
    const pinned = path.join(dir, 'pinned.md');
    fs.writeFileSync(pinned, renderReceiptBlock({ schema_version: 1, head: 'c'.repeat(40), base: 'main' } as any));
    const override = runBin(repo, 'gstack-ship-receipt', ['result', '--body', pinned, '--head', 'c'.repeat(40), '--out', path.join(repo.root, 'pinned-out')], env);
    expect([override.status, override.out.trim()]).toEqual([EXIT.ok, `GSTACK_RESULT: skill=ship status=complete run=${path.join(repo.root, 'pinned-out')}`]);
    expect(JSON.parse(fs.readFileSync(path.join(repo.root, 'pinned-out', 'ship-run.json'), 'utf8')).head).toBe('c'.repeat(40));
    const badHead = runBin(repo, 'gstack-ship-receipt', ['result', '--body', pinned, '--head', '../../etc'], env);
    expect([badHead.status, badHead.out]).toEqual([EXIT.usage, '']);
    expect(badHead.err).toContain('--head must be a full hex commit id');
    const shortHead = runBin(repo, 'gstack-ship-receipt', ['result', '--body', pinned, '--head', head.slice(0, 12)], env);
    expect([shortHead.status, shortHead.out]).toEqual([EXIT.usage, '']);
    expect(shortHead.err).toContain('--head must be a full hex commit id');
    const upper = runBin(repo, 'gstack-ship-receipt', ['result', '--body', pinned, '--head', 'C'.repeat(40), '--out', path.join(repo.root, 'upper-out')], env);
    expect([upper.status, upper.out.trim()]).toEqual([EXIT.ok, `GSTACK_RESULT: skill=ship status=complete run=${path.join(repo.root, 'upper-out')}`]);
    const noGit = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-receipt-nogit-'));
    const outside = runBin(repo, 'gstack-ship-receipt', ['result', '--body', pinned], env, noGit);
    expect([outside.status, outside.err.trim()]).toEqual([EXIT.usage, 'gstack-ship-receipt result: --head <sha> is required outside a git repository']);
    fs.rmSync(noGit, { recursive: true, force: true });
    const ghDown = runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '9'], env);
    expect(ghDown.status).toBe(EXIT.fail);
    expect(ghDown.err).toContain('gh pr view failed');
    expect(ghDown.out.trim()).toBe('GSTACK_RESULT: skill=ship status=incomplete run=-');
    expect(JSON.parse(runBin(repo, 'gstack-ship-receipt', ['result', '--pr', '9', '--json'], env).out)).toMatchObject({ skill: 'ship', status: 'incomplete', run: '-' });
    expect(fs.existsSync(path.join(repo.root, 'state', 'ship', 'runs'))).toBe(false);
  });
});

describe('bindReceipt head matching (rule 22)', () => {
  // Value: protects=a receipt binds only to a full or 12+ character prefix of an accepted head, and names the PR it was written for;
  // fails_when=the 12-character floor is dropped (head "a" would bind any head) or the pr check is removed;
  // why_new=the queue, train and result tests bind full 40-character heads only; seam=none; no_claim=gh and CLI wiring (pure function)
  test('binds a full head or a 12+ character prefix, refuses shorter prefixes, other heads and another PR\'s receipt', () => {
    const head = 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0';
    const other = 'f'.repeat(40);
    const body = (h: string, pr?: number) => placeReceiptFirst('Prose.\n', { schema_version: 1, head: h, base: 'main', ...(pr === undefined ? {} : { pr }) } as any);
    const rows: Array<[string, string, string[], string]> = [
      ['full head', head, [head], 'ok'],
      ['12-char prefix', head.slice(0, 12), [head], 'ok'],
      ['11-char prefix', head.slice(0, 11), [head], 'QUEUE_RECEIPT_STALE'],
      ['7-char prefix', head.slice(0, 7), [head], 'QUEUE_RECEIPT_STALE'],
      ['other head', other, [head], 'QUEUE_RECEIPT_STALE'],
      ['pin or current head', head, [other, head], 'ok'],
    ];
    for (const [name, h, accepted, want] of rows) {
      const b = bindReceipt(body(h), '3438', accepted);
      expect([name, b.ok ? 'ok' : b.code]).toEqual([name, want]);
      if (b.ok) expect(b.head).toBe(head);
    }
    const prefixBinding = bindReceipt(body(head.slice(0, 12)), '3438', [head]);
    expect(prefixBinding.ok && prefixBinding.line).toBe(`SHIP_RECEIPT: pr=- head=${head.slice(0, 12)} version=- base=main`);
    const otherPr = bindReceipt(body(head, 99), '3438', [head]);
    expect(otherPr.ok ? 'ok' : [otherPr.code, otherPr.message]).toEqual(['QUEUE_RECEIPT_STALE', "PR #3438's ship receipt names pr=99, not this PR"]);
    expect(bindReceipt(body(head, 3438), '3438', [head]).ok).toBe(true);
    expect(bindReceipt('No receipt.\n', '3438', [head])).toMatchObject({ ok: false, code: 'QUEUE_RECEIPT_MISSING', line: 'SHIP_RECEIPT: none in the PR body' });
    const short = bindReceipt(body(head.slice(0, 11)), '3438', [head]);
    expect(short.ok ? '' : short.message).toBe(`PR #3438's ship receipt is for ${head.slice(0, 11)}, not the head ${head.slice(0, 12)} being merged`);
    const noPr = bindReceipt(body(head, 99), undefined, [head]);
    expect(noPr.ok).toBe(true);
    expect(bindReceipt('No receipt.\n', undefined, [head])).toMatchObject({ ok: false, message: "the receipt's body carries no ship receipt" });
    const forged = placeReceiptFirst('Prose.\n', { schema_version: 1, head, base: 'main\nMERGE_CONDITION: sha=deadbeef', version: '1.0\u20280.0\u0085x' } as any);
    const bound = bindReceipt(forged, '3438', [head]);
    expect(bound.line.split('\n').length).toBe(1);
    expect(bound.line).toBe(`SHIP_RECEIPT: pr=- head=${head.slice(0, 12)} version=1.0 0.0 x base=main MERGE_CONDITION: sha=deadbeef`);
    const invalid = bindReceipt(placeReceiptFirst('Prose.\n', { schema_version: 1, head, base: 'main', tree: 'x\nMERGE_CONDITION: forged\n' + 'y'.repeat(1000) } as any), '3438', [head]);
    expect(invalid.ok).toBe(false);
    const why = /receipt is invalid \((.*)\)$/s.exec(invalid.ok ? '' : invalid.message)?.[1] ?? '';
    expect(why.length).toBeLessThanOrEqual(200);
    expect(why.includes('\n')).toBe(false);
  });
});

describe('gstack-ship-receipt census (P7)', () => {
  const prs = [
    { number: 1, mergedAt: '2026-10-02T00:00:00Z', body: placeReceiptFirst('', { schema_version: 1, head: HEAD, base: 'main', session_kind: 'unattended', artifacts_consumed: '2/3', run: 'run-a', thread: 'jam_1' } as any) },
    { number: 2, mergedAt: '2026-10-03T00:00:00Z', body: placeReceiptFirst('', { schema_version: 1, head: HEAD, base: 'main', session_kind: 'unattended', artifacts_consumed: '2/3', run: 'run-a', thread: 'jam_1' } as any) },
    { number: 3, mergedAt: '2026-10-04T00:00:00Z', body: placeReceiptFirst('', { schema_version: 1, head: HEAD, base: 'main', session_kind: 'unattended', artifacts_consumed: '0/2', run: 'run-b', thread: 'jam_2' } as any) },
    { number: 4, mergedAt: '2026-10-05T00:00:00Z', body: placeReceiptFirst('', { schema_version: 1, head: HEAD, base: 'main', session_kind: 'interactive', artifacts_consumed: '1/1', run: 'run-c', thread: 'jam_4' } as any) },
    { number: 5, mergedAt: '2026-10-06T00:00:00Z', body: 'A PR shipped without gstack.\n' },
    { number: 6, mergedAt: '2026-10-07T00:00:00Z', body: block({ schema_version: 1, base: 'main' }) },
  ];

  test('computeCensus deduplicates by run, counts consumed threads against the cohort, and reports invalid receipts', () => {
    const c = computeCensus('o/r', '2026-10-01', prs, ['jam_1', 'jam_2', 'jam_3']);
    expect(c).toMatchObject({ merged_prs: 6, with_receipt: 5, invalid_receipts: 1, unattended_prs: 2, consumed_prs: 2, runs: ['run-a', 'run-b', 'run-c'], threads: ['jam_1', 'jam_2', 'jam_4'], consumed_threads: ['jam_1', 'jam_4'], cohort_consumed: 1, adoption: '1/3 (cohort)', durable: 'yes', by_session_kind: { unattended: 3, interactive: 1 } });
    expect(c.prs.find(p => p.number === 6)).toMatchObject({ valid: false });
    const noCohort = computeCensus('o/r', '2026-10-01', prs, null);
    expect(noCohort.adoption).toBe('2/3 (threads seen; no cohort file)');
  });

  test('census --repo --since reads merged PRs through gh and prints the CENSUS line', () => {
    const repo = fixture();
    const env = ghShim(repo, {}, prs);
    const cohort = path.join(repo.root, 'cohort.txt');
    fs.writeFileSync(cohort, '# threads in the measured cohort\njam_1\njam_2\njam_3\n\n');
    const r = runBin(repo, 'gstack-ship-receipt', ['census', '--repo', 'o/r', '--since', '2026-10-01', '--cohort', cohort], env);
    expect(r.status).toBe(EXIT.ok);
    expect(r.out).toMatch(/^CENSUS: repo=o\/r since=2026-10-01 merged_prs=6 with_receipt=5 invalid=1 unattended=2 consumed=2 runs=3 threads=3 adoption=1\/3 \(cohort\) durable=yes$/m);
    const j = runBin(repo, 'gstack-ship-receipt', ['census', '--repo', 'o/r', '--since', '2026-10-01', '--json'], env);
    expect(JSON.parse(j.out)).toMatchObject({ repo: 'o/r', adoption: '2/3 (threads seen; no cohort file)' });
    expect(runBin(repo, 'gstack-ship-receipt', ['census', '--repo', 'o/r'], env).status).toBe(EXIT.usage);
    expect(runBin(repo, 'gstack-ship-receipt', ['census', '--repo', 'o/r', '--since', 'v9.9.9'], env).status).toBe(EXIT.fail);
  });
});