@bongos/core 1.17.0

package/scripts/gds/publish-manifest.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/publish-manifest.js — the Cloud Bongos public-mirror PUBLISH BOUNDARY.
+// GDS-V4 R71 (task 1210), implementing ADR 0065 §4 + ADR 0062 §1. This is the single,
+// machine-readable source of truth for "what is publishable to the open-source mirror
+// vs permanently excluded." The delayed-export pipeline (R72/#1211) CONSUMES
+// isPublishable() to select the subtree it exports; the lineage/no-leak proof
+// (R73/#1212) ASSERTS that nothing the denylist forbids ever reached the mirror.
+//
+// DESIGN — default-deny, two-layer (see ADR 0098):
+//   1. PUBLISH_ALLOWLIST is the PRIMARY gate. A path publishes ONLY if it matches the
+//      allowlist — a file in no allowlisted subtree is silently NOT published. A new,
+//      unclassified top-level surface therefore never leaks by omission.
+//   2. PUBLISH_DENYLIST is a HARD override applied first (defense-in-depth): even a path
+//      that falls inside an allowlisted subtree is dropped if the denylist forbids it.
+//   isPublishable(p)  ==  matchesDeny(p) ? false : matchesAllow(p)
+//
+// REUSE, NEVER RE-TYPE (the task's explicit instruction; the gate-review.js doctrine):
+//   The three canonical sensitive-surface inventories are IMPORTED, never copied —
+//   PROTECTED_GLOBS (write-protection over trust/pipeline/infra code),
+//   HARD_FLOOR_GLOBS (the rank-independent escalate subset), and
+//   SENSITIVE_DOC_GLOBS (read-gating over the security/audit doc corpus).
+//   Critically, PROTECTED_GLOBS is NOT a denylist: ADR 0065 §4 PUBLISHES the
+//   trust-boundary / rank / ship-grade machinery as the open-source methodology core.
+//   Only the *topology* subset of the protected surfaces (prod infra, deploy, CI, the
+//   local gate hooks) is excluded — see PROTECTED_TOPOLOGY_EXCLUDE. tests/publish_manifest.mjs
+//   cross-checks the partition against the live inventory so it cannot silently drift.
+
+// The three canonical sensitive-surface inventories — imported from their homes,
+// NEVER re-typed (the gate-review.js "imported, never hand-retyped" doctrine). All
+// three are pure to require (no DB/network at load; their CLIs are require.main-guarded).
+const { PROTECTED_GLOBS, globToRegExp } = require('../../src/bongos/permission-path-check');
+const { HARD_FLOOR_GLOBS } = require('./gate-review');
+const { SENSITIVE_DOC_GLOBS } = require('./search-ingest-md');
+
+// ---------------------------------------------------------------------------
+// PUBLISH_ALLOWLIST — the portable core + platform (ADR 0065 §4 "Published",
+// ADR 0062 §1 core column). Subtree granularity: 1210 defines the BOUNDARY; R72
+// adds the file-level redaction of instance literals inside these subtrees.
+// ---------------------------------------------------------------------------
+const PUBLISH_ALLOWLIST = [
+  // --- the GDS platform + the instance-model engine ---
+  'src/',                 // platform engine + GDS core (the game residue is denied below)
+  'scripts/',             // build + methodology tooling (deploy is denied below)
+  'bin/',                 // the `cloudbongos`/`bongos` CLI entrypoint
+  'server.js',            // the single-process app entry
+  // --- the build system's shared schema + its tests ---
+  'migrations/',
+  'tests/',
+  // --- platform-core feature modules (engine; instance flavor comes from the brand pack) ---
+  'modules/lifecycle/',
+  'modules/grading/',
+  'modules/economy/',
+  'modules/memory/',
+  'modules/onboarding/',
+  'modules/ideas/',
+  'modules/builder-settings/',
+  'modules/sessions/',
+  'modules/autonomy/',
+  'modules/security/',
+  'modules/hall-ui/',
+  'modules/status-ui/',
+  'modules/dev-box/',
+  'modules/discord/',
+  // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---
+  'config/branding.neutral.json',
+  'config/modules.neutral.json',
+  'config/design-tokens.neutral.json',
+  'config/design-tokens.schema.json',  // the design-token contract (generic schema, no instance values)
+  'config/hierarchy.neutral.json',
+  // --- the portable methodology core, governance, and sanitized docs ---
+  'CLAUDE.md',
+  'README.md',
+  'LICENSE',
+  'GOVERNANCE.md',
+  'CONTRIBUTING.md',
+  'CODE_OF_CONDUCT.md',
+  'docs/adr/',                       // sanitized — ADR 0065 §4 "docs/ADRs (sanitized)"
+  'docs/recipes/',
+  'docs/design/',
+  'docs/research/',
+  'docs/architecture.md',
+  // Served to the hall / advertised by /api/bongos — a standalone that omits these
+  // renders broken onboarding + API-reference pages (task 2078). Redacted like the
+  // rest of this docs section; the diagrams' .png/.svg regenerate on the box.
+  'docs/onboarding/',                // primer.md + drachmae-and-karma.md + diagram sources (/builders/primer · /drachmae · /diagrams)
+  'docs/api/openapi.json',           // the generated OpenAPI 3.1 spec served at /docs/openapi.json
+  'docs/api-reference.md',           // the markdown API reference
+  'docs/modules-contract.md',
+  'docs/branding-contract.md',
+  'docs/branding-fill-prompt.md',
+  'docs/design-contract.md',
+  'docs/file-map.md',
+  'docs/repo-map.md',
+  'docs/handoff-template.md',         // the portable session-handoff format (methodology)
+  'docs/canonical-permissions.md',   // the rank-ladder reference IS the methodology (sanitized)
+  'docs/project-context.template.md', // the neutral scaffold `cloudbongos init` fills (NOT the OTB-filled one)
+  '.claude/skills/',                 // the methodology slash-commands (hooks/settings are denied below)
+  // --- container + repo scaffolding (examples only; real secrets are denied) ---
+  'Dockerfile',
+  'docker-compose.yml',
+  'docker-entrypoint.sh',
+  '.dockerignore',
+  '.devcontainer/',
+  '.env.local.example',
+  '.gitignore',
+  '.gitattributes',
+  'package.json',
+  'package-lock.json',
+  'public-landing/',
+  // --- served-at-runtime app assets a standalone MUST carry (task 2078) ---
+  // The generated typed API client is served at /lib/bongos-client.js as
+  // window.BongosClient; shell.js + builders.js call it at the TOP of every hall
+  // page, so its absence from the core package threw immediately and blanked the
+  // whole UI. Only the committed files publish — clients/bongos-client/dist/ is
+  // gitignored, so it never enters the git tree package-core reads.
+  'clients/bongos-client/',
+  'public-docs/',                    // the self-hosted API-reference site (/docs): Redoc host page + vendored renderer
+];
+
+// ---------------------------------------------------------------------------
+// PUBLISH_DENYLIST — hard exclusions, applied BEFORE the allowlist. Four rationales.
+// ---------------------------------------------------------------------------
+
+// (1) TOPOLOGY — the subset of the *protected* surfaces that is prod operational infra,
+//     the deploy machinery, CI, and the local gate hooks/settings. The REST of
+//     PROTECTED_GLOBS (auth, permission code, the grader, ship.js, migrations, CLAUDE.md…)
+//     is the trust/rank machinery that ADR 0065 §4 PUBLISHES. Every entry here MUST be a
+//     verbatim member of PROTECTED_GLOBS — tests/publish_manifest.mjs asserts it, so this
+//     list cannot drift out of sync with the live inventory.
+const PROTECTED_TOPOLOGY_EXCLUDE = [
+  'infra/',
+  'scripts/deploy/',
+  'config/deploy.json',
+  '.github/',
+  '.husky/',
+  '.claude/hooks/',
+  '.claude/settings.json',
+];
+
+// (2) READ-SENSITIVE DOCS — the security/audit corpus, derived from SENSITIVE_DOC_GLOBS.
+//     (canonical-permissions.md + the trust-boundary ADRs 0016/0043 are NOT excluded here:
+//      they are the methodology and publish sanitized — they live under the docs allowlist.)
+const SENSITIVE_DOC_EXCLUDE = SENSITIVE_DOC_GLOBS.filter(
+  (g) => g.startsWith('docs/security') || g.startsWith('docs/audits')
+);
+
+// (3) CONTENT / COPYRIGHT — the game and ALL art. art-pipeline carries the 83 ripped
+//     Pokémon FireRed reference maps (modules/art-pipeline/references/), an independent
+//     hard copyright reason to never publish the art subtree under an AGPL mirror.
+//     brand/ holds instance brand packs — including the customer-0 Cloud Bongos pack,
+//     whose publication is DEFERRED to R72/owner (excluded by default until then).
+const CONTENT_EXCLUDE = [
+  'modules/game/',
+  'modules/art-pipeline/',
+  'modules/character-anim/',
+  'art/',
+  'brand/',
+  'public/',                 // the game front-end (Phaser)
+  'src/world/',
+  'src/rooms/',
+  'src/preview-server.js',
+  // the art feature's CLI tooling lives under scripts/ (legacy top-level) but belongs
+  // to the excluded art module — exclude it with the feature it serves.
+  'scripts/art/',
+  'scripts/tile-add.js',
+  'scripts/tile-find.js',
+  'scripts/tile-recommend.js',
+];
+
+// (4) INSTANCE IDENTITY + HISTORY — this host's literals, ops config, build history, and
+//     local secrets. The neutral.* config twins and the *.template docs ARE published.
+const INSTANCE_EXCLUDE = [
+  // filled-in instance config (the *.neutral.* / *.template twins publish)
+  'config/branding.json',
+  'config/modules.json',
+  'config/devbox-app.json',
+  'config/hierarchy.json',
+  'CODEOWNERS',              // names the owner (a protected surface, excluded as identity)
+  // instance-specific docs + project history
+  'docs/project-context.md',
+  'docs/lore/',
+  'docs/session-logs/',
+  'docs/session-log-index.md',
+  'docs/session-log-archive.md',
+  'docs/handoffs/',
+  'docs/reviews/',
+  'docs/discord/',
+  'docs/google-chat-broadcast.md',
+  'docs/pms-v1-deploy.md',
+  'docs/graphics-stress-test-plan.md',
+  'docs/security-baseline.md',
+  'docs/routes-permissions.md',
+  'blockers/',
+  'limitations/',
+  'generative-ideas.md',
+  // local secrets / real env (the *.example publishes; the real files never do)
+  '.env',
+  '.env.local',
+  '.env.production',
+  '.claude/settings.local.json',
+  '.claude/worktrees/',
+];
+
+// (5) BUILD ARTIFACTS — generated bundles that live inside an allowlisted subtree.
+//     The committed clients/bongos-client/ files publish (task 2078); its dist/ is a
+//     gitignored rebuild output (so package-core never sees it) — deny it too so the
+//     boundary stays self-consistent if it is ever un-ignored (deny-wins layer).
+const BUILD_ARTIFACT_EXCLUDE = [
+  'clients/bongos-client/dist/',
+];
+
+const PUBLISH_DENYLIST = [
+  ...new Set([
+    ...PROTECTED_TOPOLOGY_EXCLUDE,
+    ...SENSITIVE_DOC_EXCLUDE,
+    ...CONTENT_EXCLUDE,
+    ...INSTANCE_EXCLUDE,
+    ...BUILD_ARTIFACT_EXCLUDE,
+  ]),
+];
+
+// ---------------------------------------------------------------------------
+// Matching — reuse the canonical glob→RegExp from permission-path-check so the publish
+// boundary speaks exactly the same glob dialect as the trust boundary (trailing '/' =
+// subtree, '**' across separators, '*' within a segment, otherwise an anchored literal).
+// ---------------------------------------------------------------------------
+const ALLOW_RE = PUBLISH_ALLOWLIST.map(globToRegExp);
+const DENY_RE = PUBLISH_DENYLIST.map(globToRegExp);
+
+// Normalize a path the way git reports it (forward slashes, no leading './').
+function normalize(p) {
+  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim();
+}
+
+function matchesAny(relPath, regexes) {
+  const f = normalize(relPath);
+  if (!f) return false;
+  return regexes.some((re) => re.test(f));
+}
+
+const matchesAllow = (relPath) => matchesAny(relPath, ALLOW_RE);
+const matchesDeny = (relPath) => matchesAny(relPath, DENY_RE);
+
+// Is this repo-relative path eligible for the public mirror? Deny wins; default-deny.
+function isPublishable(relPath) {
+  const f = normalize(relPath);
+  if (!f) return false;
+  if (matchesDeny(f)) return false;
+  return matchesAllow(f);
+}
+
+// Split a list of repo-relative paths into { publish, exclude }. The shape R72's export
+// pipeline iterates and R73's proof audits.
+function partitionPaths(relPaths) {
+  const publish = [];
+  const exclude = [];
+  for (const p of relPaths || []) {
+    (isPublishable(p) ? publish : exclude).push(normalize(p));
+  }
+  return { publish, exclude };
+}
+
+module.exports = {
+  PUBLISH_ALLOWLIST,
+  PUBLISH_DENYLIST,
+  PROTECTED_TOPOLOGY_EXCLUDE,
+  SENSITIVE_DOC_EXCLUDE,
+  CONTENT_EXCLUDE,
+  INSTANCE_EXCLUDE,
+  isPublishable,
+  matchesAllow,
+  matchesDeny,
+  partitionPaths,
+  normalize,
+  // re-exported so consumers + the test see the exact inventories this manifest reused
+  PROTECTED_GLOBS,
+  HARD_FLOOR_GLOBS,
+  SENSITIVE_DOC_GLOBS,
+};
+
+// CLI: `node scripts/gds/publish-manifest.js <path> [<path> …]` prints publish|exclude
+// per path; `--list` prints the allowlist + denylist. A quick human/debug surface; R72
+// imports the functions above rather than shelling out.
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log('usage: node scripts/gds/publish-manifest.js <repo-relative-path> [...]   # classify paths');
+    console.log('       node scripts/gds/publish-manifest.js --list                       # print the boundary');
+    process.exit(args.length === 0 ? 2 : 0);
+  }
+  if (args[0] === '--list') {
+    console.log('PUBLISH_ALLOWLIST:');
+    for (const g of PUBLISH_ALLOWLIST) console.log(`  + ${g}`);
+    console.log('\nPUBLISH_DENYLIST:');
+    for (const g of PUBLISH_DENYLIST) console.log(`  - ${g}`);
+    process.exit(0);
+  }
+  let anyExcluded = false;
+  for (const p of args) {
+    const ok = isPublishable(p);
+    if (!ok) anyExcluded = true;
+    console.log(`${ok ? 'publish' : 'exclude'}\t${normalize(p)}`);
+  }
+  process.exit(anyExcluded ? 1 : 0);
+}

