@bongos/core 1.18.0 → 1.18.18

package/src/platform-server.js

@@ -29,10 +29,17 @@
 // by ABSENCE (the game middleware is simply never mounted), not by a runtime
 // check, exactly as preview-server.js enforces "no internal API" by absence.
 //
-// Background services (uptime poller, publish reconciler, Discord bot) are NOT
-// started here. They are not game code, but which of them a given instance runs
-// is an instance-policy decision that R54's feature-module system (task 1193)
-// will own; R51 keeps this entrypoint to the minimal "serve the surfaces" core.
+// BACKGROUND SERVICES — started here, at the bottom of this file (task 1002419).
+// R51 deferred "which background services an instance runs" to the feature-module
+// system. That system shipped: a module DECLARES contributes.pollers in its
+// manifest and the instance's enabled-module set decides what actually runs
+// (ADR 0083 / 0093 §1). So the policy question is already answered — the enabled
+// set IS the policy — and this entrypoint just has to honour it, exactly as it
+// already honours contributes.routes (mountModuleRoutes) and contributes.
+// webSurfaces (moduleWebSurfaces). Until this was wired, startModulePollers had
+// ZERO callers post-split — its only caller was ever the retired game entrypoint
+// server.js — so on a standalone instance EVERY module poller was dead: the
+// confirmed→shipped sweep never fired and shipped tasks stranded at 'confirmed'.
 
 const http = require('http');
 const fs = require('fs');
@@ -40,6 +47,8 @@ const path = require('path');
 const express = require('express');
 const { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal } = require('./bongos/serve-internal');
 const { isApiShapedPath, apiNotFoundBody } = require('./bongos/api-path-404');
+const moduleLoader = require('./module-loader/loader');
+const { isModuleEnabled } = require('./modules');
 
 const PORT = Number(process.env.PORT) || 3000;
 const HOST = process.env.HOST || '127.0.0.1';
@@ -63,6 +72,19 @@ function landingPage(file) {
   return _landingPages.get(file);
 }
 function landingHtml() { return landingPage('index.html'); }
+// The interactive landing gate (public-landing/gate/, ported from amazonprimea
+// in task 1002407). When an instance ships it, it is the apex front door
+// (task 1002408). Unlike the placeholder landing it is a self-contained baked
+// design that reads no window.__BRANDING__, so it is served RAW, not injected.
+// Memoized: absolute path to gate/index.html, or '' when the instance ships no gate.
+let _gateIndexPath; // undefined = unresolved, '' = absent, string = present
+function gateIndexPath() {
+  if (_gateIndexPath === undefined) {
+    const p = path.join(LANDING_DIR, 'gate', 'index.html');
+    _gateIndexPath = fs.existsSync(p) ? p : '';
+  }
+  return _gateIndexPath;
+}
 function isApexHost(req) {
   return !isStatusHost(req) && !isBuildersHost(req);
 }
