@bongos/core 1.17.0

package/tests/ship_preflight.mjs

@@ -0,0 +1,368 @@
+// Tests for src/bongos/ship-preflight.js — the guards that protect /builder-ship
+// from (1) shipping uncommitted work as "complete" and (2) bailing on macOS
+// Finder/iCloud duplicate ref files.
+//
+// Run: node tests/ship_preflight.mjs
+
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { parsePorcelain, trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, closeoutPlan } = require(
+  '../modules/lifecycle/ship-preflight.js',
+);
+
+const tests = [];
+const test = (name, fn) => tests.push({ name, fn });
+
+// ---- parsePorcelain ----
+
+test('parsePorcelain: empty input → []', () => {
+  assert.deepEqual(parsePorcelain(''), []);
+  assert.deepEqual(parsePorcelain(null), []);
+});
+
+test('parsePorcelain: modified + untracked files extracted', () => {
+  const out = ' M art/pipeline/world_generator.py\n?? scripts/tile-find.js\n';
+  assert.deepEqual(parsePorcelain(out), [
+    'art/pipeline/world_generator.py',
+    'scripts/tile-find.js',
+  ]);
+});
+
+test('parsePorcelain: rename uses post-arrow path', () => {
+  const out = 'R  old/path.js -> new/path.js\n';
+  assert.deepEqual(parsePorcelain(out), ['new/path.js']);
+});
+
+test('parsePorcelain: quoted paths get unquoted', () => {
+  const out = '?? "path with spaces.txt"\n';
+  assert.deepEqual(parsePorcelain(out), ['path with spaces.txt']);
+});
+
+// ---- trackedDirty (touches[] cleanup [2/8], task 877) ----
+// Replaced dirtyTouchMatches: the guard no longer consults touches[] at all.
+// It blocks the ship whenever any TRACKED file has an uncommitted/staged change.
+
+test('trackedDirty: empty / null input → []', () => {
+  assert.deepEqual(trackedDirty(''), []);
+  assert.deepEqual(trackedDirty(null), []);
+});
+
+test('trackedDirty: untracked-only working tree → [] (no false refuse)', () => {
+  // Autonomous sessions leave scratch files around; '?? ...' lines must never
+  // block a ship.
+  const out = '?? scratch/notes.txt\n?? tmp/out.log\n';
+  assert.deepEqual(trackedDirty(out), []);
+});
+
+test('trackedDirty: modified tracked file blocks', () => {
+  const out = ' M src/bongos/db.js\n';
+  assert.deepEqual(trackedDirty(out), ['src/bongos/db.js']);
+});
+
+test('trackedDirty: staged + index-and-worktree changes block', () => {
+  const out = 'M  scripts/gds/ship.js\nMM src/bongos/routes/tasks.js\nA  migrations/099_x.sql\nD  old/gone.js\n';
+  assert.deepEqual(trackedDirty(out).sort(), [
+    'migrations/099_x.sql',
+    'old/gone.js',
+    'scripts/gds/ship.js',
+    'src/bongos/routes/tasks.js',
+  ]);
+});
+
+test('trackedDirty: rename uses the post-arrow path', () => {
+  const out = 'R  old/path.js -> new/path.js\n';
+  assert.deepEqual(trackedDirty(out), ['new/path.js']);
+});
+
+test('trackedDirty: mix of tracked-dirty + untracked → only the tracked ones', () => {
+  const out = ' M art/pipeline/world_generator.py\n?? art/pipeline/generators/ai_biome.py\n';
+  assert.deepEqual(trackedDirty(out), ['art/pipeline/world_generator.py']);
+});
+
+test('trackedDirty: strictly stronger than the old guard — blocks with no touches context', () => {
+  // The old dirtyTouchMatches returned [] when touches[] was empty, so an
+  // empty-touches task could ship uncommitted work. trackedDirty has no
+  // touches[] parameter at all: a single tracked modification blocks, period.
+  const out = ' M anything/at/all.js\n';
+  assert.equal(trackedDirty(out).length, 1, 'one tracked change is enough to refuse');
+});
+
+test('trackedDirty: quoted paths get unquoted', () => {
+  const out = ' M "path with spaces.txt"\n';
+  assert.deepEqual(trackedDirty(out), ['path with spaces.txt']);
+});
+
+// ---- classifyEmptyShip (task 1365 — close the phantom-ship hole) ----
+// ship.js calls this ONLY when the committed diff vs the grader baseline is
+// empty (nothing committed on this branch). It decides whether that empty diff
+// is the phantom-ship bug (deliverable sits uncommitted in the working tree) or
+// a legitimate no-artifact / DB-only ship the builder flagged with --allow-empty.
+
+test('classifyEmptyShip: untracked deliverable + empty diff → REFUSE (the task-1363 repro)', () => {
+  // The exact failure: a new doc was written but never `git add`-ed, ship.js was
+  // run without committing, HEAD never moved. The old guard let --skip-grade
+  // sail this through to confirm + reconciler-ship with no artifact on main.
+  const porcelain = '?? docs/audits/gds-efficiency-execution-review-2026-06-20.md\n';
+  const v = classifyEmptyShip(porcelain, { allowEmpty: false });
+  assert.equal(v.refuse, true);
+  assert.equal(v.reason, 'uncommitted-work');
+  assert.deepEqual(v.uncommitted, ['docs/audits/gds-efficiency-execution-review-2026-06-20.md']);
+});
+
+test('classifyEmptyShip: --allow-empty does NOT override a dirty/untracked tree', () => {
+  // --allow-empty asserts "there is no artifact"; a dirty tree proves there IS
+  // one, so the assertion is false → still refuse. An empty ship can't carry it.
+  const porcelain = '?? docs/audits/new.md\n M src/bongos/db.js\n';
+  const v = classifyEmptyShip(porcelain, { allowEmpty: true });
+  assert.equal(v.refuse, true);
+  assert.equal(v.reason, 'uncommitted-work');
+  assert.deepEqual(v.uncommitted.sort(), ['docs/audits/new.md', 'src/bongos/db.js']);
+});
+
+test('classifyEmptyShip: tracked-dirty + empty diff → REFUSE (uncommitted-work)', () => {
+  const v = classifyEmptyShip(' M scripts/gds/ship.js\n', { allowEmpty: false });
+  assert.equal(v.refuse, true);
+  assert.equal(v.reason, 'uncommitted-work');
+});
+
+test('classifyEmptyShip: clean tree + --allow-empty → ALLOW (DB-only / no-artifact ship)', () => {
+  const v = classifyEmptyShip('', { allowEmpty: true });
+  assert.equal(v.refuse, false);
+  assert.equal(v.reason, 'allow-empty');
+  assert.deepEqual(v.uncommitted, []);
+});
+
+test('classifyEmptyShip: clean tree + no flag → REFUSE (nothing-to-ship)', () => {
+  const v = classifyEmptyShip('', { allowEmpty: false });
+  assert.equal(v.refuse, true);
+  assert.equal(v.reason, 'nothing-to-ship');
+  assert.deepEqual(v.uncommitted, []);
+});
+
+test('classifyEmptyShip: null porcelain (git status failed) + no flag → REFUSE (nothing-to-ship)', () => {
+  // gitOk returns null on failure; treat as clean → refuse unless --allow-empty.
+  const v = classifyEmptyShip(null, {});
+  assert.equal(v.refuse, true);
+  assert.equal(v.reason, 'nothing-to-ship');
+});
+
+test('classifyEmptyShip: default opts (no second arg) → allowEmpty=false', () => {
+  const v = classifyEmptyShip('?? a.txt\n');
+  assert.equal(v.refuse, true);
+  assert.equal(v.reason, 'uncommitted-work');
+});
+
+// ---- cleanupMacFinderDupRefs ----
+
+test('cleanupMacFinderDupRefs: deletes only " 2" / " 3" suffixed ref files', () => {
+  // Spin up a throwaway git repo, plant some real refs + some Finder dups,
+  // run the cleanup, assert only the dups got removed and `git fetch` no
+  // longer fails on them.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shippref-'));
+  try {
+    execSync('git init -q', { cwd: tmp });
+    execSync('git config user.email t@t.t && git config user.name t', {
+      cwd: tmp,
+      shell: '/bin/bash',
+    });
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+
+    const refsHeads = path.join(tmp, '.git', 'refs', 'heads');
+    // Plant Finder duplicates next to the real refs. Use the actual ref
+    // contents (sha) so a curious operator wouldn't trip over them.
+    // Default branch could be 'main' or 'master' depending on git version.
+    const defaultRef = fs.existsSync(path.join(refsHeads, 'master'))
+      ? path.join(refsHeads, 'master')
+      : path.join(refsHeads, 'main');
+    const sha = fs.readFileSync(defaultRef, 'utf8').trim();
+    fs.writeFileSync(defaultRef + ' 2', sha + '\n');
+    fs.writeFileSync(path.join(refsHeads, 'feature 3'), sha + '\n');
+    // A non-numeric trailing token must NOT match (e.g. "foo bar").
+    fs.writeFileSync(path.join(refsHeads, 'real branch'), sha + '\n');
+
+    const dupName = path.basename(defaultRef) + ' 2';
+    const before = fs.readdirSync(refsHeads).sort();
+    assert.ok(before.includes(dupName));
+    assert.ok(before.includes('feature 3'));
+    assert.ok(before.includes('real branch'));
+
+    const deleted = cleanupMacFinderDupRefs(tmp);
+    assert.equal(deleted.length, 2, 'expected exactly 2 dup refs removed');
+    assert.ok(deleted.some((p) => p.endsWith(dupName)));
+    assert.ok(deleted.some((p) => p.endsWith('feature 3')));
+
+    const after = fs.readdirSync(refsHeads).sort();
+    assert.ok(!after.includes(dupName), `${dupName} should be gone`);
+    assert.ok(!after.includes('feature 3'), 'feature 3 should be gone');
+    assert.ok(after.includes('real branch'), 'real branch must survive');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('cleanupMacFinderDupRefs: noop in non-git directory returns []', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shippref-nogit-'));
+  try {
+    const deleted = cleanupMacFinderDupRefs(tmp);
+    assert.deepEqual(deleted, []);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('cleanupMacFinderDupRefs: handles linked worktrees (refs in common dir)', () => {
+  // Real-world layout: the OTB repo has linked worktrees at .claude/worktrees/.
+  // Calling cleanup from inside a linked worktree must operate on the COMMON
+  // .git/refs (parent repo), not on the per-worktree gitdir which has no
+  // refs/heads. Stale `* 2` files only ever appear in the common refs.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shippref-wt-'));
+  try {
+    execSync('git init -q', { cwd: tmp });
+    execSync('git config user.email t@t.t && git config user.name t', {
+      cwd: tmp,
+      shell: '/bin/bash',
+    });
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    execSync('git branch other', { cwd: tmp });
+
+    const wt = path.join(tmp, 'wt-linked');
+    execSync(`git worktree add -q "${wt}" other`, { cwd: tmp });
+
+    // Plant a Finder dup in the common refs.
+    const masterRef = fs.existsSync(path.join(tmp, '.git', 'refs', 'heads', 'master'))
+      ? path.join(tmp, '.git', 'refs', 'heads', 'master')
+      : path.join(tmp, '.git', 'refs', 'heads', 'main');
+    const sha = fs.readFileSync(masterRef, 'utf8').trim();
+    fs.writeFileSync(masterRef + ' 2', sha + '\n');
+
+    // Call cleanup *from inside the linked worktree*. It must reach into the
+    // common dir and delete the dup.
+    const deleted = cleanupMacFinderDupRefs(wt);
+    assert.equal(deleted.length, 1);
+    assert.ok(!fs.existsSync(masterRef + ' 2'));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ---- findMainWorktree ----
+
+test('findMainWorktree: returns the main-branch worktree path from a linked worktree', () => {
+  // Build a real repo with a linked worktree, invoke findMainWorktree from
+  // *inside* the linked worktree, expect it to return the top-level path.
+  // This is the production scenario for ship.js — it lives in a linked
+  // worktree and needs to find where `main` lives for the auto-merge.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-mainwt-'));
+  try {
+    execSync('git init -q -b main', { cwd: tmp });
+    execSync('git config user.email t@t.t && git config user.name t', {
+      cwd: tmp,
+      shell: '/bin/bash',
+    });
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    execSync('git branch feature', { cwd: tmp });
+
+    const wt = path.join(tmp, 'linked');
+    execSync(`git worktree add -q "${wt}" feature`, { cwd: tmp });
+
+    // Top-level repo is `tmp` with `main` checked out. Linked worktree has
+    // `feature` checked out. findMainWorktree called from the linked
+    // worktree should return `tmp` (the resolved real path).
+    const found = findMainWorktree(wt);
+    assert.ok(found, 'expected a path');
+    assert.equal(fs.realpathSync(found), fs.realpathSync(tmp));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('findMainWorktree: returns null when no worktree is on main', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-mainwt-none-'));
+  try {
+    execSync('git init -q -b trunk', { cwd: tmp }); // default branch is "trunk", not main
+    execSync('git config user.email t@t.t && git config user.name t', {
+      cwd: tmp,
+      shell: '/bin/bash',
+    });
+    fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    // No branch named `main` anywhere.
+    assert.equal(findMainWorktree(tmp), null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('findMainWorktree: returns null outside any git repo', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-mainwt-nogit-'));
+  try {
+    assert.equal(findMainWorktree(tmp), null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ---- closeoutPlan (task 932) ----
+
+test('closeoutPlan: clean tree → clean:true, no leftover', () => {
+  const plan = closeoutPlan('', 932);
+  assert.equal(plan.clean, true);
+  assert.deepEqual(plan.leftover, []);
+  assert.equal(plan.stashLabel, 'otb-postship-932');
+});
+
+test('closeoutPlan: null porcelain is treated as clean', () => {
+  const plan = closeoutPlan(null, 7);
+  assert.equal(plan.clean, true);
+  assert.deepEqual(plan.leftover, []);
+});
+
+test('closeoutPlan: untracked-only scratch counts as leftover (preflight lets it through)', () => {
+  // The preflight (trackedDirty) IGNORES untracked, so untracked scratch is the
+  // common post-ship leftover — closeoutPlan must still flag it for stashing.
+  const out = '?? scratch/notes.md\n?? art/tmp.png\n';
+  const plan = closeoutPlan(out, 100);
+  assert.equal(plan.clean, false);
+  assert.deepEqual(plan.leftover, ['scratch/notes.md', 'art/tmp.png']);
+  // trackedDirty would have seen these as clean — the two helpers differ on purpose.
+  assert.deepEqual(trackedDirty(out), []);
+});
+
+test('closeoutPlan: tracked + untracked mix → all paths, clean:false', () => {
+  const out = ' M scripts/gds/ship.js\n?? scratch.txt\nR  a.js -> b.js\n';
+  const plan = closeoutPlan(out, 932);
+  assert.equal(plan.clean, false);
+  assert.deepEqual(plan.leftover, ['scripts/gds/ship.js', 'scratch.txt', 'b.js']);
+});
+
+test('closeoutPlan: stashLabel embeds the task id', () => {
+  assert.equal(closeoutPlan('?? x\n', 1234).stashLabel, 'otb-postship-1234');
+});
+
+// ---- runner ----
+
+let pass = 0;
+let fail = 0;
+for (const { name, fn } of tests) {
+  try {
+    await fn();
+    console.log(`PASS  ${name}`);
+    pass++;
+  } catch (e) {
+    console.log(`FAIL  ${name}`);
+    console.log(`      ${e.message}`);
+    if (process.env.VERBOSE) console.log(e.stack);
+    fail++;
+  }
+}
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/tests/ship_premerge.mjs

@@ -0,0 +1,75 @@
+// tests/ship_premerge.mjs
+//
+// Pure-decision coverage for the #1068 pre-stage merge: ship.js merges
+// origin/main INTO the feature branch BEFORE the sandbox review gate so the
+// reviewed tree == the shipped tree (no post-approval re-stage loop). The git
+// execution is thin glue around existing helpers; the DECISION (skip vs merge,
+// branch guards) is the part worth pinning down. No git, no network.
+//
+// Run:  node tests/ship_premerge.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ship = require('../scripts/gds/ship.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+t('decidePreMerge: skip on main / HEAD / empty branch', () => {
+  assert.equal(ship.decidePreMerge({ branch: 'main', behind: 9 }).action, 'skip');
+  assert.equal(ship.decidePreMerge({ branch: 'HEAD', behind: 9 }).action, 'skip');
+  assert.equal(ship.decidePreMerge({ branch: null, behind: 9 }).action, 'skip');
+  assert.equal(ship.decidePreMerge({ branch: '', behind: 9 }).action, 'skip');
+});
+
+t('decidePreMerge: skip when already current (behind 0 / NaN)', () => {
+  assert.equal(ship.decidePreMerge({ branch: 'claude/feat', behind: 0 }).action, 'skip');
+  assert.equal(ship.decidePreMerge({ branch: 'claude/feat', behind: NaN }).action, 'skip');
+  assert.match(ship.decidePreMerge({ branch: 'claude/feat', behind: 0 }).reason, /up to date/);
+});
+
+t('decidePreMerge: merge when a feature branch is behind origin/main', () => {
+  const d = ship.decidePreMerge({ branch: 'claude/t1068-x', behind: 9 });
+  assert.equal(d.action, 'merge');
+  assert.match(d.reason, /9 commit\(s\) behind/);
+});
+
+t('decidePreMerge: single commit behind still merges', () => {
+  assert.equal(ship.decidePreMerge({ branch: 'claude/feat', behind: 1 }).action, 'merge');
+});
+
+// idea #364: a credential-less partial-clone dev box (pushVia 'server') cannot run
+// the local `git merge origin/main` (no creds to lazily fetch main's blobs) and
+// does not need to — the server reconciles with main at publish time (ADR 0055).
+// So the server path SKIPS the pre-merge regardless of how far behind it is, while
+// the laptop path ('local'/undefined) is unchanged.
+t('decidePreMerge: skip on the server-publish path even when behind', () => {
+  const d = ship.decidePreMerge({ branch: 'claude/feat', behind: 9, via: 'server' });
+  assert.equal(d.action, 'skip');
+  assert.match(d.reason, /server-mediated|server-side|idea #364/);
+});
+
+t('decidePreMerge: explicit local path still merges when behind', () => {
+  assert.equal(ship.decidePreMerge({ branch: 'claude/feat', behind: 3, via: 'local' }).action, 'merge');
+});
+
+t('decidePreMerge: undefined via preserves the original laptop behavior', () => {
+  assert.equal(ship.decidePreMerge({ branch: 'claude/feat', behind: 3 }).action, 'merge');
+  assert.equal(ship.decidePreMerge({ branch: 'claude/feat', behind: 0 }).action, 'skip');
+});
+
+t('decidePreMerge: non-feature-branch guard wins over via=server', () => {
+  // branch guard is evaluated first; action is skip either way but the reason
+  // should be the branch reason, not the server-path reason.
+  const d = ship.decidePreMerge({ branch: 'main', behind: 9, via: 'server' });
+  assert.equal(d.action, 'skip');
+  assert.match(d.reason, /feature branch/);
+});
+
+console.log(`\nship_premerge: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/ship_resume.mjs

@@ -0,0 +1,129 @@
+// tests/ship_resume.mjs
+//
+// Unit tests for task 941 (V4.R03 — idempotent ship re-drive): a CLAIM-LESS
+// `node scripts/gds/ship.js <id>` re-run resumes from the leg it stalled on
+// instead of dead-ending at "you don't have an active claim".
+//
+// The claim is consumed at the resolve step, so a ship that fails AFTER it
+// strands the task with no claim:
+//   - grade fail   → task stuck at `completed`  → re-run should RE-GRADE
+//   - merge/deploy fail → task stuck at `confirmed` → re-run should RE-MERGE
+//     (the exact task-1027 dev-box nightmare)
+// evaluateResumeAction is the pure decision behind that routing. We prove the
+// full truth table here — no git, no network.
+//
+// Run:  node tests/ship_resume.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ship = require('../scripts/gds/ship.js');
+const { evaluateResumeAction } = ship;
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+
+const OWNER = { id: 7, rank: 'metic' };
+const ARCHON = { id: 1, rank: 'archon' };
+const STRANGER = { id: 99, rank: 'metic' };
+const claimBy = (bid) => ({ builder_id: bid, github_login: `b${bid}` });
+
+// ---- completed (grade stalled) → resume-grade for owner/archon ----
+
+test('completed + owner → resume-grade (via owner)', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'completed' }, lastClaim: claimBy(7), builder: OWNER });
+  assert.equal(a.action, 'resume-grade');
+  assert.equal(a.via, 'owner');
+});
+
+test('completed + archon (not owner) → resume-grade (via archon)', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'completed' }, lastClaim: claimBy(7), builder: ARCHON });
+  assert.equal(a.action, 'resume-grade');
+  assert.equal(a.via, 'archon');
+});
+
+test('completed + stranger → error (not owner)', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'completed' }, lastClaim: claimBy(7), builder: STRANGER });
+  assert.equal(a.action, 'error');
+  assert.match(a.reason, /last claimed by @b7/);
+  assert.match(a.reason, /resume the grade/);
+});
+
+// ---- confirmed (merge/deploy stalled — the #1027 case) → resume-merge ----
+
+test('confirmed + owner → resume-merge (the task-1027 fix)', () => {
+  const a = evaluateResumeAction({ task: { id: 1027, status: 'confirmed' }, lastClaim: claimBy(7), builder: OWNER });
+  assert.equal(a.action, 'resume-merge');
+  assert.equal(a.via, 'owner');
+});
+
+test('confirmed + archon → resume-merge (via archon)', () => {
+  const a = evaluateResumeAction({ task: { id: 1027, status: 'confirmed' }, lastClaim: claimBy(7), builder: ARCHON });
+  assert.equal(a.action, 'resume-merge');
+  assert.equal(a.via, 'archon');
+});
+
+test('confirmed + stranger → error (mentions merge, not grade)', () => {
+  const a = evaluateResumeAction({ task: { id: 1027, status: 'confirmed' }, lastClaim: claimBy(7), builder: STRANGER });
+  assert.equal(a.action, 'error');
+  assert.match(a.reason, /resume the merge/);
+});
+
+// ---- terminal / not-resumable states ----
+
+test('shipped → done (idempotent no-op)', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'shipped' }, lastClaim: claimBy(7), builder: OWNER });
+  assert.equal(a.action, 'done');
+});
+
+test('active (claimed elsewhere) → claim-first with release hint', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'active' }, lastClaim: claimBy(7), builder: OWNER });
+  assert.equal(a.action, 'claim-first');
+  assert.match(a.reason, /release\.js 5 --force/);
+});
+
+test('ready → claim-first with claim hint', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'ready' }, lastClaim: null, builder: OWNER });
+  assert.equal(a.action, 'claim-first');
+  assert.match(a.reason, /claim\.js 5/);
+});
+
+test('backlog → claim-first', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'backlog' }, lastClaim: null, builder: OWNER });
+  assert.equal(a.action, 'claim-first');
+});
+
+test('abandoned → error (nothing to resume)', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'abandoned' }, lastClaim: claimBy(7), builder: OWNER });
+  assert.equal(a.action, 'error');
+});
+
+test('missing task → error', () => {
+  const a = evaluateResumeAction({ task: null, lastClaim: null, builder: OWNER });
+  assert.equal(a.action, 'error');
+  assert.match(a.reason, /not found/i);
+});
+
+// ---- ownership edge: owner inferred by id even when rank is low ----
+
+test('completed + owner with low rank still resumes (ownership, not rank)', () => {
+  const a = evaluateResumeAction({ task: { id: 5, status: 'completed' }, lastClaim: claimBy(99), builder: { id: 99, rank: 'xenos' } });
+  assert.equal(a.action, 'resume-grade');
+  assert.equal(a.via, 'owner');
+});
+
+console.log('');
+console.log(`ship_resume: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/ship_upload_skip.mjs

@@ -0,0 +1,89 @@
+// tests/ship_upload_skip.mjs
+//
+// Unit tests for the session-upload skip logging (#617, ADR 0027 / BFG 6D).
+// Reconciling the corpus (#608) showed uploadSessionOnShip skips SILENTLY in
+// many ship contexts (no session id, no transcript, 401, swallowed error), so
+// missed captures were invisible. classifyUploadSkip + recordUploadSkip make
+// every skip emit a clear reason AND a durable, auditable trace.
+//
+// Run:  node tests/ship_upload_skip.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ship = require('../scripts/gds/ship.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+
+// ---- classifyUploadSkip (pure) ----
+
+test('classifyUploadSkip: missing session id → skip, no_session_id, names the consequence', () => {
+  const v = ship.classifyUploadSkip({ sessionId: null, sessionIdSafe: false, transcriptPath: null, pathsTried: [] });
+  assert.equal(v.skip, true);
+  assert.equal(v.code, 'no_session_id');
+  assert.match(v.reason, /CLAUDE_CODE_SESSION_ID is not set/);
+  assert.match(v.reason, /NOT appear in the BFG session corpus/);
+});
+
+test('classifyUploadSkip: unsafe session id → skip, unsafe_session_id', () => {
+  const v = ship.classifyUploadSkip({ sessionId: '../etc', sessionIdSafe: false, transcriptPath: null, pathsTried: [] });
+  assert.equal(v.skip, true);
+  assert.equal(v.code, 'unsafe_session_id');
+  assert.match(v.reason, /not a plain token/);
+});
+
+test('classifyUploadSkip: transcript not found → skip + reports the exact paths it looked in', () => {
+  const tried = ['/home/u/.claude/projects/-a/sid.jsonl', '/home/u/.claude/projects/-b/sid.jsonl'];
+  const v = ship.classifyUploadSkip({ sessionId: 'sid', sessionIdSafe: true, transcriptPath: null, pathsTried: tried });
+  assert.equal(v.skip, true);
+  assert.equal(v.code, 'transcript_not_found');
+  assert.match(v.reason, /Looked in:/);
+  assert.ok(v.reason.includes(tried[0]) && v.reason.includes(tried[1]), 'reason should list both tried paths');
+});
+
+test('classifyUploadSkip: all preconditions satisfied → no skip', () => {
+  const v = ship.classifyUploadSkip({ sessionId: 'sid', sessionIdSafe: true, transcriptPath: '/x/sid.jsonl', pathsTried: [] });
+  assert.equal(v.skip, false);
+});
+
+// ---- recordUploadSkip (durable, auditable trace) ----
+
+test('recordUploadSkip: appends a structured jsonl row to the trace file', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-skip-'));
+  try {
+    const file = ship.recordUploadSkip(617, { code: 'no_session_id', reason: 'because reasons.' }, { dir });
+    assert.equal(file, path.join(dir, 'session-upload-skips.jsonl'));
+    const lines = fs.readFileSync(file, 'utf8').trim().split('\n');
+    assert.equal(lines.length, 1);
+    const row = JSON.parse(lines[0]);
+    assert.equal(row.task_id, 617);
+    assert.equal(row.code, 'no_session_id');
+    assert.match(row.reason, /because reasons/);
+    assert.ok(typeof row.ts === 'string' && row.ts.length > 0, 'row carries a timestamp');
+    // a second skip appends, never truncates — the trace is a running ledger
+    ship.recordUploadSkip(null, { code: 'http_500', reason: 'server sad.' }, { dir });
+    assert.equal(fs.readFileSync(file, 'utf8').trim().split('\n').length, 2);
+    assert.equal(JSON.parse(fs.readFileSync(file, 'utf8').trim().split('\n')[1]).task_id, null);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+console.log(`\nSession upload-skip logging (#617) tests: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);