@bongos/core 1.19.1032 → 1.19.1034

package/tests/ship_land_red_pr.mjs

@@ -0,0 +1,236 @@
+// tests/ship_land_red_pr.mjs — a stalled land names its red check (task 1003764, gap 2).
+//
+// WHY. Task 1003747's ship sat at "waiting for auto-merge + prod deploy" while a
+// required check was red, and ended on "This is NOT a failure". The cause — CI tests
+// the branch MERGED with main, and main had moved six commits, staling the copy
+// registry in the merged tree only — took ~20 minutes of git archaeology to find,
+// though it was one API call away. The laptop poll (pollCiDeploy) never looked at
+// checks at all; the server poll named them but not the merge trap, and not how a
+// freshness gate heals. These drive both polls with fake gh / server reads (no
+// network, no sleeping) and pin the pure pieces they are built from.
+//
+// Run:  node tests/ship_land_red_pr.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import {
+  FRESHNESS_TESTS, failingTestNames, landPendingLines, localMergeDriver, mergeTrapLines,
+  pollCiDeploy, pollServerPublish, redBlocksMerge, redPrLines, unitReportFor,
+} from '../scripts/gds/ship-land.js';
+
+const require = createRequire(import.meta.url);
+const githubPush = require('../modules/lifecycle/github-push.js');
+const { CARDS } = require('../scripts/gds/plain-cards.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// Run fn with console.log captured; returns { result, out }.
+async function capture(fn) {
+  const lines = [];
+  const orig = console.log;
+  console.log = (...a) => { lines.push(a.join(' ')); };
+  try { return { result: await fn(), out: lines.join('\n'), lines }; }
+  finally { console.log = orig; }
+}
+
+const SHA = 'a'.repeat(40);
+// What `gh pr view --json state,mergeCommit,mergeStateStatus,headRefOid,statusCheckRollup`
+// really returns (shape taken from a live PR on this repo): check runs, then statuses.
+const run = (name, conclusion, status = 'COMPLETED') => ({ __typename: 'CheckRun', name, conclusion, status, workflowName: 'unit' });
+const ctx = (context, state) => ({ __typename: 'StatusContext', context, state, targetUrl: '' });
+const openPr = (rollup, mergeStateStatus = 'BLOCKED') => ({ state: 'OPEN', mergeCommit: null, mergeStateStatus, headRefOid: SHA, statusCheckRollup: rollup });
+const RED_ROLLUP = [run('unit', 'FAILURE'), run('report', 'SUCCESS'), ctx('gate-author-trust', 'SUCCESS'), ctx('unit-report', 'FAILURE')];
+const COMBINED_STATUS = { state: 'failure', statuses: [
+  { context: 'gate-author-trust', state: 'success', description: 'Metic+ author' },
+  { context: 'unit-report', state: 'failure', description: '1 failed: fitness' },
+] };
+
+// ---- localMergeDriver: the laptop's view of a red PR, in publish-status's shape ----
+
+await test('localMergeDriver names the failing required check and asks for the tests once the report is posted', async () => {
+  const asked = [];
+  const md = localMergeDriver(openPr(RED_ROLLUP), (sha) => { asked.push(sha); return '1 failed: fitness'; });
+  assert.deepEqual(md, { reason: 'failing_check:unit', failing_tests: '1 failed: fitness' });
+  assert.deepEqual(asked, [SHA], 'the unit-report is read for the PR head sha');
+});
+
+await test('localMergeDriver does not ask for tests before the unit-report status exists', async () => {
+  let asked = 0;
+  const md = localMergeDriver(openPr([run('unit', 'FAILURE')]), () => { asked++; return 'x'; });
+  assert.deepEqual(md, { reason: 'failing_check:unit', failing_tests: null });
+  assert.equal(asked, 0);
+});
+
+await test('localMergeDriver: pending, expected and in-progress are waiting, not red', async () => {
+  for (const rollup of [
+    [run('unit', '', 'IN_PROGRESS')],
+    [ctx('unit-report', 'PENDING')],
+    [ctx('some-required-status', 'EXPECTED')],
+    [run('unit', 'SUCCESS'), run('lint', 'NEUTRAL'), run('docs', 'SKIPPED'), ctx('unit-report', 'SUCCESS')],
+  ]) assert.equal(localMergeDriver(openPr(rollup)), null, JSON.stringify(rollup));
+});
+
+await test('localMergeDriver: an UNSTABLE PR means the failing check is optional', async () => {
+  assert.equal(localMergeDriver(openPr([run('lint', 'FAILURE')], 'UNSTABLE')).reason, 'non_required_check_failing:lint');
+});
+
+await test('localMergeDriver: nothing to say for a merged/closed PR, or a gh that returned no rollup', async () => {
+  assert.equal(localMergeDriver(null), null);
+  assert.equal(localMergeDriver({ ...openPr(RED_ROLLUP), state: 'MERGED' }), null);
+  assert.equal(localMergeDriver({ state: 'OPEN', mergeCommit: null }), null, 'the legacy two-field read has no rollup');
+});
+
+await test('localMergeDriver agrees with the server\'s mergeBlockReason on a red required check', async () => {
+  const server = githubPush.mergeBlockReason({
+    merged: false, pr_state: 'open', mergeable: 'MERGEABLE', merge_state: 'BLOCKED', review_decision: null,
+    rollup_state: 'FAILURE', checks: [{ name: 'unit', conclusion: 'FAILURE', status: 'COMPLETED' }], checks_unreadable: false,
+  });
+  assert.equal(localMergeDriver(openPr([run('unit', 'FAILURE')])).reason, server);
+});
+
+// ---- unitReportFor: the failing-test line, via the same parser the server uses ----
+
+await test('unitReportFor reads the unit-report status for the sha', async () => {
+  const calls = [];
+  const text = unitReportFor(SHA, (args) => { calls.push(args); return COMBINED_STATUS; });
+  assert.equal(text, '1 failed: fitness');
+  assert.deepEqual(calls, [['api', `repos/{owner}/{repo}/commits/${SHA}/status`]]);
+});
+
+await test('unitReportFor: a green report, an unreadable one, or a bad sha → null (and a bad sha never reaches gh)', async () => {
+  assert.equal(unitReportFor(SHA, () => ({ statuses: [{ context: 'unit-report', state: 'success', description: 'all unit tests passed' }] })), null);
+  assert.equal(unitReportFor(SHA, () => null), null);
+  assert.equal(unitReportFor('HEAD; rm -rf /', () => { throw new Error('must not call gh'); }), null);
+});
+
+// ---- the merge trap + the freshness heal ----
+
+await test('failingTestNames parses the unit-report line and drops a name the status limit cut', async () => {
+  assert.deepEqual(failingTestNames('1 failed: fitness'), ['fitness']);
+  assert.deepEqual(failingTestNames('3 failed: api_docs, fitness, security'), ['api_docs', 'fitness', 'security']);
+  assert.deepEqual(failingTestNames('40 failed: a_test, b_test, some_lo…'), ['a_test', 'b_test']);
+  assert.deepEqual(failingTestNames(null), []);
+  assert.deepEqual(failingTestNames('all unit tests passed'), []);
+});
+
+await test('every name in FRESHNESS_TESTS is a real test file', async () => {
+  for (const name of FRESHNESS_TESTS) {
+    assert.ok(fs.existsSync(new URL(`./${name}.mjs`, import.meta.url)), `tests/${name}.mjs does not exist`);
+  }
+});
+
+await test('every red PR names the trap: CI tests the MERGE, not the branch', async () => {
+  const local = mergeTrapLines({ reason: 'failing_check:unit' }, { taskId: 42, via: 'local' }).join('\n');
+  assert.match(local, /MERGED with the current main, not the branch alone/);
+  assert.match(local, /git fetch origin && git merge origin\/main/, 'the laptop can reproduce on the merge');
+  const server = mergeTrapLines({ reason: 'failing_check:unit' }, { taskId: 42, via: 'server' }).join('\n');
+  assert.match(server, /MERGED with the current main/);
+  assert.ok(!/git merge origin\/main/.test(server), 'a credential-less machine cannot merge main locally — never tell it to');
+});
+
+await test('a failing freshness gate gets its healing command, per push path', async () => {
+  const md = { reason: 'failing_check:unit-report', failing_tests: '1 failed: fitness' };
+  const local = mergeTrapLines(md, { taskId: 42, via: 'local' }).join('\n');
+  assert.match(local, /`fitness` is a freshness gate/);
+  assert.match(local, /stale in the MERGED tree/);
+  assert.match(local, /node scripts\/gds\/ship\.js 42/, 'names the re-ship for THIS task');
+  assert.match(local, /ship-check\.js/);
+  const server = mergeTrapLines(md, { taskId: 42, via: 'server' }).join('\n');
+  assert.match(server, /The server regenerates stale generated files/);
+  const plain = mergeTrapLines({ reason: 'failing_check:unit-report', failing_tests: '1 failed: security' }, { taskId: 42 }).join('\n');
+  assert.ok(!/freshness gate/.test(plain), 'an ordinary failing test gets no regenerate advice');
+});
+
+await test('redPrLines: the red line first, then the trap, then the plain-words card', async () => {
+  const lines = redPrLines({ reason: 'failing_check:unit-report', failing_tests: '1 failed: fitness' }, { taskId: 42, via: 'local' });
+  assert.match(lines[0], /the PR is RED — 1 failed: fitness/);
+  assert.match(lines[1], /MERGED with the current main/);
+  const at = lines.findIndex((l) => l.includes('[otb-plain]'));
+  assert.ok(at > 2, 'the card still follows');
+  assert.ok(lines.slice(at).join('\n').includes(CARDS.failing_check.happened));
+  assert.deepEqual(redPrLines({ reason: 'review_required' }), [], 'nothing red → nothing printed');
+});
+
+await test('redBlocksMerge: only a failing REQUIRED check stops the merge', async () => {
+  assert.equal(redBlocksMerge({ reason: 'failing_check:unit' }), true);
+  assert.equal(redBlocksMerge({ reason: 'failing_check_unreadable' }), true);
+  assert.equal(redBlocksMerge({ reason: 'non_required_check_failing:lint' }), false, 'GitHub still merges an UNSTABLE PR');
+  assert.equal(redBlocksMerge(null), false);
+});
+
+await test('landPendingLines: a RED PR never gets "NOT a failure"; a green-but-slow one keeps it', async () => {
+  const red = landPendingLines(42, { red: true }).join('\n');
+  assert.ok(!/NOT a failure/.test(red), 'a failing required check does not pass by waiting');
+  assert.match(red, /RED/);
+  assert.match(red, /node scripts\/gds\/ship\.js 42/);
+  assert.match(landPendingLines(42).join('\n'), /This is NOT a failure/);
+});
+
+// ---- the two poll loops, end to end with fakes ----
+
+await test('pollCiDeploy (laptop): a red PR is named once, the trap and heal are printed, and the banner is red', async () => {
+  const seen = { prView: 0, status: 0 };
+  const gh = (args) => {
+    if (args[0] === 'pr' && args[1] === 'view') { seen.prView++; return openPr(RED_ROLLUP); }
+    if (args[0] === 'api') { seen.status++; return COMBINED_STATUS; }
+    throw new Error(`unexpected gh call: ${args.join(' ')}`);
+  };
+  const { result, out } = await capture(() => pollCiDeploy(42, 'task-42', SHA, { ghJson: gh, pause: () => {} }));
+  assert.equal(result.pending, true, 'still a pending land — the check can yet pass');
+  assert.equal(seen.prView, 30, 'polled the whole window');
+  assert.equal(seen.status, 1, 'the unit-report is read once per head sha, not once per poll');
+  assert.equal(out.split('the PR is RED — 1 failed: fitness').length - 1, 1, 'named once, not thirty times');
+  assert.match(out, /MERGED with the current main/);
+  assert.match(out, /`fitness` is a freshness gate/);
+  assert.match(out, /node scripts\/gds\/ship\.js 42/);
+  assert.ok(!/This is NOT a failure/.test(out), 'the closing banner must not contradict the red line');
+  assert.ok(!out.includes(CARDS.land_pending.happened), 'nor the "nothing to do" card');
+});
+
+await test('pollCiDeploy: a gh that rejects the new fields falls back to the old read and still sees the merge', async () => {
+  const gh = (args) => {
+    if (args[0] === 'pr' && args.includes('state,mergeCommit')) return { state: 'MERGED', mergeCommit: { oid: 'b'.repeat(40) } };
+    if (args[0] === 'pr') return null; // unknown JSON field → gh exits non-zero → ghJson null
+    if (args[0] === 'run') return [];
+    throw new Error(`unexpected gh call: ${args.join(' ')}`);
+  };
+  const { result, out } = await capture(() => pollCiDeploy(42, 'task-42', SHA, { ghJson: gh, pause: () => {} }));
+  assert.match(out, /merged to main \(bbbbbbbb\)/);
+  assert.equal(result.pending, true);
+});
+
+await test('pollCiDeploy: a green PR that is merely slow keeps the reassuring banner', async () => {
+  const gh = (args) => (args[0] === 'pr' ? openPr([run('unit', '', 'IN_PROGRESS')]) : null);
+  const { out } = await capture(() => pollCiDeploy(42, 'task-42', SHA, { ghJson: gh, pause: () => {} }));
+  assert.ok(!/RED/.test(out));
+  assert.match(out, /This is NOT a failure/);
+});
+
+await test('pollServerPublish (credential-less): a failing status read is said once; a red PR gets the server-path heal', async () => {
+  let n = 0;
+  const readStatus = async () => {
+    n++;
+    if (n <= 3) return { ok: false, status: 502, data: { error: { code: 'status_failed', message: 'x' } } };
+    return { ok: true, status: 200, data: {
+      pr_state: 'open', merged: false, deploy_status: 'pending', reconcile_blocked: null,
+      merge_driver: { reason: 'failing_check:unit-report', failing_tests: '1 failed: fitness' },
+    } };
+  };
+  const { result, out } = await capture(() => pollServerPublish(42, 'task-42', { readStatus, pause: () => {} }));
+  assert.equal(result.pending, true);
+  assert.equal(out.split('could not read the land status from the server (HTTP 502 status_failed)').length - 1, 1,
+    'three identical failures are reported once');
+  assert.equal(out.split('the PR is RED — 1 failed: fitness').length - 1, 1);
+  assert.match(out, /The server regenerates stale generated files/);
+  assert.ok(!/git merge origin\/main/.test(out), 'never tells a credential-less machine to merge main');
+  assert.ok(!/This is NOT a failure/.test(out));
+});
+
+console.log(`\nship-land red PR (task 1003764) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;

package/tests/ship_preflight.mjs

@@ -12,9 +12,12 @@ 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 {
+  parsePorcelain, trackedDirty, classifyEmptyShip, cleanupMacFinderDupRefs, findMainWorktree, closeoutPlan,
+  untrackedPaths, untrackedLeftBehind, untrackedWarningLines,
+} = require('../modules/lifecycle/ship-preflight.js');
+// task 1001436: the preflight step itself + the ship-input resolver it is handed.
+const { preflight, shipInputPaths, staleToolingFiles, TOOLING_PATHSPECS } = require('../scripts/gds/ship-preflight-steps.js');
 
 const tests = [];
 const test = (name, fn) => tests.push({ name, fn });
@@ -352,6 +355,226 @@ test('closeoutPlan: stashLabel embeds the task id', () => {
   assert.equal(closeoutPlan('?? x\n', 1234).stashLabel, 'otb-postship-1234');
 });
 
+// ---- the residual phantom ship: untracked files left behind (task 1001436) ----
+// A branch with REAL committed work ships; a new file beside it that was never
+// `git add`ed silently does not. The preflight now names those files — a warning,
+// never a refusal (trackedDirty must keep ignoring scratch).
+
+test('untrackedPaths: only ?? lines, in order, unquoted; tracked changes are not listed', () => {
+  const out = ' M src/a.js\n?? tests/new_case.mjs\nA  src/b.js\n?? "docs/with space.md"\n';
+  assert.deepEqual(untrackedPaths(out), ['tests/new_case.mjs', 'docs/with space.md']);
+  assert.deepEqual(untrackedPaths(''), []);
+  assert.deepEqual(untrackedPaths(null), []);
+});
+
+test('untrackedLeftBehind: nothing committed → [] (the empty-diff guard already refuses and lists them)', () => {
+  const out = '?? tests/new_case.mjs\n';
+  assert.deepEqual(untrackedLeftBehind(out, { committedFileCount: 0 }), []);
+  assert.deepEqual(untrackedLeftBehind(out), [], 'default opts behave as "nothing committed"');
+  // ...and that empty case is exactly the one classifyEmptyShip refuses on:
+  assert.equal(classifyEmptyShip(out).reason, 'uncommitted-work');
+});
+
+test('untrackedLeftBehind: committed work + an untracked file → that file is named', () => {
+  const out = ' M src/unrelated.js\n?? tests/new_case.mjs\n?? docs/adr/0999-x.md\n';
+  assert.deepEqual(untrackedLeftBehind(out, { committedFileCount: 3 }), ['tests/new_case.mjs', 'docs/adr/0999-x.md']);
+});
+
+test('untrackedLeftBehind: the ship\'s own input files are excluded, whatever their spelling', () => {
+  const out = '?? notes.md\n?? summary.txt\n?? shots/after.png\n?? tests/new_case.mjs\n';
+  const inputs = ['./notes.md', 'summary.txt', 'shots\\after.png'];
+  assert.deepEqual(untrackedLeftBehind(out, { committedFileCount: 1, inputs }), ['tests/new_case.mjs']);
+});
+
+test('untrackedWarningLines: [] when there is nothing to say', () => {
+  assert.deepEqual(untrackedWarningLines([]), []);
+  assert.deepEqual(untrackedWarningLines(null), []);
+});
+
+test('untrackedWarningLines: names the count, the task, each file, and says it does not block', () => {
+  const text = untrackedWarningLines(['tests/new_case.mjs', 'docs/x.md'], { taskId: 1001436 }).join('\n');
+  assert.match(text, /2 untracked file\(s\) in this worktree will NOT ship with task 1001436/);
+  assert.match(text, /- tests\/new_case\.mjs/);
+  assert.match(text, /- docs\/x\.md/);
+  assert.match(text, /Warning only — not blocking; the ship proceeds/);
+});
+
+test('untrackedWarningLines: a long list is capped, with the remainder counted', () => {
+  const files = Array.from({ length: 17 }, (_, i) => `scratch/f${i}.txt`);
+  const lines = untrackedWarningLines(files, { cap: 15 });
+  assert.equal(lines.filter((l) => l.startsWith('    - ')).length, 15);
+  assert.ok(lines.includes('    … and 2 more'));
+  assert.match(lines.join('\n'), /17 untracked file\(s\)/);
+});
+
+test('shipInputPaths: prose/visual flags resolve to repo-relative paths; stdin and out-of-tree paths add nothing', () => {
+  const root = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shipinputs-')));
+  const outside = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shipinputs-out-')));
+  try {
+    fs.mkdirSync(path.join(root, 'sub'));
+    for (const f of ['notes.md', 'summary.txt', 'sub/shot.png', 'resp.md']) fs.writeFileSync(path.join(root, f), 'x');
+    fs.writeFileSync(path.join(outside, 'notes.md'), 'x');
+    const args = [
+      '1001436', '--notes-file', 'notes.md', '--summary-file=summary.txt',
+      '--visual', path.join(root, 'sub', 'shot.png'), '--response-file', '-',
+    ];
+    assert.deepEqual(shipInputPaths(args, { cwd: root, repoRoot: root }), ['notes.md', 'summary.txt', 'sub/shot.png']);
+    // Run from a subdirectory: the relative flag value resolves against cwd, the result against the root.
+    assert.deepEqual(shipInputPaths(['1', '--response-file', '../resp.md'], { cwd: path.join(root, 'sub'), repoRoot: root }), ['resp.md']);
+    // A file outside the checkout cannot be an untracked file in it.
+    assert.deepEqual(shipInputPaths(['1', '--notes-file', path.join(outside, 'notes.md')], { cwd: root, repoRoot: root }), []);
+    // A flag with no value (last token) is ignored rather than resolved to the root.
+    assert.deepEqual(shipInputPaths(['1', '--notes-file'], { cwd: root, repoRoot: root }), []);
+    assert.deepEqual(shipInputPaths([], { cwd: root, repoRoot: root }), []);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(outside, { recursive: true, force: true });
+  }
+});
+
+// The behaviour, not just the helpers: run the REAL preflight() in a throwaway
+// repo with a local "origin", and read what it prints. Two worlds: a branch
+// carrying committed work (the warning must fire, minus inputs and ignored
+// files), and a branch with nothing committed (it must stay silent — the
+// empty-diff guard owns that case).
+function withPreflightRepo(fn) {
+  const tmp = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'otb-untracked-')));
+  const origin = path.join(tmp, 'origin.git');
+  const work = path.join(tmp, 'work');
+  const run = (cmd, cwd = work) => execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  const prevCwd = process.cwd();
+  try {
+    execSync(`git init -q --bare -b main "${origin}"`);
+    execSync(`git clone -q "${origin}" "${work}"`, { stdio: ['ignore', 'pipe', 'pipe'] });
+    run('git config user.email t@t.t && git config user.name t && git config commit.gpgsign false');
+    run('git checkout -q -b main');
+    fs.writeFileSync(path.join(work, '.gitignore'), '*.log\n');
+    fs.writeFileSync(path.join(work, 'a.txt'), 'x');
+    run('git add -A && git commit -q -m init && git push -q origin main');
+    process.chdir(work);
+    return fn({ work, run });
+  } finally {
+    process.chdir(prevCwd);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function capturePreflight(claim, opts) {
+  const out = [];
+  const err = [];
+  const log = console.log;
+  const error = console.error;
+  console.log = (...a) => out.push(a.join(' '));
+  console.error = (...a) => err.push(a.join(' '));
+  try {
+    return { result: preflight(claim, opts), out: out.join('\n'), err: err.join('\n') };
+  } finally {
+    console.log = log;
+    console.error = error;
+  }
+}
+
+test('preflight (real git): committed work + a forgotten new file → warns, still OK, inputs + ignored files unlisted', () => {
+  withPreflightRepo(({ work, run }) => {
+    run('git checkout -q -b feature');
+    fs.mkdirSync(path.join(work, 'src'));
+    fs.writeFileSync(path.join(work, 'src', 'fix.js'), 'module.exports = 1;\n');
+    run('git add src/fix.js && git commit -q -m "the committed half"');
+    fs.mkdirSync(path.join(work, 'tests'));
+    fs.writeFileSync(path.join(work, 'tests', 'forgot.mjs'), '// never git-added\n');
+    fs.writeFileSync(path.join(work, 'notes.md'), 'handoff notes\n');
+    fs.writeFileSync(path.join(work, 'debug.log'), 'ignored by .gitignore\n');
+
+    const { result, out, err } = capturePreflight({ task_id: 4242, head_sha: null }, { inputFiles: ['notes.md'] });
+    assert.equal(result.ok, true, 'a warning must never refuse the ship');
+    // A wholly-untracked directory is still named file by file (--untracked-files=all).
+    assert.deepEqual(result.untrackedLeftBehind, ['tests/forgot.mjs']);
+    assert.match(err, /1 untracked file\(s\) in this worktree will NOT ship with task 4242/);
+    assert.match(err, /- tests\/forgot\.mjs/);
+    assert.doesNotMatch(err, /notes\.md/, 'the ship\'s own --notes-file is not a deliverable');
+    assert.doesNotMatch(err, /debug\.log/, 'an ignored file is never listed');
+    assert.match(out, /preflight: tracked files clean \(1 untracked file\(s\) will not ship/);
+  });
+});
+
+test('preflight (real git): nothing committed on the branch → no untracked warning', () => {
+  withPreflightRepo(({ work, run }) => {
+    run('git checkout -q -b feature');
+    fs.writeFileSync(path.join(work, 'forgot.md'), 'never git-added\n');
+    const { result, out, err } = capturePreflight({ task_id: 4243, head_sha: null }, {});
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.untrackedLeftBehind, []);
+    assert.doesNotMatch(err, /Untracked-file warning/);
+    assert.match(out, /preflight: working tree clean/);
+  });
+});
+
+// ---- stale ship-tooling guard (task 1004273) ----
+// The guard named ship.js + grader.js only; two carves moved the logic into ship-*.js
+// and grader-*.js / grader-workers/ / grade-engine.js, so a branch behind main on any
+// of those shipped with a stale copy — the #662 shape the guard exists for.
+
+test('stale-tooling guard: every tracked ship*.js and grader file is covered by TOOLING_PATHSPECS', () => {
+  const root = path.resolve(import.meta.dirname, '..');
+  const ls = (...spec) => execSync(`git ls-files -z -- ${spec.map((s) => `'${s}'`).join(' ')}`, { cwd: root, encoding: 'utf8' })
+    .split('\0').filter(Boolean);
+  // Chosen by an independent rule (the filename), then asked of git's own pathspec matcher.
+  const shipTooling = ls('scripts/gds', 'modules/grading').filter((f) =>
+    /^scripts\/gds\/ship[^/]*\.js$/.test(f) || /^modules\/grading\/(?:grader|grade-engine)/.test(f));
+  assert.ok(shipTooling.length >= 25, `only ${shipTooling.length} ship/grader file(s) found — the scan is reading the wrong tree`);
+  assert.ok(shipTooling.includes('scripts/gds/ship-land.js') && shipTooling.includes('modules/grading/grader-score.js'));
+  const covered = new Set(ls(...TOOLING_PATHSPECS));
+  const missed = shipTooling.filter((f) => !covered.has(f));
+  assert.deepEqual(missed, [], `ship/grade tooling the stale-tooling guard would not refuse: ${missed.join(', ')}`);
+});
+
+// Publish the throwaway repo's main to its local bare "origin".
+const publishMain = (run) => run(['git', 'push', '-q', 'origin', 'main'].join(' '));
+
+test('preflight (real git): main moved a carved ship-*.js and added a new grader file → refused stale-tooling', () => {
+  withPreflightRepo(({ work, run }) => {
+    fs.mkdirSync(path.join(work, 'scripts', 'gds'), { recursive: true });
+    fs.mkdirSync(path.join(work, 'modules', 'grading'), { recursive: true });
+    fs.writeFileSync(path.join(work, 'scripts', 'gds', 'ship-land.js'), '// v1\n');
+    fs.writeFileSync(path.join(work, 'modules', 'grading', 'grader-score.js'), '// v1\n');
+    run('git add -A && git commit -q -m tooling');
+    publishMain(run);
+    run('git checkout -q -b feature');
+    fs.writeFileSync(path.join(work, 'src.txt'), 'the branch\'s own work\n');
+    run('git add -A && git commit -q -m work');
+    // main moves: one carved file changes, one file appears that this checkout never had.
+    run('git checkout -q main');
+    fs.writeFileSync(path.join(work, 'scripts', 'gds', 'ship-land.js'), '// v2\n');
+    fs.writeFileSync(path.join(work, 'modules', 'grading', 'grader-new.js'), '// new carve\n');
+    run('git add -A && git commit -q -m "main moves the tooling"');
+    publishMain(run);
+    run('git checkout -q feature');
+    assert.ok(!fs.existsSync(path.join(work, 'modules', 'grading', 'grader-new.js')), 'the new file is on main only');
+
+    const { result, out } = capturePreflight({ task_id: 4244, head_sha: null }, {});
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'stale-tooling');
+    assert.match(out, /- scripts\/gds\/ship-land\.js/, 'a carved ship-*.js is tooling');
+    assert.match(out, /- modules\/grading\/grader-new\.js/, 'a file only main has is still matched');
+    assert.deepEqual(staleToolingFiles({ cwd: work }).sort(), ['modules/grading/grader-new.js', 'scripts/gds/ship-land.js']);
+  });
+});
+
+test('preflight (real git): the branch\'s OWN edit to a ship-*.js is not stale tooling', () => {
+  withPreflightRepo(({ work, run }) => {
+    fs.mkdirSync(path.join(work, 'scripts', 'gds'), { recursive: true });
+    fs.writeFileSync(path.join(work, 'scripts', 'gds', 'ship-land.js'), '// v1\n');
+    run('git add -A && git commit -q -m tooling');
+    publishMain(run);
+    run('git checkout -q -b feature');
+    fs.writeFileSync(path.join(work, 'scripts', 'gds', 'ship-land.js'), '// the fix this task ships\n');
+    run('git add -A && git commit -q -m "fix the land"');
+    const { result } = capturePreflight({ task_id: 4245, head_sha: null }, {});
+    assert.equal(result.ok, true);
+    assert.deepEqual(staleToolingFiles({ cwd: work }), []);
+  });
+});
+
 // ---- runner ----
 
 let pass = 0;

package/tests/start_env_guard.mjs

@@ -118,6 +118,22 @@ t('a hosted origin says the core installs with no token, and never re-offers the
   assert.doesNotMatch(card, /\bprivate\b/i, 'must not call the package private');
 });
 
+// task 1004288: the card above was corrected when the core went public, but the SKILL that
+// routes the same fresh-clone wall kept teaching the old posture — "a PRIVATE package", "404s
+// on any machine with no NPM_TOKEN", "the expected tokenless outcome". An agent that believes
+// that reads a real 404 (a version never published, a mistyped name) as normal and moves on.
+t('the builder-start skill agrees with the card: the core is public, and a 404 is not normal', () => {
+  const { readFileSync } = require('node:fs');
+  const path = require('node:path');
+  const skill = readFileSync(path.join(import.meta.dirname, '..', '.claude', 'skills', 'builder-start', 'SKILL.md'), 'utf8');
+  assert.doesNotMatch(skill, /PRIVATE package|private package/i, 'must not call @bongos/core a private package (ADR 0283)');
+  assert.doesNotMatch(skill, /expected tokenless outcome/i, 'must not present a tokenless 404 as expected');
+  assert.doesNotMatch(skill, /404s on any machine with no `?NPM_TOKEN/i, 'must not tell the agent a tokenless install 404s');
+  assert.match(skill, /PUBLIC npm package/, 'names the core as public');
+  assert.match(skill, /ADR 0283/, 'cites the decision that made it public');
+  assert.match(skill, /404 on `@bongos\/core` is therefore \*\*not\*\* a normal outcome/, 'says a 404 now means something is wrong');
+});
+
 t('isLocalOrigin: loopback is local, everything else is remote', () => {
   for (const o of ['http://localhost:3000', 'http://app.localhost:3000', 'http://127.0.0.1:3000', 'http://[::1]:3000']) {
     assert.equal(isLocalOrigin(o), true, `${o} should be local`);

package/tests/sweep_app_account.mjs

@@ -17,13 +17,17 @@ const REPO = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const skip = spawnSync('bash', ['-c', 'true']).error ? 'bash not on PATH' : false;
 const slash = (p) => p.replace(/\\/g, '/');
 
-function stubs() {
+// `bsdStat` swaps in macOS's stat, which refuses GNU's `-c` outright and names an owner
+// with `-f %Su` instead (task 1004170).
+function stubs({ bsdStat = false } = {}) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sweep-stubs-'));
   const sudoLog = slash(path.join(dir, 'sudo.log'));
   const statLog = slash(path.join(dir, 'stat.log'));
   const bin = (name, body) => fs.writeFileSync(path.join(dir, name), `#!/usr/bin/env bash\n${body}\n`, { mode: 0o755 });
   bin('sudo', `echo "$*" >> "${sudoLog}"; exit 0`);
-  bin('stat', `echo "$*" >> "${statLog}"; echo checkout-owner`);
+  bin('stat', `echo "$*" >> "${statLog}"; ` + (bsdStat
+    ? 'case "$1 $2" in "-c "*) echo "stat: illegal option -- c" >&2; exit 1 ;; "-f %Su") echo checkout-owner ;; *) exit 1 ;; esac'
+    : 'echo checkout-owner'));
   bin('systemctl', 'exit 0');
   const lines = (f) => (fs.existsSync(f) ? fs.readFileSync(f, 'utf8').split('\n').filter(Boolean) : []);
   return { dir, sudo: () => lines(sudoLog), stat: () => lines(statLog) };
@@ -109,4 +113,13 @@ for (const [name, src] of [['address-park-sweep', PARK], ['stray-unit-sweep', ST
     assert.match(s.stat()[0] || '', new RegExp(`^-c %U .*${path.basename(inst)}$`), 'the instance root, not the package');
     assert.match(s.sudo()[0] || '', /^-n -u checkout-owner psql /);
   });
+
+  test(`${name}: on macOS, where stat refuses GNU's -c, the checkout's owner still acts (task 1004170)`, { skip }, () => {
+    // It used to read '' as the owner there and refuse with "cannot use '' as the app account".
+    const s = stubs({ bsdStat: true });
+    const inst = fs.mkdtempSync(path.join(os.tmpdir(), 'sweep-inst-'));
+    run(src, s, { INSTANCE_DIR: slash(inst) });
+    assert.deepEqual(s.stat().map((l) => l.split(' ').slice(0, 2).join(' ')), ['-c %U', '-f %Su'], 'GNU is asked first and BSD answers');
+    assert.match(s.sudo()[0] || '', /^-n -u checkout-owner psql /);
+  });
 }

package/tests/upgrade.mjs

@@ -1543,7 +1543,7 @@ t('persistPin: a refused origin push on a WIRED private instance is loud — nam
   assert.equal(r.refused, 'read-only-deploy-key');
   // The tokenless refusal is a plain sentence, not the bare status line.
   assert.match(r.error, /read-only deploy key at \/srv\/bongos\/acme\/\.git\/cloudbongos-deploy-key/, 'names the key');
-  assert.match(r.error, /no owner GitHub token is stored/, 'and why nothing else was tried');
+  assert.match(r.error, /no owner GitHub token was available/, 'and why nothing else was tried');
   assert.notEqual(r.error, 'git push failed');
   const text = warnings.join('\n');
   assert.match(text, /PIN NOT PUSHED/, 'shouts');
@@ -1655,6 +1655,25 @@ t('resolvePinPushAuth: the owner token is spent only when one is stored AND the
   assert.equal(await u.resolvePinPushAuth(dir, { log: hush, instance: inst, getGithubToken: async () => { throw new Error('secret-box off'); } }, at('git@github.com:acme/widgets.git')), null);
 });
 
+t('resolvePinPushAuth: on a hosted project\u2019s own box a missing row SAYS WHY, instead of falling back silently (task 1004065)', async () => {
+  // The project's own database has no provisioning table (ADR 0281), so the lookup
+  // answers null there — and on a checkout wired with the read-only deploy key that is
+  // not "the origin path", it is a push that cannot succeed.
+  const dir = { instanceDir: '/srv/bongos/acme' };
+  const wired = { config: { status: 0, stdout: 'ssh -F /dev/null -i /srv/bongos/acme/.git/cloudbongos-deploy-key -o IdentitiesOnly=yes\n' }, remote: { status: 0, stdout: 'git@github.com:acme/widgets.git\n' } };
+  const said = [];
+  const r = await u.resolvePinPushAuth(dir, { log: (m) => said.push(m), getInstanceBySlug: async () => null }, pinRun(wired));
+  assert.equal(r, null, 'still the remote path — there is no token to use');
+  const line = said.join('\n');
+  assert.match(line, /no provisioning row is readable from this database/, 'names what is missing');
+  assert.match(line, /read-only deploy key at \/srv\/bongos\/acme\/\.git\/cloudbongos-deploy-key/, 'and why the fallback cannot work');
+  assert.match(line, /pushes the pin from the hub/, 'and where the push actually happens');
+  // An UNWIRED checkout with no row (a laptop, a public instance) is the real origin path: quiet.
+  const quiet = [];
+  await u.resolvePinPushAuth(dir, { log: (m) => quiet.push(m), getInstanceBySlug: async () => null }, pinRun({ remote: wired.remote }));
+  assert.deepEqual(quiet, [], 'no noise where the fallback is correct');
+});
+
 t('runUpgrade --commit-pin: on a wired private instance the pin lands via the owner token, end to end', async () => {
   const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
   const src = mkdtempSync(join(tmpdir(), 'otb-upgrade-src-'));