package/scripts/gds/pulse.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// Fire-and-forget heartbeat for an active GDS claim, plus the stale-claim
+// auto-release sweeper. Two distinct modes share this file because both
+// concern the session_pulses table:
+//
+//   1) Pulse mode (default) — POST a single heartbeat for one claim. Used
+//      by a background process while a builder works.
+//        node scripts/gds/pulse.js --claim-id <N>
+//
+//   2) Release-stale mode (V3.R49 / #268) — scan for active claims with
+//      no pulse in N hours and auto-release them. Used by the
+//      `stale-claim-release` scheduled task (runs every 15 min on the
+//      droplet) and runnable by hand for ops.
+//        node scripts/gds/pulse.js --release-stale [--threshold-hours 6] [--dry-run]
+//
+// -------------------------------------------------------------------------
+// Pulse-mode follow-up note (unchanged from original):
+//   POST /api/gds/pulse is NOT yet wired (route lives in src/bongos/routes.js,
+//   which is OUT of THAT task's touches[]). Once a follow-up task adds
+//   the route, the pulse path starts working with no changes. Until then,
+//   running it will print a 404 from the server — that is expected.
+//
+// -------------------------------------------------------------------------
+// Release-stale-mode notes (V3.R49):
+//   - Threshold is HOURS by default (env var GDS_STALE_CLAIM_HOURS, default
+//     6). The underlying sweepStaleClaims() helper takes minutes; we convert.
+//   - We talk to Postgres directly via the existing src/db.js pool (peer auth
+//     on the droplet). No HTTP session needed — this routine ships with the
+//     server and runs in the same trust boundary.
+//   - claims.outcome and session_logs.outcome are both DB-constrained to
+//     ('shipped', 'partial', 'abandoned') / ('shipped', 'abandoned', 'partial',
+//     'expired'). We do NOT add a new 'abandoned-stale' enum value (the task's
+//     touches[] excludes migrations/ — adding one is a separate follow-up).
+//     Instead we set outcome='abandoned' AND tag the audit trail in notes_md
+//     with a stable [auto-released:stale] prefix so the case is discoverable
+//     by anyone reading the log or grepping the table.
+//   - Tasks return to status='ready', no credits, just like a manual release.
+//   - Affected builders get one broadcast each via scripts/discord/post.js
+//     (Discord #ship-news — outbound moved off Google Chat per ADR 0032 /
+//     #607; scripts/chat/ is inbound-only now). Post failure is non-fatal
+//     (mirrors ship.js).
+//   - Exit codes: 0 = success (including "nothing stale"); 1 = fatal error.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+
+// Lazy require — only when release-stale mode is engaged, so the lightweight
+// pulse path doesn't pull in pg unless needed (e.g. when invoked from a non-
+// droplet machine without Postgres reachable).
+function loadDeps() {
+  // eslint-disable-next-line global-require
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  // eslint-disable-next-line global-require
+  // pulse.js (the lib) carved → modules/sessions/ (BV1.R82 / ADR 0093 §1); the CLI
+  // shell stays here and requires the module lib directly (scripts are outside the
+  // kernel boundary, so a direct module require is fine).
+  const { sweepStaleClaims } = require(path.join(REPO_ROOT, 'modules/sessions/pulse'));
+  return { pool, sweepStaleClaims };
+}
+
+function parseThresholdHours(args) {
+  const cliVal = arg('--threshold-hours', args);
+  if (cliVal != null) {
+    const n = Number(cliVal);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new Error(`--threshold-hours must be a positive number (got ${cliVal})`);
+    }
+    return n;
+  }
+  if (process.env.GDS_STALE_CLAIM_HOURS) {
+    const n = Number(process.env.GDS_STALE_CLAIM_HOURS);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new Error(`GDS_STALE_CLAIM_HOURS must be a positive number (got "${process.env.GDS_STALE_CLAIM_HOURS}")`);
+    }
+    return n;
+  }
+  return 6;
+}
+
+// Post a single broadcast about an auto-released claim. Best-effort —
+// returns { ok, error } and never throws. Mirrors the pattern in ship.js
+// (synchronous execFile via the local scripts/discord/post.js helper —
+// default channel ship_news; outbound moved off Google Chat per ADR 0032).
+function postDiscordPing(text) {
+  try {
+    execFileSync('node', ['scripts/discord/post.js', text], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+    });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+async function releaseStale({ thresholdHours, dryRun }) {
+  const { pool, sweepStaleClaims } = loadDeps();
+  const thresholdMin = Math.round(thresholdHours * 60);
+
+  let stale;
+  try {
+    stale = await sweepStaleClaims({ thresholdMin });
+  } catch (e) {
+    console.error('sweepStaleClaims failed:', e.message);
+    await pool.end().catch(() => {});
+    process.exit(1);
+  }
+
+  const header =
+    `stale-claim sweep (threshold=${thresholdHours}h / ${thresholdMin}m` +
+    `${dryRun ? ', dry-run' : ''}): ${stale.length} claim(s) eligible`;
+  console.log(header);
+
+  if (stale.length === 0) {
+    await pool.end().catch(() => {});
+    return;
+  }
+
+  const NOTE_TAG = '[auto-released:stale]';
+
+  const results = [];
+  for (const row of stale) {
+    const { claim_id, task_id, builder_id, claimed_at, last_pulse_at } = row;
+    const lastSeen = last_pulse_at
+      ? `last pulse at ${new Date(last_pulse_at).toISOString()}`
+      : `never pulsed (claimed at ${new Date(claimed_at).toISOString()})`;
+
+    if (dryRun) {
+      console.log(
+        `  would release claim #${claim_id} (task #${task_id}, builder #${builder_id}) — ${lastSeen}`
+      );
+      results.push({ claim_id, task_id, builder_id, status: 'dry-run' });
+      continue;
+    }
+
+    const client = await pool.connect();
+    let outcome;
+    try {
+      await client.query('BEGIN');
+
+      // Lock the claim row and re-check it's still open. If a real release
+      // raced us between the sweep query and now, skip it.
+      const { rows: cur } = await client.query(
+        `SELECT c.id, c.task_id, c.builder_id, c.claimed_at, c.released_at,
+                t.title
+           FROM claims c JOIN tasks t ON t.id = c.task_id
+          WHERE c.id = $1
+          FOR UPDATE`,
+        [claim_id]
+      );
+      if (cur.length === 0) {
+        await client.query('ROLLBACK');
+        results.push({ claim_id, task_id, builder_id, status: 'skip-missing' });
+        continue;
+      }
+      if (cur[0].released_at) {
+        await client.query('ROLLBACK');
+        results.push({ claim_id, task_id, builder_id, status: 'skip-already-released' });
+        continue;
+      }
+
+      const taskTitle = cur[0].title;
+      const claimedAtSql = cur[0].claimed_at;
+      const notesMd =
+        `${NOTE_TAG} session_pulses heartbeat went silent for ` +
+        `>= ${thresholdHours}h (threshold ${thresholdMin}m). ` +
+        (last_pulse_at
+          ? `Last pulse: ${new Date(last_pulse_at).toISOString()}.`
+          : `No pulse ever recorded; claimed_at ${new Date(claimedAtSql).toISOString()}.`) +
+        ' Claim auto-released; task returned to status=ready, no credits awarded.';
+
+      // Release the claim. outcome='abandoned' is the closest existing enum
+      // value (DB CHECK constraint blocks new values without a migration —
+      // see header note). The [auto-released:stale] tag in notes_md is the
+      // discoverability hook.
+      await client.query(
+        `UPDATE claims SET released_at = now(), outcome = 'abandoned' WHERE id = $1`,
+        [claim_id]
+      );
+
+      // Send the task back to ready (same map as release.js).
+      await client.query(
+        `UPDATE tasks
+            SET status = 'ready',
+                updated_at = now()
+          WHERE id = $1`,
+        [task_id]
+      );
+
+      // Write the session_logs entry so the audit trail is complete.
+      await client.query(
+        `INSERT INTO session_logs (builder_id, task_id, claim_id, started_at, ended_at, outcome, notes_md)
+         VALUES ($1, $2, $3, $4, now(), 'abandoned', $5)`,
+        [builder_id, task_id, claim_id, claimedAtSql, notesMd]
+      );
+
+      await client.query('COMMIT');
+
+      outcome = { task_id, builder_id, taskTitle, lastSeen };
+      console.log(
+        `  released claim #${claim_id} (task #${task_id} "${taskTitle}", builder #${builder_id}) — ${lastSeen}`
+      );
+    } catch (e) {
+      await client.query('ROLLBACK').catch(() => {});
+      console.error(`  release failed for claim #${claim_id}:`, e.message);
+      results.push({ claim_id, task_id, builder_id, status: 'error', error: e.message });
+      continue;
+    } finally {
+      client.release();
+    }
+
+    // Look up the builder's display name (display_name / github_login) for
+    // the broadcast. Outside the transaction — read-only and tolerant of
+    // missing rows.
+    let builderName = `builder #${builder_id}`;
+    try {
+      const { rows } = await pool.query(
+        `SELECT COALESCE(display_name, github_login, 'builder #' || id) AS name
+           FROM builders WHERE id = $1`,
+        [builder_id]
+      );
+      if (rows.length > 0) builderName = rows[0].name;
+    } catch (_) {
+      /* fall through with default */
+    }
+
+    const msg =
+      `@${builderName} your claim on task #${outcome.task_id} ` +
+      `("${outcome.taskTitle}") was auto-released because the session ` +
+      `heartbeat went silent for >= ${thresholdHours}h. ` +
+      `No credits awarded. Task is back to ready — reclaim with ` +
+      `\`/builder-claim ${outcome.task_id}\` if you're back.`;
+
+    const ping = postDiscordPing(msg);
+    if (!ping.ok) {
+      console.log(`    Discord ping FAILED (non-blocking): ${ping.error}`);
+      results.push({ claim_id, ...outcome, status: 'released-ping-failed', ping_error: ping.error });
+    } else {
+      results.push({ claim_id, ...outcome, status: 'released' });
+    }
+  }
+
+  const summary = {
+    released: results.filter((r) => r.status === 'released').length,
+    released_ping_failed: results.filter((r) => r.status === 'released-ping-failed').length,
+    skipped: results.filter((r) => r.status.startsWith('skip-')).length,
+    errors: results.filter((r) => r.status === 'error').length,
+    dry_run: results.filter((r) => r.status === 'dry-run').length,
+  };
+  console.log(`done — released=${summary.released} ping-failed=${summary.released_ping_failed} skipped=${summary.skipped} errors=${summary.errors} dry-run=${summary.dry_run}`);
+
+  await pool.end().catch(() => {});
+}
+
+(async () => {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--release-stale')) {
+    let thresholdHours;
+    try {
+      thresholdHours = parseThresholdHours(args);
+    } catch (e) {
+      console.error(e.message);
+      process.exit(1);
+    }
+    const dryRun = args.includes('--dry-run');
+    await releaseStale({ thresholdHours, dryRun });
+    return;
+  }
+
+  // ----- pulse mode (unchanged) -----
+  await requireSession();
+  const claimIdStr = arg('--claim-id', args);
+  const claimId = claimIdStr ? Number(claimIdStr) : NaN;
+  if (!Number.isFinite(claimId)) {
+    console.error('usage:');
+    console.error('  node scripts/gds/pulse.js --claim-id <N>');
+    console.error('  node scripts/gds/pulse.js --release-stale [--threshold-hours H] [--dry-run]');
+    process.exit(1);
+  }
+
+  // POST /pulse is a non-spec route (not in the generated client) — use the
+  // escape hatch, which honors the same { status, ok, data } contract.
+  const api = await cliClient();
+  const r = await api.request('POST', '/pulse', { body: { claim_id: claimId } });
+  if (!r.ok) {
+    // Fire-and-forget: log the diagnostic but do not fail.
+    // Until the /api/gds/pulse route is mounted, this routinely returns 404.
+    console.error(`pulse non-ok (status ${r.status}):`, r.data);
+    process.exit(0);
+  }
+  console.log(`pulse ok for claim #${claimId}`);
+})().catch((err) => {
+  // pulse mode is fire-and-forget — never break the foreground workflow.
+  // release-stale mode handles its own errors above and only reaches here
+  // on an unexpected throw (e.g. a syntax bug). Exit 0 so a CLI-mode pulse
+  // never propagates a failure to the foreground caller.
+  console.error('pulse error:', err && err.message ? err.message : err);
+  process.exit(0);
+});
+
+// Quiet the "unused" lint signal if fs/path ever get tree-shaken in CI.
+void fs;
+void path;

