@bongos/core 1.18.3 → 1.18.19

package/src/instance-config.js

@@ -65,6 +65,35 @@ function defaultApiBase(b = safeBrand()) {
   return (typeof origin === 'string' && origin.trim()) || 'http://localhost:3000';
 }
 
+// The API base a CLI command should actually talk to:
+//   <PREFIX>_API_BASE (env) → the PERSISTED session's api_base → defaultApiBase()
+// The session beats the branding default because a builder authenticated against
+// instance A must keep hitting A even when this checkout's own branding names B —
+// which is exactly what broke re-auth (task 1002427). cliClient() had this order
+// right; paste-token.js hardcoded the founder host and reauth.js used the bare
+// branding default, so a token minted by one instance was verified against
+// another and rejected 401. Every base resolution routes through here so the
+// three cannot drift again.
+//
+// `session` is injected by callers that already loaded it (cliClient) and read
+// from the session file otherwise; pass null to mean "no session" without a disk
+// read. Never returns empty — an unusable api_base falls back to the default.
+function resolveApiBase({ session, env = process.env, b = safeBrand() } = {}) {
+  const fromEnv = resolveEnv('API_BASE', { env, prefix: envPrefix(b) });
+  if (fromEnv) return fromEnv;
+  let s = session;
+  if (s === undefined) {
+    try {
+      const raw = readConfigFileSync('gds-session.json', { b });
+      s = raw ? JSON.parse(raw) : null;
+    } catch (_) {
+      s = null; // unreadable/corrupt session must never break base resolution
+    }
+  }
+  const fromSession = s && typeof s.api_base === 'string' && s.api_base.trim();
+  return fromSession || defaultApiBase(b);
+}
+
 // Absolute path to the instance config dir — the WRITE target and first read.
 function configHome(b = safeBrand()) {
   return path.join(os.homedir(), '.config', configDirName(b));
@@ -202,6 +231,7 @@ module.exports = {
   configDirName,
   envPrefix,
   defaultApiBase,
+  resolveApiBase,
   configHome,
   configReadDirs,
   configPath,

package/src/module-api.js

@@ -237,8 +237,131 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         was --skip-pin-verify, which the unattended auto-upgrade subscription cannot pass).
 //         package-core now drops npm-stripped files from the manifest + pin so it describes exactly
 //         what npm installs. Build-tool fix, no doorway export change → semver PATCH.
+// 1.18.4 — ship the platform-identity hub module in the core package (task 1002235, goal 1000041).
+//         The module (ADR 0141: /sso/*, projects catalog, my-projects, scouting + its migrations) was
+//         built but never added to publish-manifest PUBLISH_ALLOWLIST, so it did not ship in
+//         @bongos/core — the hub's enabledModules() threw "unknown module platform-identity" and
+//         provision.js's federation load MODULE_NOT_FOUNDed. Reclassified IN (sibling of provisioning);
+//         default:false → shipped ≠ enabled, dormant on every instance until the hub turns it on. PATCH.
+// 1.18.5 — configurable post-login landing (task 1002240, goal 1000041). A successful web sign-in
+//         that carried no explicit ?return= / same-apex Referer now lands on branding.landing.postLogin
+//         (auth.js postLoginLanding) instead of a hardcoded /builders. Portable default stays
+//         '/builders' (the hall always exists); env-overridable per instance via
+//         <PREFIX>_POST_LOGIN_LANDING. cloudbongos.com sets it to /gate/ so a visitor who signs in
+//         from the orbs returns to the orbs, never auto-redirected into the builders' hall. The value
+//         is validated through the open-redirect allowlist. Additive config read, no doorway change → PATCH.
+// 1.18.6 — post-login ?return= fix (task 1002241). parseCookie() now URL-DECODES the cookie
+//         value, symmetric with Express res.cookie's percent-ENCODING. Before this, a return
+//         target like "/create" was stored as "%2Fcreate"; safeReturnTo() rejected the encoded
+//         form and every explicit ?return= fell through to the post-login landing (on
+//         cloudbongos.com, /gate/) — most visibly the onboarding "Connect GitHub" button, which
+//         bounced to the orbs instead of back to the wizard. Also un-breaks the #726 subdomain
+//         return. A bug fix in a shared route helper, no doorway change → PATCH.
+// 1.18.7 — federated single-logout (task 1002238, goal 1000041, ADR 0144). Signing out of the hub now
+//         signs you out of every federated project too. Core gains: a `builder.logout` seam event
+//         (emitted by POST /auth/logout), a POST /auth/backchannel-logout endpoint (dormant unless the
+//         instance federates — idp set), and auth.js verifyHubLogoutToken. The hub (platform-identity)
+//         listens for builder.logout and fans a hub-signed EdDSA logout token out to each federated
+//         instance the builder entered, which verifies it (aud-scoped, purpose-tagged, ~120s TTL) and
+//         revokes that builder's local sessions. Identity/trust boundary intact (the token carries only
+//         a subject + purpose, never a rank). Additive event + route, no doorway change → PATCH.
+// 1.18.8 — hall sign-out works on every page (task 1002245). The real sign-out (POST /auth/logout:
+//         revoke session + clear cookies + emit the `builder.logout` federated single-logout) was wired
+//         ONLY in the index script (builders.js); shell.js draws the sign-out control on EVERY hall page
+//         as a bare GET anchor to the POST-only endpoint, so on non-index pages the click 404'd — the
+//         session was never revoked and the hub never notified (the 1.18.7 SLO was bypassed). Centralized
+//         in shell.js (doLogout + a delegated click listener), with tests/hall_signout.mjs proving it.
+//         Also carries minor /create wizard polish (tasks 1002246/1002247). Client + shared-surface fix,
+//         no doorway change → PATCH.
+// 1.18.9 — /create onboarding: the wizard's own "Sign in with GitHub" now requests repo scope up front
+//         (read:user + public_repo via &repos=1), so a visitor who signs in THROUGH the create flow grants
+//         everything in one GitHub screen and never hits the separate "Connect GitHub" step at Home —
+//         ensureRepoAccess()'s probe finds the stored token and shows the picker/creator directly. Also
+//         reworks the residual need-connect copy + button ("Allow repo access") so a user already signed
+//         in with identity-only scope isn't asked to "connect" as if signing in twice. Hall + CLI sign-in
+//         stay identity-only (ADR 0143 least-privilege default). Client-only (public-landing/create.html),
+//         no doorway change → PATCH. (task 1002259)
+// 1.18.10 — reward-mode go-live: the configurable per-instance branding.reward.mode knob (economy;
+//         ADR 0146) lands together with the goal-1000037 pay-on-land migrations. Cloud Bongos selects
+//         "cost-plus-only" (instance config), so a shipped task pays only the cost-plus session reward,
+//         not the per-task author estimate; the estimate still rides the row for display + the no-zero
+//         claim gate. This deploy applies core_193 (tasks.needs_rebase columns) + core_194 (the one-time
+//         confirmed-backlog clawback). Default stays "cost-plus-and-estimate" → every other instance is
+//         unchanged; economy-only, no doorway change → PATCH. (task 1002270 + goal 1000037 go-live 1002273)
+//   1.18.12 — Docs-surface correctness (task 1002374). User-facing "GDS"/"Game Development System" →
+//         "Bongos" (primer, OpenAPI spec title/description + reference header, the two CLI session
+//         messages the primer quotes). 04-architecture diagram REDRAWN for the standalone model —
+//         own repo + auto-pull deploy (ADR 0129) + vendored @bongos/core (ADR 0108), product-neutral;
+//         it had hardcoded the reference game monorepo (amazonprimea.com / GitHub-Actions deploy-prod.yml
+//         / "the live game"). Docs/prose + diagram generator only, no schema/doorway change → PATCH.
+//   1.18.11 — Standalone instances get live-updating docs (ADR 0147, task 1002314). gen-session-index.js
+//         now resolves the INSTANCE root (was hardcoded to the core, so a standalone box indexed
+//         node_modules/@bongos/core instead of its own sessions); adds upgrade.regenerateNavDocs() +
+//         a regen-instance-docs.js CLI wired into init/upgrade/provision-deploy; INSTANCE_GITIGNORE
+//         ignores the whole-file nav docs. Docs-pipeline only, no schema/doorway change → PATCH.
+//         (go-live 1002318)
+//   1.18.12 — docs-surface correctness: GDS→Bongos rename + standalone architecture redraw
+//         (task 1002374). Docs/prose + diagram generator only, no schema/doorway change → PATCH.
+//   1.18.13 — `bongos dev`: one-command LOCAL launcher for a standalone instance (task 1002397,
+//         ADR 0149). New CLI verb + scripts/gds/dev.js + dev-lib.js so a freshly-created,
+//         localhost-configured project stands up locally in one step. No schema/doorway change → PATCH.
+//   1.18.14 — module pollers actually start on a standalone instance (task 1002419). The loader's
+//         startModulePollers had ZERO callers once the game entrypoint server.js was retired, so
+//         EVERY module poller was dead — most visibly lifecycle/publish-reconciler, which is what
+//         drives confirmed→shipped, leaving merged tasks stranded at 'confirmed' indefinitely
+//         (12 rows, oldest 6.2 days). src/platform-server.js now starts them at boot behind the
+//         same isEnabled gate mountModuleRoutes uses, and stops them on SIGTERM/SIGINT. Wiring
+//         only — no schema/doorway change → PATCH. Any instance on ≤1.18.13 lands nothing until
+//         it takes this bump.
+//   1.18.15 — re-release of the 1.18.14 module-poller fix (task 1002419) under a fresh number.
+//         A SEPARATE release had already published 1.18.14 for the task-scoped dev-box go-live
+//         (goal 1000051), so the poller-fix 1.18.14 could never reach an instance already pinned to
+//         the dev-box 1.18.14 (same version = npm no-op; the pull-deploy loop skips npm ci when the
+//         lockfile is unchanged). This bump carries the identical src/platform-server.js poller
+//         wiring forward on a number no instance has taken yet, so the pin can actually move. No
+//         code delta vs the 1.18.14 already on main — version constant only → PATCH. (task 1002421)
+//   1.18.16 — go-live carrier for the hall version-UI work already merged to main since 1.18.15:
+//         the Roadmap "Command deck" redesign (task 1002426) and the sidebar reorg — nav order
+//         Roadmap→Goals→Tasks, the "Work" board relabelled "Tasks", goal-detail task parity
+//         (task 1002425, PR #17). Both landed on main with NO version bump, so no vendored-tarball
+//         instance could take them (the pull-deploy pin only moves on a fresh number). No new code
+//         delta beyond this constant → PATCH. (go-live task 1002431)
+//   1.18.17 — Goals page reorganised into a task-readiness rollup (grouped
+//         Active/Blocked/Achieved; each goal rolls its tasks into ready/in-progress/
+//         blocked + a next claimable task) and the task-list API gained an opt-in
+//         `?include=deps` that enriches each task with blocked_by[]/blocks so the
+//         hall can paint readiness without an N+1 (db.attachTaskDepSummaries). New
+//         export is additive; the enrichment is opt-in → PATCH. (task 1002439)
+//   1.18.18 — go-live carrier for 171 commits that landed on main between 2026-07-24
+//         and 2026-08-03 with no bump behind them, so no vendored-tarball instance
+//         could take any of them. Headline: the governance permission system
+//         (BV1.R95–R109 — resolver + kernel port, first-class principals, session
+//         scopes, requirePermission(), ownership-scoped grants, config/governance.json)
+//         and the route-rank/validation hardening that followed it; the ship.js
+//         Windows project-path fix so Windows sessions actually get paid (89f291c);
+//         the sequential chain runner (task 1002484); Metic task abandon/un-abandon
+//         (ADR 0152); goal-authored criteria + the orphan-task goal_advisory (ADR
+//         0154); the nightly-backup 203/EXEC fix (task 1002479); and a broad hall
+//         pass (jump palette, sidebar regroup, browser-side idea triage, mobile
+//         overflow). This bump also carries the /version-vs-CORE_VERSION divergence
+//         check added under task 1002521 — the gap above went unnoticed for ten days
+//         precisely because nothing compared live against main. The doorway surface
+//         is byte-identical to 1.18.17 (governance is reached through the kernel
+//         port, not a new export), so despite the size this is → PATCH. (task 1002521)
+//   1.18.19 — SINGLE-FIX patch cut from the core-v1.18.18 tag, not from main: core
+//         migrations were silently skipped on any checkout whose absolute path
+//         contains a space. `for f in $MIGRATIONS` word-split the newline-separated
+//         list on IFS, fragmenting every path; the `[ -e "$f" ]` guard then dropped
+//         all of them and schema_migrations stayed empty. The module loop is quoted,
+//         so module migrations ran against an empty schema and the operator saw a
+//         misleading `relation "achievements" does not exist` from modules/economy
+//         instead of the real cause. Now read with a newline-safe herestring, and a
+//         no-op guard makes the skip FATAL rather than silent. No doorway change, no
+//         schema change, one script + its test → PATCH. Deliberately does NOT carry
+//         the unreleased 1.19 tree on main, so a blocked instance can take the fix
+//         alone. (task 1002611)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.18.3'; // package-core pin honesty for vendored upgrades (task 1002229 / idea 1000543); see changelog above
+const CORE_VERSION = '1.18.19'; // single-fix patch off the 1.18.18 tag: migrations skipped on a path with a space (task 1002611); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

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);