@@ -81,16 +103,38 @@ function buildPlatformApp() {
   // The whole internal surface — shared verbatim with server.js (ADR 0062 R51).
   mountInternalSurfaces(app);
 
-  // Apex landing. On the apex host (not status./builders.), GET / serves the
-  // branding-injected landing page, and other paths can resolve a landing asset
-  // (e.g. the mascot image) from public-landing/. Both fall through to the 404
-  // tail when there is no landing file or no matching asset.
+  // Apex landing. On the apex host (not status./builders.):
+  //   * if this instance ships the interactive landing gate (public-landing/gate/),
+  //     the gate is the front door — GET / 302-redirects to /gate/ (mirrors the
+  //     amazonprimea Caddy rule this replaces, task 1002408). The redirect (not a
+  //     direct serve at /) is required so the browser base URL becomes /gate/ and
+  //     the gate's relative asset paths (sprites/…, ../world, ../assets) resolve.
+  //   * otherwise GET / serves the branding-injected minimal placeholder.
+  // Both fall through to the 404 tail when neither is present, and to the landing
+  // asset handler below for non-/ paths (e.g. the mascot image).
   app.get('/', (req, res, next) => {
     if (!isApexHost(req)) return next();
+    if (gateIndexPath()) return res.redirect(302, '/gate/');
     const html = landingHtml();
     if (!html) return next();
     res.type('html').send(html);
   });
+  // /gate → /gate/ (so the gate's relative asset paths resolve against the dir),
+  // and /gate/ serves the gate's own index RAW — a self-contained baked design,
+  // so no window.__BRANDING__ injection. The gate's sub-assets (/gate/*, /world/*,
+  // /assets/*) are served by the express.static(LANDING_DIR) handler below with no
+  // extra rule, which also closes the amazonprimea Caddy gap where /assets/anim/idle/*
+  // (the buddha idle frames) fell through to the app instead of the static server.
+  // One handler for both forms — Express's non-strict routing matches /gate and
+  // /gate/ interchangeably, so branch on the real req.path: /gate 301→ /gate/
+  // (so relative asset paths resolve against the dir), /gate/ serves the index.
+  app.get(['/gate', '/gate/'], (req, res, next) => {
+    if (!isApexHost(req)) return next();
+    const p = gateIndexPath();
+    if (!p) return next();
+    if (!req.path.endsWith('/')) return res.redirect(301, '/gate/');
+    return res.type('html').sendFile(p);
+  });
   // The branded project-creation experience (goal 35, task 2081) — a sibling
   // landing page at a clean /create URL, branding-injected like the landing.
   app.get('/create', (req, res, next) => {
@@ -122,6 +166,28 @@ function buildPlatformApp() {
   return app;
 }
 
+// Start each ENABLED module's background pollers through the loader — module-
+// agnostic: it requires modules/<key>/pollers/<name>.js and fires start(). Same
+// `{ isEnabled: isModuleEnabled }` gate mountModuleRoutes uses, so a module that
+// is off contributes no poller, exactly as it contributes no route. Non-blocking
+// + failure-isolated by the loader, and every poller is independently idempotent,
+// unref'd and self-gating (PUBLISH_RECONCILER_DISABLED, ROUTINE_TIMERS_DISABLED,
+// DISCORD_BOT_ENABLED), so a poller problem can never take the platform down.
+//
+// Safe to start unconditionally — no cross-process lease needed — because this
+// entrypoint runs as a SINGLE process (docker-entrypoint.sh `exec`s it; there is
+// no cluster/replica topology). The one poller with a hard single-runner
+// requirement, the Discord gateway, is double-gated off anyway: its module is
+// default:false AND it needs DISCORD_BOT_ENABLED=true. If an instance ever runs
+// more than one web process, this is the line that needs a lease
+// (modules/lifecycle/merge-lock.js has the pattern).
+//
+// Deliberately OUTSIDE buildPlatformApp(): importing this module (tests) must
+// bind no port and start no timers. Exported so a test can drive it directly.
+function startBackgroundServices() {
+  return moduleLoader.startModulePollers({}, { isEnabled: isModuleEnabled });
+}
+
 // Start only when run as the entry (`node src/platform-server.js`). Importing the
 // module (the smoke test) must NOT bind a port.
 if (require.main === module) {
@@ -129,7 +195,18 @@ if (require.main === module) {
   const httpServer = http.createServer(app);
   httpServer.listen(PORT, HOST, () => {
     console.log(`Cloud Bongos platform (GDS-only, no game; ADR 0062 R51) listening on ${HOST}:${PORT}`);
+    startBackgroundServices();
   });
+
+  // Graceful shutdown — stop each module poller (e.g. close the Discord gateway
+  // socket cleanly on a systemd restart / Ctrl-C so no zombie session is left for
+  // Discord to reap). stopModulePollers awaits each stop and isolates errors, so
+  // a stuck poller never blocks the exit.
+  for (const sig of ['SIGTERM', 'SIGINT']) {
+    process.on(sig, () => {
+      moduleLoader.stopModulePollers().finally(() => process.exit(0));
+    });
+  }
 }
 
-module.exports = { buildPlatformApp };
+module.exports = { buildPlatformApp, startBackgroundServices };

package/tests/abandon_task.mjs

@@ -30,7 +30,7 @@ process.env.NODE_ENV = 'test';
 
 const require = createRequire(import.meta.url);
 const db = require('../modules/lifecycle/db.js');
-const { abandonTask } = db;
+const { abandonTask, restoreTask } = db;
 
 const { test, summary } = makeRunner();
 
@@ -39,7 +39,8 @@ const { test, summary } = makeRunner();
 //   notFound       → the FOR UPDATE select matches no row
 //   status         → the row's current status
 //   hasActiveClaim → the claims lookup returns an unreleased claim
-function fakePool({ status = 'ready', notFound = false, hasActiveClaim = false }) {
+//   updatedStatus  → what the UPDATE ... RETURNING reports (restore returns 'backlog')
+function fakePool({ status = 'ready', notFound = false, hasActiveClaim = false, updatedStatus = 'abandoned' }) {
   return makeSqlAwareClient((s, params) => {
       if (/^SELECT id, title, status FROM tasks WHERE id = \$1 FOR UPDATE/.test(s)) {
         return { rows: notFound ? [] : [{ id: params[0], title: 'fixture task', status }] };
@@ -48,7 +49,7 @@ function fakePool({ status = 'ready', notFound = false, hasActiveClaim = false }
         return { rows: hasActiveClaim ? [{ id: 999 }] : [] };
       }
       if (/^UPDATE tasks/.test(s)) {
-        return { rows: [{ id: params[0], title: 'fixture task', status: 'abandoned' }] };
+        return { rows: [{ id: params[0], title: 'fixture task', status: updatedStatus }] };
       }
       return { rows: [] };   // BEGIN / COMMIT / ROLLBACK
   });
@@ -134,5 +135,60 @@ await test('abandon: a missing task throws TASK_NOT_FOUND and rolls back', async
   assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
 });
 
+// =========================================================================
+// restoreTask (ADR 0152) — the undo that had to exist before abandon could be
+// handed to Metics. Same txn shape as abandonTask, inverted.
+
+await test('restore: an abandoned task flips to backlog, COMMITs, reports previousStatus', async () => {
+  const pool = fakePool({ status: 'abandoned', updatedStatus: 'backlog' });
+  const out = await restoreTask({ taskId: TASK }, { pool });
+
+  assert.equal(out.taskStatus, 'backlog', 'restores to backlog, never straight to ready');
+  assert.equal(out.previousStatus, 'abandoned');
+  assert.ok(find(pool._client.queries, /^UPDATE tasks/), 'the tasks UPDATE must run');
+  assert.ok(find(pool._client.queries, /^COMMIT/), 'must COMMIT');
+  assert.ok(!find(pool._client.queries, /^ROLLBACK/), 'no ROLLBACK on the happy path');
+});
+
+await test("restore: clears only an 'Abandoned: …' value_summary, leaving any other note", async () => {
+  const pool = fakePool({ status: 'abandoned', updatedStatus: 'backlog' });
+  await restoreTask({ taskId: TASK }, { pool });
+  const upd = find(pool._client.queries, /^UPDATE tasks/);
+  const sql = String(upd.sql).replace(/\s+/g, ' ');
+  assert.match(sql, /status = 'backlog'/);
+  assert.match(sql, /value_summary LIKE 'Abandoned: %' THEN NULL ELSE value_summary END/,
+    'the retire stamp is cleared conditionally — an unrelated summary survives');
+  assert.equal(upd.params.length, 1, 'only the task id is bound');
+});
+
+await test('restore: a task that is not abandoned is refused and rolls back', async () => {
+  for (const status of ['ready', 'backlog', 'shipped']) {
+    const pool = fakePool({ status });
+    await assert.rejects(
+      () => restoreTask({ taskId: TASK }, { pool }),
+      (err) => err.code === 'TASK_NOT_ABANDONED',
+      `${status} must not be restorable`,
+    );
+    assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0, `must not UPDATE a ${status} task`);
+    assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+  }
+});
+
+await test('restore: a missing task throws TASK_NOT_FOUND and rolls back', async () => {
+  const pool = fakePool({ notFound: true });
+  await assert.rejects(
+    () => restoreTask({ taskId: 424242 }, { pool }),
+    (err) => err.code === 'TASK_NOT_FOUND',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('restore: never consults claims (an abandoned task has none by construction)', async () => {
+  const pool = fakePool({ status: 'abandoned', updatedStatus: 'backlog' });
+  await restoreTask({ taskId: TASK }, { pool });
+  assert.equal(all(pool._client.queries, /SELECT id FROM claims/).length, 0);
+});
+
 // -------------------------------------------------------------------------
 summary();

package/tests/api_cli_flags.mjs

@@ -0,0 +1,53 @@
+// tests/api_cli_flags.mjs
+//
+// Unit test for two PURE helpers exported from scripts/gds/cli-lib.js in support
+// of scripts/gds/api.js's CLI flags (task 1002475):
+//   - stripBom(s)      → drop a leading UTF-8 BOM (U+FEFF); pass clean input through
+//   - resolveQuiet(args, env) → true when --quiet or GDS_QUIET should suppress
+//     api.js's stderr status banner
+// Extracted out of api.js's own top-level IIFE (which has no exports and would
+// run on require()) so this behavior is unit-testable without spawning a
+// process or a network call. Deterministic, no DB/network/filesystem/live
+// server. Run: node tests/api_cli_flags.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cli = require('../scripts/gds/cli-lib.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}`); }
+}
+
+test('stripBom: removes a leading U+FEFF', () => {
+  assert.equal(cli.stripBom('{"a":1}'), '{"a":1}');
+});
+
+test('stripBom: clean input (no BOM) passes through untouched', () => {
+  assert.equal(cli.stripBom('{"a":1}'), '{"a":1}');
+  assert.equal(cli.stripBom(''), '');
+});
+
+test('stripBom: non-string input passes through untouched (edge)', () => {
+  assert.equal(cli.stripBom(null), null);
+  assert.equal(cli.stripBom(undefined), undefined);
+});
+
+test('resolveQuiet: --quiet flag present → true', () => {
+  assert.equal(cli.resolveQuiet(['GET', '/api/gds/me', '--quiet'], {}), true);
+});
+
+test('resolveQuiet: GDS_QUIET env var set → true', () => {
+  assert.equal(cli.resolveQuiet(['GET', '/api/gds/me'], { GDS_QUIET: '1' }), true);
+});
+
+test('resolveQuiet: neither flag nor env → false (default off)', () => {
+  assert.equal(cli.resolveQuiet(['GET', '/api/gds/me'], {}), false);
+});
+
+console.log(`\napi.js CLI-flag helpers (task 1002475) tests: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/auth_page_gate.mjs

@@ -29,6 +29,17 @@ db.lookupSession = async () => {
 };
 const auth = require('../src/bongos/auth.js');
 
+// BV1.R107: the page gate now also resolves a permission (page.view.public) through
+// the `governance` kernel port, so an authenticated request needs the port stubbed —
+// exactly as tests/governance_require_permission.mjs stubs it for requirePermission.
+// The audience is unchanged; tests/governance_page_gates.mjs is the parity proof.
+const seams = require('../src/module-seams.js');
+const catalog = require('../modules/governance/catalog.js');
+seams._reset();
+seams.registerProvider('governance', {
+  resolveBuilderPermissions: async () => catalog.seedForRank('xenos'),
+});
+
 // Minimal res double capturing redirect target + status.
 function fakeRes() {
   return {
@@ -88,5 +99,7 @@ await t('session lookup error → fails CLOSED (redirect, next() NOT called)', a
     'must redirect to sign-in on a lookup error (fail closed)');
 });
 
+seams._reset(); // leave the seam registry as we found it (the governance_* suites' pattern)
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/backfill_sessions.mjs

@@ -11,9 +11,14 @@
 
 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 bf = require('../scripts/gds/backfill-sessions.js');
+const { encodeProjectPath } = require('../scripts/gds/ship.js');
+const { looksLikeGraderTranscript } = require('../scripts/gds/session-cost.js');
 
 let passed = 0;
 let failed = 0;
@@ -58,7 +63,7 @@ test('extracts a release marker', () => {
 test('does NOT false-positive on CLAUDE.md markdown #N links', () => {
   // The exact shape that saturates CLAUDE.md / the injected context.
   const claudeMd = asst(
-    'See [#435](https://amazonprimea.com/builders#/task/435) and ADR 0024 ([#395](x), [#410](y)). ' +
+    'See [#435](https://example.com/builders#/task/435) and ADR 0024 ([#395](x), [#410](y)). ' +
       'Phase 2.2 [#421] shipped. (#607) mirrors to Discord.'
   );
   assert.deepEqual(bf.extractTaskIds([claudeMd]), []);
@@ -97,5 +102,126 @@ test('inScope matches every historical project-path family', () => {
   assert.equal(bf.inScope('-Users-x-Desktop-SomeOtherProject'), false);
 });
 
+// --- regressions: the tool was a silent no-op on any non-legacy checkout -----
+
+test('inScope matches THIS checkout, not just the four legacy names', () => {
+  // The bug: PROJECT_TOKENS was a hardcoded list of the owner's old project
+  // names, so every other clone skipped every folder and reported "0 transcripts"
+  // while exiting 0. The scope token must be derived from the repo itself.
+  const derived = encodeProjectPath(path.resolve('.'));
+  assert.ok(bf.inScope(derived), 'the current checkout must be in scope');
+  assert.ok(
+    bf.inScope(`${derived}--claude-worktrees-task-1002503`),
+    'a per-task worktree dir must be in scope too'
+  );
+});
+
+test('a Windows cwd encodes to the dir name Claude Code actually creates', () => {
+  // Claude Code replaces every non-alphanumeric char, so a Windows cwd (drive
+  // colon, backslashes, spaces) encodes to one long dashed name. This is the
+  // shape the old [/.] encoder no-op'd on, which is why no transcript was found.
+  assert.equal(
+    encodeProjectPath('C:\\Users\\rocke\\OneDrive\\Desktop\\Cloud Bongos\\cloud-bongos'),
+    'C--Users-rocke-OneDrive-Desktop-Cloud-Bongos-cloud-bongos'
+  );
+  // And the matching loop accepts it when it IS the derived token — asserted
+  // against inScope itself, machine-independently, via the real first token.
+  const derived = bf.PROJECT_TOKENS[0];
+  assert.ok(bf.inScope(derived), 'the derived token must match itself through inScope');
+  assert.equal(bf.inScope('C--Users-someone-else-Desktop-OtherProject'), false);
+});
+
+test('buildUploadPayload sends model_usage at the TOP level', () => {
+  // The route reads body.model_usage and never looks inside metrics; dropping it
+  // silently under-pays via the opus cache_read fallback. Guard the field set.
+  const digest = {
+    totalTokens: 135734889,
+    durationSeconds: 6407,
+    startedAt: '2026-07-26T21:18:16.356Z',
+    endedAt: '2026-07-26T23:05:03.560Z',
+    detail: [{ i: 0, role: 'assistant' }],
+    metrics: { assistant_turns: 1, model_usage: { 'claude-opus-5': { input: 1, output: 2 } } },
+  };
+  const payload = bf.buildUploadPayload({ sessionId: 'abc', taskIds: [1002471], digest });
+  assert.deepEqual(payload.model_usage, { 'claude-opus-5': { input: 1, output: 2 } });
+  assert.equal(payload.session_id, 'abc');
+  assert.deepEqual(payload.task_ids, [1002471]);
+  assert.equal(payload.total_tokens, 135734889);
+});
+
+test('buildUploadPayload defaults model_usage to {} rather than undefined', () => {
+  // An unpriceable digest must still upload (the server prices from total_tokens);
+  // an undefined field would fail the route's object validator.
+  const payload = bf.buildUploadPayload({ sessionId: 'x', taskIds: [], digest: { metrics: {} } });
+  assert.deepEqual(payload.model_usage, {});
+});
+
+test('grader detection matches a NEW worker persona, not just the known four', () => {
+  // A closed name list would let a future grader worker be uploaded as a builder
+  // session and earn credit for spend the ship path never pays.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'backfill-grader2-'));
+  const write = (name, text) => {
+    const f = path.join(dir, `${name}.jsonl`);
+    fs.writeFileSync(f, JSON.stringify({ type: 'user', message: { role: 'user', content: text } }) + '\n');
+    return f;
+  };
+  try {
+    for (const [persona, joiner] of [['Narc', '— a specialist'], ['Quality', 'specialist — an'],
+                                     ['Efficiency Monger', '— a specialist'], ['Cartographer', '— a specialist']]) {
+      const f = write(persona.replace(/\s/g, ''), `You are the **${persona}** ${joiner} adversarial subagent for the project.`);
+      assert.ok(looksLikeGraderTranscript(f), `${persona} must be detected as a grader worker`);
+    }
+    // A real session that merely mentions the panel must NOT be skipped.
+    const real = write('real', 'The adversarial subagent panel flagged my diff — help me fix it.');
+    assert.equal(looksLikeGraderTranscript(real), false, 'a builder session must not be skipped');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('extracts a 7-digit task id from a ship.js invocation', () => {
+  // {1,4} matched nothing on a live instance, so no modern session could ever pay.
+  const ids = bf.extractTaskIds([toolUse('Bash', { command: 'node scripts/gds/ship.js 1002471' })]);
+  assert.deepEqual(ids, [1002471]);
+});
+
+test('extracts 7-digit ids from claim/release/Claimed markers', () => {
+  assert.deepEqual(bf.extractTaskIds([asst('Running /builder-claim 1002503 now')]), [1002503]);
+  assert.deepEqual(bf.extractTaskIds([asst('builder-release 1002446 — handing it back')]), [1002446]);
+  assert.deepEqual(bf.extractTaskIds([asst('Claimed task #1002475.')]), [1002475]);
+});
+
+test('7-digit ids survive extractTaskIds (the n < 10000 clamp is gone)', () => {
+  // Widening TASK_MARKERS alone was not enough: the clamp dropped them again.
+  const entries = [
+    toolUse('Bash', { command: 'node scripts/gds/ship.js 1002471' }),
+    asst('Claimed #284.'), // legacy 3-digit ids must still work
+  ];
+  assert.deepEqual(bf.extractTaskIds(entries), [284, 1002471]);
+});
+
+test('grader worker transcripts are detectable and would otherwise be paid', () => {
+  // The grader panel writes each worker as its OWN transcript in the same project
+  // dir. A worker quotes the diff, so it carries real ship markers — uploading one
+  // would book a cost-plus reward the live ship path never pays.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'backfill-grader-'));
+  const file = path.join(dir, 'aaaaaaaa-0000-0000-0000-000000000000.jsonl');
+  const graderPrompt =
+    'You are the **Narc** — a specialist adversarial subagent for this project. ' +
+    'Review the diff shipped by node scripts/gds/ship.js 1002471 --summary "x".';
+  try {
+    fs.writeFileSync(file, JSON.stringify({ type: 'user', message: { role: 'user', content: graderPrompt } }) + '\n');
+    assert.ok(looksLikeGraderTranscript(file), 'the grader worker prompt must be detected');
+    // Load-bearing: without the skip, this transcript yields a real shipped id.
+    assert.deepEqual(bf.extractTaskIds([asst(graderPrompt)]), [1002471]);
+
+    const normal = path.join(dir, 'bbbbbbbb-0000-0000-0000-000000000000.jsonl');
+    fs.writeFileSync(normal, JSON.stringify({ type: 'user', message: { role: 'user', content: 'fix the backfill script' } }) + '\n');
+    assert.equal(looksLikeGraderTranscript(normal), false, 'a real builder session must NOT be skipped');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 console.log(`\nbackfill_sessions: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/backup_cli.mjs

@@ -10,6 +10,7 @@
 // Run:  node tests/backup_cli.mjs
 
 import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
 
 let passed = 0;
 let failed = 0;
@@ -94,6 +95,59 @@ t('trigger response: 409 when already running', () => {
   assert.equal(response.error, 'backup_already_running');
 });
 
+// ---- staleness detection (task 1002479) -------------------------------------
+// These import the REAL implementations rather than re-implementing them, so a
+// regression in the shipped code fails here instead of passing against a copy.
+const backupRoute = createRequire(import.meta.url)('../src/bongos/routes/backup.js');
+const { parseDumpTimestamp, dumpAgeHours, isStaleDump } = backupRoute;
+
+const NOW = Date.parse('2026-07-28T23:00:00Z');
+
+t('parseDumpTimestamp: the dump stamp is NOT plain ISO — colons must be reinserted', () => {
+  // Regression guard: Date.parse on the raw stamp returns NaN. If someone
+  // "simplifies" this to Date.parse(stamp), staleness silently becomes unknown
+  // → every dump reads stale (or, with a sloppier fallback, every dump reads fresh).
+  assert.ok(Number.isNaN(Date.parse('2026-07-28T230421Z')), 'raw stamp should not parse as ISO');
+  assert.equal(parseDumpTimestamp('2026-07-28T230421Z'), Date.parse('2026-07-28T23:04:21Z'));
+});
+
+t('parseDumpTimestamp: rejects garbage rather than guessing', () => {
+  for (const bad of ['', null, undefined, 'nope', '2026-07-28', '2026-07-28T2304Z']) {
+    assert.equal(parseDumpTimestamp(bad), null, `should reject ${JSON.stringify(bad)}`);
+  }
+});
+
+t('dumpAgeHours: computes hours, floors at 0 for a future stamp', () => {
+  assert.equal(dumpAgeHours('2026-07-28T220000Z', NOW), 1);
+  assert.equal(dumpAgeHours('2026-07-27T230000Z', NOW), 24);
+  assert.equal(dumpAgeHours('2026-07-29T230000Z', NOW), 0, 'future stamp must not go negative');
+  assert.equal(dumpAgeHours('garbage', NOW), null);
+});
+
+t('isStaleDump: fresh dump is not stale', () => {
+  assert.equal(isStaleDump('2026-07-28T230421Z', NOW), false);
+  assert.equal(isStaleDump('2026-07-27T140000Z', NOW), false, '33h is inside the 36h threshold');
+});
+
+t('isStaleDump: the real 13-day cloudbongos outage is detected', () => {
+  // The actual last good dump before the 203/EXEC failure was 2026-07-15.
+  assert.equal(isStaleDump('2026-07-15T040302Z', NOW), true);
+  assert.ok(dumpAgeHours('2026-07-15T040302Z', NOW) > 300, 'should be ~13 days of hours');
+});
+
+t('isStaleDump: an undateable stamp fails LOUD (stale), never silently healthy', () => {
+  assert.equal(isStaleDump('garbage', NOW), true);
+  assert.equal(isStaleDump('', NOW), true);
+  assert.equal(isStaleDump(undefined, NOW), true);
+});
+
+t('isStaleDump: threshold boundary is exclusive', () => {
+  const at36h = '2026-07-27T110000Z'; // exactly 36h before NOW
+  assert.equal(dumpAgeHours(at36h, NOW), 36);
+  assert.equal(isStaleDump(at36h, NOW, 36), false, 'exactly at threshold is not yet stale');
+  assert.equal(isStaleDump('2026-07-27T105900Z', NOW, 36), true, 'one minute past is stale');
+});
+
 // ---- summary ----------------------------------------------------------------
 console.log('');
 if (failed === 0) {

package/tests/bongos_box_connect.mjs

@@ -3,6 +3,7 @@
 // helpers are exercised. Picked up by scripts/gds/run-unit-tests.js (the `unit` gate).
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
+import crypto from 'node:crypto';
 import lib from '../scripts/gds/box-connect-lib.js';
 
 const HOST = 'box-alice.dev.amazonprimea.com';
@@ -63,6 +64,62 @@ test('buildKnownHostsUpsert drops the stale line for the host, keeps others, app
   assert.ok(next.includes(`${HOST} ssh-rsa AAAARSANEW`), 'appends every reported key');
 });
 
+// task 1002509 — the upsert used to compare field 1 to the hostname with `!==`, so
+// the two forms OpenSSH actually writes survived the "replace" and stale lines
+// ACCUMULATED: the client kept verifying against the first, now-wrong entry
+// ("Host denied (verification failed)") on a box that had just re-reported keys.
+test('buildKnownHostsUpsert drops a host,ip entry for this box (the accumulation bug)', () => {
+  const existing = `${HOST},64.225.49.206 ssh-ed25519 STALE\n`;
+  const next = lib.buildKnownHostsUpsert(existing, HOST, 'ssh-ed25519 AAAANEW');
+  assert.ok(!next.includes('STALE'), 'a `host,ip` field-1 names this host and must be replaced');
+  assert.ok(next.includes(`${HOST} ssh-ed25519 AAAANEW`));
+});
+
+test('buildKnownHostsUpsert drops a HASHED entry for this box, keeps another host, keeps comments', () => {
+  const salt = crypto.randomBytes(20);
+  const hashFor = (h) => `|1|${salt.toString('base64')}|${crypto.createHmac('sha1', salt).update(h).digest('base64')}`;
+  const existing = [
+    '# hand-written note',
+    `${hashFor(HOST)} ssh-ed25519 STALEHASHED`,
+    `${hashFor('other.example.com')} ssh-ed25519 KEEPHASHED`,
+  ].join('\n') + '\n';
+  const next = lib.buildKnownHostsUpsert(existing, HOST, 'ssh-ed25519 AAAANEW');
+  assert.ok(!next.includes('STALEHASHED'), 'HashKnownHosts entries must be matched, not stepped over');
+  assert.ok(next.includes('KEEPHASHED'), 'another host hashed with the same salt stays');
+  assert.ok(next.includes('# hand-written note'), 'comments survive');
+});
+
+test('buildKnownHostsUpsert drops an IP-keyed line when the box IP is supplied', () => {
+  const existing = '203.0.113.7 ssh-ed25519 STALEIP\nunrelated.example.com ssh-ed25519 KEEP\n';
+  const next = lib.buildKnownHostsUpsert(existing, HOST, 'ssh-ed25519 AAAANEW', '203.0.113.7');
+  assert.ok(!next.includes('STALEIP'), 'DNS is repointed on every wake — an old IP line is stale too');
+  assert.ok(next.includes('KEEP'));
+});
+
+test('buildKnownHostsUpsert is idempotent — re-running never grows the file', () => {
+  const first = lib.buildKnownHostsUpsert('', HOST, 'ssh-ed25519 AAAANEW\nssh-rsa AAAARSA');
+  const second = lib.buildKnownHostsUpsert(first, HOST, 'ssh-ed25519 AAAANEW\nssh-rsa AAAARSA');
+  assert.equal(second, first);
+  assert.equal(second.split('\n').filter(Boolean).length, 2);
+});
+
+// task 1002509 — the old inline logic FAILED OPEN: no fingerprint (ssh-keygen absent
+// from a GUI process's leaner PATH) or an unreadable key list meant "skip", so a
+// builder whose key was never on the server got a bare "Permission denied". A
+// redundant POST is free (the server upserts by fingerprint), uncertainty is not.
+test('decideKeyRegistration registers on uncertainty and skips only on proof', () => {
+  const FP = 'SHA256:abc';
+  assert.deepEqual(lib.decideKeyRegistration({ created: true }), { register: true, why: 'created' });
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listedKeys: [{ fingerprint: FP }] }).register, false);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listedKeys: [{ fingerprint: 'SHA256:other' }] }).register, true);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listedKeys: [] }).register, true);
+  // the two fail-open holes this closes:
+  assert.equal(lib.decideKeyRegistration({ fingerprint: null, listedKeys: [] }).register, true);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: null, listedKeys: [{ fingerprint: FP }] }).register, true);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listFailed: true }).register, true);
+  assert.equal(lib.decideKeyRegistration({}).register, true, 'no information at all → register');
+});
+
 test('buildRemoteShellCommand forces claude only on first run and always lands in /workspace', () => {
   const first = lib.buildRemoteShellCommand({ firstRun: true });
   const later = lib.buildRemoteShellCommand({ firstRun: false });
@@ -74,6 +131,26 @@ test('buildRemoteShellCommand forces claude only on first run and always lands i
   assert.match(later, /exec bash -l/);
 });
 
+test('buildRemoteShellCommand re-scopes on connect ONLY with sync:true (BV1.R101)', () => {
+  const noSync = lib.buildRemoteShellCommand({ firstRun: false, sync: false });
+  const withSync = lib.buildRemoteShellCommand({ firstRun: false, sync: true });
+  assert.ok(!/box-sync/.test(noSync), 'default (sync:false) never re-scopes');
+  assert.match(withSync, /node scripts\/gds\/box-sync\.js \|\| true/);
+  // order: cd → re-scope → shell, so the builder lands in the scoped folder.
+  assert.ok(withSync.indexOf('cd /workspace') < withSync.indexOf('box-sync'), 'cd before sync');
+  assert.ok(withSync.indexOf('box-sync') < withSync.indexOf('exec bash -l'), 'sync before the shell');
+  // sync + firstRun: re-scope THEN the one-time claude /login handoff.
+  const both = lib.buildRemoteShellCommand({ firstRun: true, sync: true });
+  assert.ok(both.indexOf('box-sync') < both.indexOf('claude || true'), 'sync before the first-run login');
+});
+
+test('buildRemoteResyncCommand is a cd + re-scope one-shot (bongos code path) — no shell (BV1.R101)', () => {
+  const cmd = lib.buildRemoteResyncCommand();
+  assert.match(cmd, /cd \/workspace/);
+  assert.match(cmd, /node scripts\/gds\/box-sync\.js \|\| true/);
+  assert.ok(!/exec bash/.test(cmd), 'one-shot — never spawns a login shell');
+});
+
 test('remoteAuthority builds a VS Code Remote-SSH authority', () => {
   assert.equal(lib.remoteAuthority(HOST), `ssh-remote+${HOST}`);
 });