package/scripts/gds/push-main.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// scripts/gds/push-main.js — the ONE sanctioned client-side push to `main`.
+//
+// This is the deploy step of the GRADED GDS pipeline: ship.js's auto-merge and
+// /merge-mode call it after a task has passed the grader + the Archon-only
+// confirm gate. It carries the OTB_ALLOW_MAIN_PUSH override so the SEC #863
+// pre-push hook lets the legitimate, already-gated pipeline land main while
+// still blocking an ad-hoc `git push origin main` (the Builder 25 move).
+//
+// NOT a security boundary — anyone could run this script, just as anyone could
+// `git push --no-verify`. The enforcement is the POST-push main audit
+// (scripts/gds/main-audit.js, ADR 0043): it reads the real git history + real
+// builder ranks server-side and reverts un-graded / sub-Metic-permission-path
+// commits regardless of HOW they were pushed. push-main.js only distinguishes
+// "the pipeline's deploy push" from "a human bypassing the pipeline" so the
+// hook's friction lands on the latter.
+//
+// Under FULL Option A (server-side merge+deploy, gated behind SERVER_SIDE_DEPLOY
+// — see ADR 0043 + blockers), this client-side push goes away entirely and
+// builders never hold main-push at all.
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+function pushMain(extra = []) {
+  execFileSync('git', ['push', 'origin', 'main', ...extra], {
+    stdio: 'inherit',
+    env: { ...process.env, OTB_ALLOW_MAIN_PUSH: '1' },
+    shell: false,
+  });
+}
+
+// Only push when run directly — never on require (requiring this file must not
+// trigger a push). ship.js / merge-mode invoke it as `node push-main.js`.
+if (require.main === module) {
+  try {
+    pushMain(process.argv.slice(2)); // optional extra args (rare; e.g. --force-with-lease)
+    process.exit(0);
+  } catch (_) {
+    process.exit(1);
+  }
+}
+
+module.exports = { pushMain };