@bongos/core 1.17.1 → 1.17.2

package/modules/provisioning/tests/provisioning.mjs

@@ -0,0 +1,232 @@
+// modules/provisioning/tests/provisioning.mjs
+//
+// DB-free unit smoke for the provisioning module's domain slice (ADR 0111). Focus:
+// the P4 (#1945) Caddy on-demand-TLS ALLOW-LIST helpers — normalizeHostname (pure)
+// and isProvisionedHostname (a fake { query }) — plus a sanity check of the P1 pure
+// helpers. No DB, no network: `db` is a recording fake. Auto-discovered + run by
+// scripts/gds/run-unit-tests.js when the `provisioning` module is enabled (it is on
+// OTB). Run standalone: node modules/provisioning/tests/provisioning.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const P = require('../provisioning.js');
+const RL = require('../rate-limit.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+console.log('normalizeHostname (on-demand-TLS allow-list, P4):');
+
+t('lowercases, trims, drops a trailing dot + a :port', () => {
+  assert.equal(P.normalizeHostname('  Mercury.Example.COM. '), 'mercury.example.com');
+  assert.equal(P.normalizeHostname('mercury.example.com:443'), 'mercury.example.com');
+});
+
+t('rejects a bare TLD / empty / malformed names (fail-closed → the caller denies)', () => {
+  assert.equal(P.normalizeHostname('com'), '');
+  assert.equal(P.normalizeHostname(''), '');
+  assert.equal(P.normalizeHostname(null), '');
+  assert.equal(P.normalizeHostname('-bad.example.com'), '');
+  assert.equal(P.normalizeHostname('bad-.example.com'), '');
+  assert.equal(P.normalizeHostname('has space.example.com'), '');
+  assert.equal(P.normalizeHostname('a..b.com'), '');
+});
+
+t('accepts a normal multi-label host', () => {
+  assert.equal(P.normalizeHostname('a.b.example.com'), 'a.b.example.com');
+});
+
+console.log('\nisProvisionedHostname (the Caddy `ask` allow-list, P4):');
+
+// A fake db whose query returns the status row a lookup fn decides, keyed on $1.
+function fakeDb(statusFor) {
+  return { query: async (_sql, params) => {
+    const s = statusFor(String(params[0]));
+    return { rows: s ? [{ status: s }] : [] };
+  } };
+}
+
+await ta('true ONLY for a provisioning|active instance; false for every other state or unknown', async () => {
+  const byHost = {
+    'live.example.com': 'active',
+    'mid.example.com': 'provisioning',
+    'gone.example.com': 'torn_down',
+    'req.example.com': 'requested',
+    'err.example.com': 'error',
+    'down.example.com': 'tearing_down',
+  };
+  const db = fakeDb((h) => byHost[h] || null);
+  assert.equal(await P.isProvisionedHostname(db, 'live.example.com'), true);
+  assert.equal(await P.isProvisionedHostname(db, 'mid.example.com'), true);
+  assert.equal(await P.isProvisionedHostname(db, 'gone.example.com'), false);
+  assert.equal(await P.isProvisionedHostname(db, 'req.example.com'), false);
+  assert.equal(await P.isProvisionedHostname(db, 'err.example.com'), false);
+  assert.equal(await P.isProvisionedHostname(db, 'down.example.com'), false);
+  assert.equal(await P.isProvisionedHostname(db, 'unknown.example.com'), false);
+});
+
+await ta('normalizes the SNI before matching, and never queries a malformed host (fail-closed, no DB hit)', async () => {
+  let queried = 0;
+  const db = { query: async (_sql, params) => {
+    queried++;
+    return { rows: params[0] === 'live.example.com' ? [{ status: 'active' }] : [] };
+  } };
+  assert.equal(await P.isProvisionedHostname(db, 'LIVE.example.com.:443'), true, 'normalized SNI matches');
+  const before = queried;
+  assert.equal(await P.isProvisionedHostname(db, 'com'), false);
+  assert.equal(await P.isProvisionedHostname(db, ''), false);
+  assert.equal(queried, before, 'no query issued for a malformed host');
+});
+
+console.log('\nmakeAskRateLimiter (tls-check ask rate limit, P4 SEC review of task 1945):');
+
+function fakeRes() {
+  return {
+    _status: 200, _json: null, _headers: {},
+    set(k, v) { this._headers[k] = v; return this; },
+    status(c) { this._status = c; return this; },
+    json(b) { this._json = b; return this; },
+  };
+}
+function call(mw, ip) {
+  let nexted = false;
+  const res = fakeRes();
+  mw({ ip }, res, () => { nexted = true; });
+  return { nexted, res };
+}
+
+t('allows up to `max` per window, then 429s with Retry-After', () => {
+  let clock = 1_000_000;
+  const mw = RL.makeAskRateLimiter({ windowMs: 60_000, max: 3, now: () => clock });
+  for (let i = 0; i < 3; i++) {
+    const { nexted, res } = call(mw, '1.2.3.4');
+    assert.equal(nexted, true, `request ${i + 1} within cap passes`);
+    assert.equal(res._status, 200);
+  }
+  const over = call(mw, '1.2.3.4');
+  assert.equal(over.nexted, false, 'over-cap request is blocked (next not called)');
+  assert.equal(over.res._status, 429);
+  assert.ok(Number(over.res._headers['Retry-After']) >= 1, 'sets Retry-After');
+  assert.equal(over.res._json.error, 'rate_limited');
+});
+
+t('the window slides — after windowMs elapses, requests flow again', () => {
+  let clock = 0;
+  const mw = RL.makeAskRateLimiter({ windowMs: 1_000, max: 1, now: () => clock });
+  assert.equal(call(mw, 'a').nexted, true);
+  assert.equal(call(mw, 'a').nexted, false, 'second within the window is blocked');
+  clock += 1_001; // step past the window
+  assert.equal(call(mw, 'a').nexted, true, 'allowed again after the window slides');
+});
+
+t('per-IP buckets are independent', () => {
+  let clock = 5;
+  const mw = RL.makeAskRateLimiter({ windowMs: 60_000, max: 1, now: () => clock });
+  assert.equal(call(mw, 'ip-a').nexted, true);
+  assert.equal(call(mw, 'ip-a').nexted, false, 'ip-a is capped');
+  assert.equal(call(mw, 'ip-b').nexted, true, 'ip-b has its own bucket');
+});
+
+console.log('\nP1 pure helpers (sanity):');
+
+t('isValidSlug basic contract', () => {
+  assert.equal(P.isValidSlug('mercury'), true);
+  assert.equal(P.isValidSlug('a'), false);      // too short
+  assert.equal(P.isValidSlug('-x'), false);     // leading dash
+  assert.equal(P.isValidSlug('a--b'), false);   // double dash
+});
+
+console.log('\nGitHub App Manifest — pure builders (task 2080, ADR 0133):');
+
+t('githubAppName prefers the DOMAIN (unique + reads on the consent screen)', () => {
+  // The domain is globally unique, so "demo" never collides once named after its host.
+  assert.equal(P.githubAppName({ domain: 'demo.cloudbongos.com', brand: 'Cloud Bongos', project: 'demo' }), 'demo.cloudbongos.com');
+  assert.equal(P.githubAppName({ domain: 'Mercury.Example.com.:443', brand: 'X', project: 'mercury' }), 'mercury.example.com'); // normalized (case/port/dot)
+});
+
+t('githubAppName falls back to brand-qualified project when there is no usable domain', () => {
+  // no domain → "<brand> - <project>", still collision-resistant vs a bare slug
+  assert.equal(P.githubAppName({ brand: 'Cloud Bongos', project: 'demo' }), 'Cloud Bongos - demo');
+  // a domain over GitHub's 34-char limit → fall back to brand-qualified project
+  assert.equal(P.githubAppName({ domain: 'a-really-long-subdomain.enterprise.example.com', brand: 'Cloud Bongos', project: 'demo' }), 'Cloud Bongos - demo');
+  assert.equal(P.githubAppName({ brand: '', project: 'mercury' }), 'mercury');           // no brand → project
+  assert.equal(P.githubAppName({ brand: 'Cloud Bongos', project: '' }), 'Cloud Bongos');  // no project → brand
+  assert.equal(P.githubAppName({}), 'Cloud Bongos');                                      // last-resort default
+  const long = P.githubAppName({ brand: 'Cloud Bongos', project: 'x'.repeat(50) });
+  assert.ok(long.length <= 34 && long.startsWith('Cloud Bongos - '), `capped + brand kept: ${long}`);
+});
+
+t('buildGithubAppManifest points redirect at the MOTHERSHIP, callbacks at the INSTANCE, minimal perms, domain-named', () => {
+  const m = P.buildGithubAppManifest({
+    instanceName: 'mercury', slug: 'mercury', brand: 'Cloud Bongos',
+    instanceDomain: 'mercury.example.com', mothershipOrigin: 'https://cloudbongos.com',
+  });
+  assert.equal(m.name, 'mercury.example.com'); // the App is named after its own domain
+  assert.equal(m.url, 'https://mercury.example.com');
+  // redirect_url = the control-plane callback (where GitHub returns the code)
+  assert.equal(m.redirect_url, 'https://cloudbongos.com/api/bongos/provisioning/github-app/callback');
+  // callback_urls = the INSTANCE's own sign-in callback, BOTH prefixes for robustness
+  assert.deepEqual(m.callback_urls, [
+    'https://mercury.example.com/api/gds/auth/web/callback',
+    'https://mercury.example.com/api/bongos/auth/web/callback',
+  ]);
+  // sign-in needs no repo/account permissions; no active webhook; not public
+  assert.deepEqual(m.default_permissions, {});
+  assert.equal(m.hook_attributes.active, false);
+  assert.equal(m.public, false);
+});
+
+t('buildGithubAppManifest tolerates a trailing slash on the mothership origin', () => {
+  const m = P.buildGithubAppManifest({ instanceName: 'M', slug: 'm', instanceDomain: 'm.example.com', mothershipOrigin: 'https://cloudbongos.com/' });
+  assert.equal(m.redirect_url, 'https://cloudbongos.com/api/bongos/provisioning/github-app/callback');
+});
+
+t('manifestPostUrl: personal vs org, state url-encoded', () => {
+  assert.equal(P.manifestPostUrl({ account: 'personal', state: 'abc' }), 'https://github.com/settings/apps/new?state=abc');
+  assert.equal(P.manifestPostUrl({ account: 'org', orgLogin: 'acme', state: 'a b' }), 'https://github.com/organizations/acme/settings/apps/new?state=a%20b');
+  // org requested but no org login → falls back to personal (never a broken URL)
+  assert.equal(P.manifestPostUrl({ account: 'org', state: 'x' }), 'https://github.com/settings/apps/new?state=x');
+});
+
+console.log('\nGitHub App Manifest — data access (fake { query }):');
+
+await ta('attachManifestCode is single-use + TTL-guarded (only a pending, un-expired row advances)', async () => {
+  const seen = [];
+  const db = { query: async (sql, params) => {
+    seen.push({ sql, params });
+    // Emulate the guarded UPDATE ... WHERE status='pending' AND expires_at > now():
+    // the fake returns a row only when the caller's id is the "fresh" one.
+    if (/UPDATE provisioning_oauth_manifests/.test(sql) && /status = 'code_received'/.test(sql)) {
+      return { rows: params[0] === 1 ? [{ id: 1, status: 'code_received', github_code: params[1] }] : [] };
+    }
+    return { rows: [] };
+  } };
+  const fresh = await P.attachManifestCode(db, 1, 'CODE123');
+  assert.ok(fresh && fresh.status === 'code_received' && fresh.github_code === 'CODE123');
+  const stale = await P.attachManifestCode(db, 2, 'CODE456'); // wrong/expired → no row
+  assert.equal(stale, null);
+  // the guard (status + expiry) lives in the SQL, not JS — assert it's actually there
+  assert.match(seen[0].sql, /status = 'pending' AND expires_at > now\(\)/);
+});
+
+await ta('claimNextOAuthManifest flips code_received→converting, gated on an ACTIVE instance, SKIP LOCKED', async () => {
+  let sql = '';
+  const db = { query: async (q) => { sql = q; return { rows: [{ id: 7, status: 'converting' }] }; } };
+  const row = await P.claimNextOAuthManifest(db);
+  assert.equal(row.id, 7);
+  assert.match(sql, /SET status = 'converting'/);
+  assert.match(sql, /FOR UPDATE OF m SKIP LOCKED/);
+  assert.match(sql, /m\.status = 'code_received' AND i\.status = 'active'/);
+});
+
+console.log(`\nprovisioning module: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/modules/security/secret-scrub.js

@@ -146,10 +146,19 @@ function redactHighEntropy(text) {
 const ENV_SECRET_KEY_RE =
   /(?:api[_-]?key|secret|token|password|passwd|pwd|passphrase|access[_-]?key|private[_-]?key|client[_-]?secret|credential|cookie)/i;
 const ENV_SECRET_PREFIX_RE = /^(?:gds_|pms_|mac_|apple|anthropic|stripe|cf_|cloudflare|do_token|digitalocean)/i;
+// Benign shell/runtime vars whose NAME trips a secret-word substring but whose VALUE is
+// never a credential. PWD and OLDPWD contain "pwd" (the password alternative in
+// ENV_SECRET_KEY_RE), yet hold a working-directory PATH — so without this exclusion a
+// legitimate publish fails closed whenever that path appears verbatim in a functional file
+// (e.g. a /Users/<name> anti-pattern comment), passing or failing purely on the operator's
+// last `cd` (task 2130). Exact-match only, so real password vars (MYSQL_PWD, DB_PWD, …)
+// still match below.
+const ENV_BENIGN_KEY_RE = /^(?:PWD|OLDPWD)$/;
 function collectEnvSecrets(env = process.env) {
   const out = [];
   for (const [k, v] of Object.entries(env || {})) {
     if (typeof v !== 'string' || v.length < 8) continue;
+    if (ENV_BENIGN_KEY_RE.test(k)) continue;
     if (ENV_SECRET_KEY_RE.test(k) || ENV_SECRET_PREFIX_RE.test(k)) out.push(v);
   }
   return out;
@@ -196,6 +205,7 @@ module.exports = {
   redactHighEntropy,
   ENV_SECRET_KEY_RE,
   ENV_SECRET_PREFIX_RE,
+  ENV_BENIGN_KEY_RE,
   collectEnvSecrets,
   scrubSecrets,
 };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.17.1",
+  "version": "1.17.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.17.1",
+      "version": "1.17.2",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.17.1",
+  "version": "1.17.2",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",
@@ -10,7 +10,12 @@
   "exports": {
     ".": "./src/platform-server.js",
     "./serve-internal": "./src/bongos/serve-internal.js",
-    "./module-api": "./src/module-api.js"
+    "./module-api": "./src/module-api.js",
+    "./bongos/api-path-404": "./src/bongos/api-path-404.js",
+    "./bongos/uptime-poller": "./src/bongos/uptime-poller.js",
+    "./module-loader/loader": "./src/module-loader/loader.js",
+    "./modules": "./src/modules.js",
+    "./module-seams": "./src/module-seams.js"
   },
   "engines": {
     "node": ">=22"

package/scripts/discord/README.md

@@ -1,6 +1,6 @@
 # Discord integration (outbound)
 
-Posts Off the Boats build updates into the team Discord. This replaced the
+Posts Example build updates into the team Discord. This replaced the
 Google Chat outbound broadcast (Discord Phase 2, GDS task [#607](https://example.com/builders#/task/607)).
 
 Discord is a **one-way window into the GDS** — these scripts only POST. No

package/scripts/gds/claim.js

@@ -143,7 +143,88 @@ function printClaimCard(task, widgetsEnabled = true) {
   } catch (_) { /* never block a claim on the card */ }
 }
 
-(async () => {
+// task 1476: render a failed claim as GUIDANCE, not a raw object dump. The API
+// returns the R01 error envelope (ADR 0116): { error: { code, message, details } }.
+// Older paths returned a flat { error: 'CODE', ...fields } shape. This normalizes
+// BOTH — without it `r.data.error` is now an object (never === a string), so every
+// branch below silently missed and the refusal printed as `[object Object]`. Pure
+// (no console / no process.exit) + exported so it can be unit-tested against the
+// real envelope shapes. Returns { lines, exit }.
+function formatClaimFailure(r, taskId) {
+  const lines = [];
+  const errRaw = r && r.data ? r.data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  const code = isEnvelope ? errRaw.code : errRaw;
+  const message = isEnvelope ? errRaw.message : undefined;
+  // Structured fields live under .details in the envelope; fall back to the
+  // top-level body for the legacy flat shape (so both keep working).
+  const d = { ...(r && r.data ? r.data : {}), ...((isEnvelope && errRaw.details) || {}) };
+
+  // #766: a generic onboarding stage gate (kept rendering cleanly, not as raw JSON).
+  if (code === 'stage_required') {
+    lines.push(`Task #${taskId} can't be claimed yet.`);
+    lines.push(`  ${d.what_to_do || `Clear "${d.required_stage_label || d.required_stage}" first.`}`);
+    return { lines, exit: 1 };
+  }
+  // task 1476 (the core case): a session may hold at most ONE active claim
+  // (task 1642 / ADR 0097). This is the most common refusal and previously fell
+  // straight through to the raw dump — the exact "reads like you can't hold more
+  // than one task" complaint from idea 218. Surface it as guidance AND teach how
+  // to parallelize (a separate worktree/session per task, or the hall bulk-claim).
+  if (code === 'session_already_has_active_claim' || code === 'session_claim_check_failed') {
+    const n = d.active_task_id;
+    lines.push(n
+      ? `This session already holds task #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
+      : 'This session already holds an active claim.');
+    lines.push(`  ${d.what_to_do || (n
+      ? `Run /builder-ship ${n} (or /builder-release ${n}) first, or open a fresh worktree/session for this task.`
+      : 'Ship or release the in-flight claim, or start a fresh worktree/session.')}`);
+    lines.push('  One claim per session keeps each ship isolated (task 1642). To work tasks in PARALLEL, open a separate worktree/session per task — each holds its own single claim — or use the hall work board’s multi-select bulk-claim.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'newcomer_must_ship_first') {
+    lines.push(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
+    lines.push(`  You're holding an active claim on #${d.active_task_id}: ${d.active_task_title}`);
+    lines.push(`  ${d.what_to_do || 'Ship or release the current claim first.'}`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'ALREADY_CLAIMED') {
+    lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'MODULE_CONFLICT') {
+    lines.push(`Task #${taskId} has module_key='${d.module_key}', but another active claim already owns that module:`);
+    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
+    lines.push('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'TOUCHES_CONFLICT') {
+    lines.push(`Task #${taskId} touches files currently in flight on another claim:`);
+    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
+    lines.push('Pick a task with disjoint touches[], or run it in a separate session once the other ships.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'TASK_NOT_READY') {
+    lines.push(`Task #${taskId} is not ready (current status: ${d.currentStatus}).`);
+    if (d.hint) lines.push(`  ${d.hint}`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'TASK_NOT_FOUND') {
+    lines.push(`Task #${taskId} not found — check the id (run /builder-start to list claimable tasks).`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'DEPS_NOT_SHIPPED') {
+    lines.push(`Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
+    for (const dep of d.deps || []) lines.push(`  - #${dep.id}  [${dep.status}]  ${dep.title}`);
+    lines.push('Ship those first (or release them) and try again.');
+    return { lines, exit: 1 };
+  }
+  // Fallback — still readable: the message + code, never a raw [object Object].
+  lines.push(`Claim failed (${r ? r.status : '?'})${code ? ` [${code}]` : ''}${message ? `: ${message}` : ''}.`);
+  return { lines, exit: 1 };
+}
+
+async function main() {
   await requireSession();
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
@@ -283,51 +364,20 @@ function printClaimCard(task, widgetsEnabled = true) {
     printClaimCard(task, widgetsEnabled);
     return;
   }
-  // #766: the newcomer claim gate is now just the one-claim-at-a-time rule
-  // below. A generic stage_required (any future onboarding gate) still renders
-  // cleanly rather than as a raw API error.
-  if (r.data?.error === 'stage_required') {
-    console.error(`Task #${taskId} can't be claimed yet.`);
-    console.error(`  ${r.data.what_to_do || `Clear "${r.data.required_stage_label || r.data.required_stage}" first.`}`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'newcomer_must_ship_first') {
-    console.error(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
-    console.error(`  You're holding an active claim on #${r.data.active_task_id}: ${r.data.active_task_title}`);
-    console.error(`  ${r.data.what_to_do || 'Ship or release the current claim first.'}`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'ALREADY_CLAIMED') {
-    console.error(`Task #${taskId} was just claimed by another session. Try a different task.`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'MODULE_CONFLICT') {
-    console.error(`Task #${taskId} has module_key='${r.data.module_key}', but another active claim already owns that module:`);
-    for (const t of r.data.conflictTaskTitles || []) console.error(`  - ${t}`);
-    console.error('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
-    process.exit(1);
-  }
-  if (r.data?.error === 'TOUCHES_CONFLICT') {
-    console.error(`Task #${taskId} touches files currently in flight on another claim:`);
-    for (const t of r.data.conflictTaskTitles || []) console.error(`  - ${t}`);
-    console.error('Pick a task with disjoint touches[].');
-    process.exit(1);
-  }
-  if (r.data?.error === 'TASK_NOT_READY') {
-    console.error(`Task #${taskId} is not ready (current status: ${r.data.currentStatus}).`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'DEPS_NOT_SHIPPED') {
-    console.error(`Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
-    for (const d of r.data.deps || []) {
-      console.error(`  - #${d.id}  [${d.status}]  ${d.title}`);
-    }
-    console.error('Ship those first (or release them) and try again.');
+  // Any non-201 comes here. formatClaimFailure normalizes the R01 error envelope
+  // and renders the refusal as guidance (task 1476) — one place, unit-tested.
+  const failure = formatClaimFailure(r, taskId);
+  for (const line of failure.lines) console.error(line);
+  process.exit(failure.exit);
+}
+
+// Only auto-run when invoked directly (`node claim.js …`); a `require()` (the
+// unit test) just imports formatClaimFailure without executing the claim flow.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
     process.exit(1);
-  }
-  console.error(`Claim failed (${r.status}):`, r.data);
-  process.exit(1);
-})().catch((err) => {
-  console.error('fatal:', err);
-  process.exit(1);
-});
+  });
+}
+
+module.exports = { formatClaimFailure };

package/scripts/gds/claude-materialize.js

@@ -15,8 +15,9 @@
 // copy+transform. hooks/ + settings.json are TOPOLOGY (PROTECTED_TOPOLOGY_EXCLUDE) → NOT in the
 // package; this module copies+transforms them when they ARE present at the core root (today's single
 // checkout, and the core repo itself), and no-ops with a note when they aren't (an installed package).
-// Rewriting hook *.js internals + shipping a topology STARTER for a package-only install is a
-// follow-up (idea captured by task 1883) — this lands the skills materialization + the transform.
+// Hooks self-resolve their core require()s at RUNTIME via the copied _core-resolve.js sibling
+// (task 2139, the former W3 follow-up), so no require-path rewriting happens here; shipping a
+// topology STARTER for a package-only install (hooks absent at the core root) stays a follow-up (task 1883).
 //
 // SELF-COPY GUARD. When the instance dir IS the core root (running init inside the core checkout /
 // OTB today), there is nothing to materialize — a self-copy would be a no-op at best and corrupting
@@ -70,9 +71,9 @@ function bongosify(text, verbs = VERBS) {
 // branding objects, so no source host survives. Focused + FULL-HOST (a subdomain
 // like demo.cloudbongos.com is preserved), fail-open (a missing field drops that
 // one rule), a no-op when source == target, and it touches ONLY the copied output
-// (never the running source hooks). This does NOT rewrite hooks' internal
-// require('scripts/gds/…') paths for a package-only install — that stays the W3
-// follow-up; this lands the origin/config-dir neutralization.
+// (never the running source hooks). It does NOT rewrite hooks' internal
+// require('scripts/gds/…') paths — those self-resolve at runtime via the copied
+// _core-resolve.js sibling (task 2139); this rule lands the origin/config-dir neutralization.
 
 function reEsc(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 function hostOf(origin) { try { return new URL(String(origin)).host || null; } catch { return null; } }
@@ -214,7 +215,7 @@ function transformSettings(srcPath) {
 const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
 
 function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, settings: false, hooks: 0, skippedFiles: [], excludedSkills: [], rebrandRules: 0, claudeMd: false, notes: [] };
+  const summary = { skipped: false, skills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], rebrandRules: 0, claudeMd: false, notes: [] };
   if (path.resolve(instanceDir) === path.resolve(coreRoot)) {
     summary.skipped = true;
     summary.notes.push('instance dir is the core root — nothing to materialize (byte-identical no-op).');
@@ -273,8 +274,8 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   }
 
   // 3. hooks — topology; copied WITH an identity rebrand (their .js internals carried
-  //    the founder origin/config-dir). require('scripts/gds/…') path rewriting for a
-  //    package-only install stays the W3 follow-up.
+  //    the founder origin/config-dir). Their core require()s self-resolve at runtime via
+  //    the copied _core-resolve.js sibling (task 2139) — no path rewriting needed here.
   const hooksRes = copyTreeTransformed(path.join(srcClaude, 'hooks'), path.join(destClaude, 'hooks'), {
     dryRun, overwrite, transform: rebrand, textExt: HOOK_TEXT_EXT,
   });
@@ -284,7 +285,27 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     summary.notes.push('.claude/hooks not present at the core root (topology, excluded from the package) — provide them from a starter.');
   } else {
     log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${hooksRes.files} hook file(s) → .claude/hooks/ (founder identity rebranded)${left((hooksRes.skipped || []).length)}`);
-    summary.notes.push('hooks: founder origin/config-dir rebranded to this instance; their internal `require(scripts/gds/…)` paths are NOT yet rewritten to resolve inside the package (W3 follow-up).');
+    summary.notes.push('hooks: founder origin/config-dir rebranded to this instance; their internal `require(scripts/gds/…)` paths self-resolve inside the package at runtime via the copied _core-resolve.js sibling (task 2139).');
+  }
+
+  // 3b. scheduled-tasks — the cron routines (System 4 dispatcher, ADR 0078; task 2138). TOPOLOGY
+  //     like hooks (NOT in the package — PROTECTED_TOPOLOGY_EXCLUDE), so materialized by copy when
+  //     present at the core root and a no-op-with-note in a package-only install. Bodies (.md) are
+  //     bongosified so a judgment routine's `node scripts/gds/x.js` model-instructions become
+  //     `bongos exec …`; the deterministic routines' `.claude/scheduled-tasks/<x>.js` step commands
+  //     are NOT matched by bongosify and stay as-is. Companion .js are rebranded but keep their
+  //     paths: they resolve core require()s at runtime via the copied _core-resolve.js sibling
+  //     (task 2139), and run-routine.js finds the routines under resolveInstanceRoot() post-split.
+  const routinesRes = copyTreeTransformed(path.join(srcClaude, 'scheduled-tasks'), path.join(destClaude, 'scheduled-tasks'), {
+    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), textExt: HOOK_TEXT_EXT,
+  });
+  summary.scheduledTasks = routinesRes.files;
+  for (const rel of routinesRes.skipped || []) summary.skippedFiles.push(`scheduled-tasks/${rel}`);
+  if (!routinesRes.present) {
+    summary.notes.push('.claude/scheduled-tasks not present at the core root (topology, excluded from the package) — provide them from a starter.');
+  } else {
+    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${routinesRes.files} scheduled-task file(s) → .claude/scheduled-tasks/ (bodies→bongos, founder identity rebranded)${left((routinesRes.skipped || []).length)}`);
+    summary.notes.push('scheduled-tasks: cron routines materialized; run-routine.js resolves them under resolveInstanceRoot() and their companion .js resolve core via the copied _core-resolve.js sibling (task 2138).');
   }
 
   // 4. CLAUDE.md — the project-root framing an agent reads every session (task 2104).