@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/smoke-claim-consistency.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# GDS claim-consistency smoke test (production). Renamed from PMS in V3.R01.
+#
+# Enforces criterion 7 of pms-v2.md: every surface that lists "your active
+# claims" must read from the canonical helper (src/bongos/active-claims.js)
+# and therefore return identical claim sets in identical order.
+#
+# Strategy:
+#   1. Create 2 disjoint __smoke__ tasks
+#   2. Claim both as the same builder
+#   3. Hit every consumer surface that currently exists:
+#        - GET /api/bongos/me                              (always present)
+#        - GET /api/bongos/builders/me   (PMS-V2 P6)       (capability-gated)
+#      The /builder-start and /builder-session CLIs render server data;
+#      they do not constitute independent surfaces in the sense of
+#      criterion 7 (they consume /api/bongos/* responses). We assert at the
+#      API boundary, which is where the bug class lives.
+#   4. Extract the ordered (task_id) sequence from each surface
+#   5. Assert all surfaces return identical sequences
+#   6. Release both claims, surfaces are cleaned up by the task lifecycle
+#
+# Surfaces that 404 are AUTO-SKIPPED so the smoke test passes against
+# current production even before PMS-V2 P6 lands. A summary line records
+# which surfaces were checked vs skipped.
+#
+# TODO: once PMS-V2 P6 (#48 — /builders web profile) ships, the
+# /api/bongos/builders/me surface will start returning 200 and this smoke
+# will automatically include it. No edits needed here.
+#
+# Usage:
+#   bash scripts/bongos/smoke-claim-consistency.sh
+# Optional env:
+#   GDS_API_BASE / PMS_API_BASE  override the API host (default: this instance's own,
+#                                resolved from the session + branding pack — see lib.sh)
+
+set -euo pipefail
+
+# shellcheck source=scripts/bongos/lib.sh
+source "$(dirname "$0")/lib.sh"
+
+API="$(gds_api_base)"
+TOKEN="$(gds_resolve_token)" || exit $?
+
+ts=$(date +%Y%m%d-%H%M%S)
+SMOKE_TITLE_A="__smoke__ claim-consistency-A ${ts}"
+SMOKE_TITLE_B="__smoke__ claim-consistency-B ${ts}"
+
+call() {
+  local method="$1" path="$2" body="${3:-}"
+  local args=(-sS -X "${method}" -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -w "\n%{http_code}")
+  if [[ -n "${body}" ]]; then args+=(-d "${body}"); fi
+  local out
+  out=$(curl "${args[@]}" "${API}${path}")
+  local code="${out##*$'\n'}"
+  local payload="${out%$'\n'*}"
+  echo "${payload}"
+  if [[ "${code}" -ge 300 ]]; then
+    echo "FAIL: ${method} ${path} -> HTTP ${code}" >&2
+    return 1
+  fi
+}
+
+# Returns the HTTP status code for a GET to PATH. Used for capability gating.
+probe_status() {
+  local path="$1"
+  curl -sS -o /dev/null -w "%{http_code}" \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "${API}${path}"
+}
+
+# Extract sorted task_id list from a JSON payload at a given JSON path.
+# Args: <payload> <python-extract-expr-returning-list-of-ints>
+extract_ids() {
+  local payload="$1" expr="$2"
+  echo "${payload}" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+ids = ${expr}
+print(','.join(str(x) for x in ids))
+"
+}
+
+create_task() {
+  local title="$1" suffix="$2"
+  local body
+  body=$(python3 -c "
+import json
+print(json.dumps({
+  'version_id': '${VERSION_ID}',
+  'title': '${title}',
+  'description': 'Synthetic smoke task. Auto-cleaned by smoke-claim-consistency.sh.',
+  'status': 'ready',
+  'touches': ['__smoke__/claim-consistency/${ts}/${suffix}'],
+  'est_minutes': 1,
+  'manual_degree': 1,
+  'priority': 5,
+  'automation_tag': 'overnight-safe',
+  'credits_reward': 0,
+  'source': 'smoke',
+  'source_ref': 'consistency-${ts}-${suffix}'
+}))
+")
+  local out
+  out=$(call POST /api/bongos/tasks "${body}")
+  echo "${out}" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['id'])"
+}
+
+claim_task() {
+  local task_id="$1"
+  local body
+  body=$(python3 -c "import json; print(json.dumps({'task_id': ${task_id}, 'worktree_name': '__smoke__'}))")
+  local out
+  out=$(call POST /api/bongos/claims "${body}")
+  echo "${out}" | python3 -c "import json,sys; print(json.load(sys.stdin)['claim']['id'])"
+}
+
+release_claim() {
+  local claim_id="$1"
+  call POST "/api/bongos/claims/${claim_id}/resolve" '{"outcome":"abandoned","notes_md":"smoke cleanup"}' >/dev/null || true
+}
+
+echo "=== GDS claim-consistency smoke test ==="
+echo "API: ${API}"
+echo "Titles: ${SMOKE_TITLE_A} | ${SMOKE_TITLE_B}"
+echo
+
+# task 1003166 (G02): resolve the version at RUNTIME. This file used to hardcode
+# one; that version shipped, `version_closed` refused every create, and the smoke
+# could not pass while /merge-mode still advertised it green (idea 1000823).
+VERSION_ID=$(node "$(dirname "$0")/version-select.js") || {
+  echo "FAIL: could not resolve a building version — see version-select.js" >&2
+  exit 1
+}
+echo "Version: ${VERSION_ID}"
+
+echo "--- 1. create 2 smoke tasks ---"
+TASK_A=$(create_task "${SMOKE_TITLE_A}" "A")
+TASK_B=$(create_task "${SMOKE_TITLE_B}" "B")
+echo "task A=#${TASK_A}  task B=#${TASK_B}"
+
+# Always clean up on exit, even if assertions fail.
+CLAIM_A=""
+CLAIM_B=""
+cleanup() {
+  local rc=$?
+  echo
+  echo "--- cleanup ---"
+  [[ -n "${CLAIM_A}" ]] && release_claim "${CLAIM_A}" && echo "released claim ${CLAIM_A}"
+  [[ -n "${CLAIM_B}" ]] && release_claim "${CLAIM_B}" && echo "released claim ${CLAIM_B}"
+  exit "${rc}"
+}
+trap cleanup EXIT
+
+echo
+echo "--- 2. claim both as same builder (A first, then B) ---"
+CLAIM_A=$(claim_task "${TASK_A}")
+# Tiny pause so claimed_at differs and ordering is unambiguous.
+sleep 1
+CLAIM_B=$(claim_task "${TASK_B}")
+echo "claim A=#${CLAIM_A}  claim B=#${CLAIM_B}"
+
+EXPECTED="${TASK_A},${TASK_B}"
+echo "expected ordered task_ids: ${EXPECTED}"
+
+echo
+echo "--- 3. probe each surface, extract ordered task_id sequence ---"
+checked=0
+skipped=0
+fail=0
+
+# Surface 1: /api/bongos/me — always present.
+ME_PAYLOAD=$(call GET /api/bongos/me)
+ME_IDS=$(extract_ids "${ME_PAYLOAD}" "[c['task_id'] for c in data.get('active_claims', [])]")
+# Filter to just our 2 smoke task_ids in case the builder has other live claims.
+ME_FILTERED=$(python3 -c "
+ids = '${ME_IDS}'.split(',') if '${ME_IDS}' else []
+keep = [x for x in ids if x in ('${TASK_A}', '${TASK_B}')]
+print(','.join(keep))
+")
+echo "/api/bongos/me                 -> ${ME_FILTERED}"
+if [[ "${ME_FILTERED}" == "${EXPECTED}" ]]; then
+  echo "  PASS /api/bongos/me ordering matches"
+  checked=$((checked+1))
+else
+  echo "  FAIL /api/bongos/me ordering mismatch (expected ${EXPECTED}, got ${ME_FILTERED})"
+  fail=1
+fi
+
+# Surface 2: /api/bongos/builders/me — PMS-V2 P6, capability-gated.
+BUILDERS_ME_CODE=$(probe_status /api/bongos/builders/me)
+if [[ "${BUILDERS_ME_CODE}" == "200" ]]; then
+  BME_PAYLOAD=$(call GET /api/bongos/builders/me)
+  # Try both common shapes: top-level active_claims, or nested under builder/profile.
+  BME_IDS=$(extract_ids "${BME_PAYLOAD}" "[c['task_id'] for c in (data.get('active_claims') or data.get('builder', {}).get('active_claims') or data.get('profile', {}).get('active_claims') or [])]")
+  BME_FILTERED=$(python3 -c "
+ids = '${BME_IDS}'.split(',') if '${BME_IDS}' else []
+keep = [x for x in ids if x in ('${TASK_A}', '${TASK_B}')]
+print(','.join(keep))
+")
+  echo "/api/bongos/builders/me        -> ${BME_FILTERED}"
+  if [[ "${BME_FILTERED}" == "${EXPECTED}" ]]; then
+    echo "  PASS /api/bongos/builders/me ordering matches /api/bongos/me"
+    checked=$((checked+1))
+  else
+    echo "  FAIL /api/bongos/builders/me ordering mismatch (expected ${EXPECTED}, got ${BME_FILTERED})"
+    fail=1
+  fi
+else
+  echo "/api/bongos/builders/me        -> HTTP ${BUILDERS_ME_CODE} (SKIP — PMS-V2 P6 not live yet)"
+  skipped=$((skipped+1))
+fi
+
+echo
+echo "--- summary ---"
+echo "surfaces checked: ${checked}"
+echo "surfaces skipped: ${skipped}"
+if [[ "${fail}" -eq 0 ]]; then
+  echo "OK: claim-consistency smoke passed (task A=#${TASK_A}, task B=#${TASK_B})"
+else
+  echo "FAIL: one or more surfaces disagreed on active-claims ordering"
+fi
+exit "${fail}"

package/scripts/bongos/smoke-dependencies.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Smoke test for the dependency + auto-promotion system (ADR 0015 / migration 020).
+#
+# Round-trip:
+#   1. Create task A with status='backlog', kind='feature'
+#   2. Create task B with status='ready'
+#   3. Wire A.dependencies = [B]    (A's status stays backlog — auto-promotion only
+#                                    fires when B SHIPS, not when the edge is added)
+#   4. Try to claim A — must fail 409 DEPS_NOT_SHIPPED (manual promote test)
+#   5. Promote A manually (the route allows it; the gate is at claim time)
+#   6. Try to claim A — still 409 DEPS_NOT_SHIPPED
+#   7. Claim B, ship B (active → completed → confirmed → shipped)
+#   8. Verify C — a second dependent of B that NOTHING ever promoted by hand —
+#      flipped backlog→ready. This is the only assertion that can fail if the
+#      auto-promotion trigger is broken (task 1004191): A was already 'ready'
+#      from the manual step, so A's status proves nothing about the trigger.
+#   9. Claim A — succeeds
+#  10. Release A, abandon A and C (B is shipped and cannot be abandoned)
+#
+# Run from any environment with a valid CLI session (/builder-setup).
+# Requires curl.
+set -euo pipefail
+
+# Token + API base both come from lib.sh, which resolves them through
+# instance-config the way every /builder-* command does. The literals that used
+# to live here were doubly broken: a macOS-only /Users/$USER path and a baked-in
+# founder host, so this smoke could not run on any other OS or instance
+# (task 1002567).
+# shellcheck source=scripts/bongos/lib.sh
+source "$(dirname "$0")/lib.sh"
+
+TOKEN="$(gds_resolve_token)" || exit $?
+BASE="${GDS_BASE:-$(gds_api_base)}"
+SUFFIX="$(date +%s)"
+
+echo "=== 1. Create task B (depends-on target, status=ready) ==="
+B=$(curl -sS -X POST "$BASE/api/bongos/tasks" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data "{\"version_id\":\"GDS-V3\",\"title\":\"__smoke__ dep-test B $SUFFIX\",\"description\":\"smoke\",\"status\":\"ready\",\"kind\":\"feature\",\"discipline\":\"engineering\",\"priority\":5,\"touches\":[\"smoke-dep-B-$SUFFIX/\"],\"source\":\"smoke\",\"source_ref\":\"smoke-dep-B-$SUFFIX\"}")
+B_ID=$(echo "$B" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['id'])")
+echo "  B id=$B_ID"
+
+echo "=== 2. Create task A (dependent, status=backlog) ==="
+A=$(curl -sS -X POST "$BASE/api/bongos/tasks" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data "{\"version_id\":\"GDS-V3\",\"title\":\"__smoke__ dep-test A $SUFFIX\",\"description\":\"smoke\",\"status\":\"backlog\",\"kind\":\"feature\",\"discipline\":\"engineering\",\"priority\":5,\"touches\":[\"smoke-dep-A-$SUFFIX/\"],\"source\":\"smoke\",\"source_ref\":\"smoke-dep-A-$SUFFIX\"}")
+A_ID=$(echo "$A" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['id'])")
+echo "  A id=$A_ID"
+
+echo "=== 2b. Create task C (dependent, status=backlog, NEVER promoted by hand) ==="
+# task 1004191 (finding 62 of the task 1000379 audit): A is promoted manually in
+# step 4, so "A is ready after B ships" held whether or not the auto-promotion
+# trigger fired. C exists to be the dependent only the trigger can flip.
+C=$(curl -sS -X POST "$BASE/api/bongos/tasks" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data "{\"version_id\":\"GDS-V3\",\"title\":\"__smoke__ dep-test C $SUFFIX\",\"description\":\"smoke\",\"status\":\"backlog\",\"kind\":\"feature\",\"discipline\":\"engineering\",\"priority\":5,\"touches\":[\"smoke-dep-C-$SUFFIX/\"],\"source\":\"smoke\",\"source_ref\":\"smoke-dep-C-$SUFFIX\"}")
+C_ID=$(echo "$C" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['id'])")
+echo "  C id=$C_ID"
+
+echo "=== 3. Wire A → depends_on B, and C → depends_on B ==="
+curl -sS -X POST "$BASE/api/bongos/tasks/$C_ID/dependencies" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data "{\"depends_on_task_id\": $B_ID}" >/dev/null
+C_PRE=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/bongos/tasks/$C_ID" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['status'])")
+[ "$C_PRE" = "backlog" ] && echo "  PASS: C is backlog before B ships" || (echo "  FAIL: C is '$C_PRE' before B ships — the auto-promotion check below would prove nothing"; exit 1)
+curl -sS -X POST "$BASE/api/bongos/tasks/$A_ID/dependencies" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data "{\"depends_on_task_id\": $B_ID}" | python3 -m json.tool
+
+echo "=== 4. Manually promote A (testing claim-time gate, not auto-promote) ==="
+curl -sS -X POST "$BASE/api/bongos/tasks/$A_ID/promote" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
+
+echo "=== 5. Attempt claim A — MUST 409 DEPS_NOT_SHIPPED ==="
+CLAIM_RESP=$(curl -sS -X POST "$BASE/api/bongos/claims" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data "{\"task_id\": $A_ID, \"worktree_name\": \"smoke-$SUFFIX\"}")
+echo "$CLAIM_RESP" | python3 -m json.tool
+echo "$CLAIM_RESP" | grep -q "DEPS_NOT_SHIPPED" && echo "  PASS: claim refused with DEPS_NOT_SHIPPED" || (echo "  FAIL: claim was not refused"; exit 1)
+
+echo "=== 6. Claim + ship B (the dep) ==="
+node scripts/bongos/claim.js "$B_ID" --worktree "smoke-$SUFFIX-B"
+# Move through completed → confirmed → shipped using direct API calls (skip the
+# scanner/grader by going straight at /resolve + /confirm + /ship)
+curl -sS -X POST "$BASE/api/bongos/claims/by-task/$B_ID/resolve" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data '{"outcome":"completed","verification":{"passed":true,"smoke_ok":true}}' >/dev/null
+curl -sS -X POST "$BASE/api/bongos/tasks/$B_ID/confirm" -H "Authorization: Bearer $TOKEN" >/dev/null
+curl -sS -X POST "$BASE/api/bongos/tasks/$B_ID/ship"    -H "Authorization: Bearer $TOKEN" >/dev/null
+
+echo "=== 7. Verify the auto-promotion trigger fired: C backlog → ready ==="
+# C was never promoted by hand, so only promote_dependents_on_ship can have made
+# it 'ready'. (A is 'ready' from the manual step 4 regardless, so A is not asserted
+# here — that is the assertion that used to pass with the trigger broken.)
+C_STATUS=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/bongos/tasks/$C_ID" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['status'])")
+echo "  C status: $C_STATUS"
+[ "$C_STATUS" = "ready" ] && echo "  PASS: C auto-promoted" || (echo "  FAIL: C is '$C_STATUS' — B shipped but the auto-promotion trigger did not flip its dependent"; exit 1)
+
+echo "=== 8. Claim A — must succeed now ==="
+node scripts/bongos/claim.js "$A_ID" --worktree "smoke-$SUFFIX-A"
+
+echo "=== 9. Cleanup — abandon A and C; B is shipped and stays ==="
+# task 1004026: this step used to ANNOUNCE "release A; mark both abandoned" and then
+# only release A. Neither task reached a terminal state, so every run leaked two
+# __smoke__ rows into the live tasks table — invisibly, because anyone grepping the
+# cleanup step read a line saying both were handled.
+#
+# "mark both abandoned" was never possible. B is SHIPPED by step 6, and the abandon
+# route refuses shipped work (cannot_abandon_shipped) because shipped rows are
+# immutable history. Only A can reach a terminal state here, so the echo now states
+# what the code does instead of the reverse.
+#
+# Follows scripts/bongos/smoke-write.sh's cleanup (task 1002018): abandon is the right
+# terminal state for a smoke row, and cleanup is STRICTLY best-effort. task.abandon is
+# floor-metic (ADR 0152), so a Xenos/Thetes token gets a 403 here while every assertion
+# above genuinely passed — a cleanup that cannot run must never turn a passing smoke
+# into a failing one. Hence the `|| true` and the reported-not-raised status codes.
+# Reaching this line at all means every assertion passed: the script is `set -e` and
+# each check above exits non-zero on failure, so a FAILED run stops earlier and leaves
+# both rows in place for inspection, which is the same deliberate choice smoke-write makes.
+node scripts/bongos/release.js "$A_ID" --reason "smoke cleanup" || true
+
+A_CLEANUP_CODE=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data '{"reason":"smoke cleanup (task 1004026) - dependency smoke passed; the throwaway row has served its purpose"}' \
+  "$BASE/api/bongos/tasks/$A_ID/abandon") || true
+case "${A_CLEANUP_CODE:-000}" in
+  2*)  echo "  PASS cleaned up throwaway task #$A_ID (abandoned)" ;;
+  403) echo "  SKIP cleanup — task.abandon needs Metic+ (ADR 0152); task #$A_ID left in the ledger" ;;
+  000) echo "  SKIP cleanup — POST /tasks/$A_ID/abandon got no response; task #$A_ID left in the ledger" ;;
+  *)   echo "  SKIP cleanup — POST /tasks/$A_ID/abandon returned HTTP $A_CLEANUP_CODE; task #$A_ID left in the ledger" ;;
+esac
+C_CLEANUP_CODE=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data '{"reason":"smoke cleanup (task 1004191) - auto-promotion witness; the throwaway row has served its purpose"}' \
+  "$BASE/api/bongos/tasks/$C_ID/abandon") || true
+case "${C_CLEANUP_CODE:-000}" in
+  2*) echo "  PASS cleaned up throwaway task #$C_ID (abandoned)" ;;
+  *)  echo "  SKIP cleanup — POST /tasks/$C_ID/abandon returned HTTP ${C_CLEANUP_CODE:-000}; task #$C_ID left in the ledger" ;;
+esac
+echo "  NOTE task #$B_ID is SHIPPED and is deliberately left in the ledger — the abandon route refuses shipped work (cannot_abandon_shipped)."
+
+echo
+echo "ALL SMOKE STEPS PASSED."

package/scripts/bongos/smoke-gds.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// Cross-platform replacement for smoke-gds.sh — same checks, no bash required.
+// Works on Windows (Git Bash / PowerShell / cmd), macOS, and Linux.
+//
+// Usage:
+//   node scripts/bongos/smoke-gds.js                        # against THIS instance
+//   GDS_API_BASE=http://localhost:3000 node scripts/bongos/smoke-gds.js
+//
+// Exit 0 = all checks passed (or the local-target skip). Exit 1 = one or more
+// failures, or no resolvable target (see resolveSmokeTarget).
+
+const https = require('https');
+const http = require('http');
+const net = require('net');
+const { URL } = require('url');
+const ic = require('../../src/instance-config');
+const { loadSessionSync } = require('./cli-lib');
+
+function safeBranding() {
+  try { return require('../../src/branding').branding(); } catch (_) { return {}; }
+}
+
+// readSessionApiBase — the signed-in session's persisted api_base (the instance
+// this CLI is actually pointed at), or null when not signed in / unreadable. The
+// session's OWN value only — deliberately NOT cli-lib's readSessionToken().apiBase,
+// which already folds in the env override + branding default; resolveSmokeTarget
+// orders that precedence itself so it stays pure over its injected inputs. Twin of
+// ship.js's readSessionApiBase.
+function readSessionApiBase() {
+  try {
+    const s = loadSessionSync();
+    return (s && typeof s.api_base === 'string' && s.api_base.trim()) ? s.api_base.trim() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+const normalizeBase = (s) => (typeof s === 'string' && s.trim() ? s.trim().replace(/\/+$/, '') : null);
+
+// Which <PREFIX>_API_BASE supplied the override — the same prefix list, in the
+// same order, that ic.resolveEnv() itself walks. A lookup of the winning NAME,
+// not a second copy of the precedence.
+function matchedApiBaseVar(env) {
+  for (const p of [ic.envPrefix(), ...ic.LEGACY_ENV_PREFIXES]) {
+    const k = `${p}_API_BASE`;
+    if (env[k] !== undefined && env[k] !== '') return k;
+  }
+  return null;
+}
+
+// resolveSmokeTarget — WHICH instance these checks are run against. Precedence
+// mirrors ship.js's resolveInstanceBase(): <PREFIX>_API_BASE env (incl. legacy
+// GDS_/OTB_/PMS_) → the signed-in session's api_base → branding publicOrigin →
+// null.
+//
+// There is deliberately NO hardcoded host. This file baked in
+// `https://example.com` as its fallback, so a builder signed into any OTHER
+// instance who shipped without an env override ran the ship's verification smoke
+// against the founder's box — which PASSED, because that box is healthy. The ship
+// then reported "smoke=clean" on the strength of testing a system it never
+// touched (task 1002418; the smoke sibling of resolveInstanceBase's task 1002232).
+//
+// FAILS CLOSED: a null base is an error, not a fallback. Verifying nothing and
+// saying so beats verifying the wrong instance and calling it a pass.
+//
+// Pure over its injected inputs (env / sessionApiBase / branding) so the
+// precedence is unit-tested without fs/env/network; the defaults read the real
+// session file + brand pack.
+function resolveSmokeTarget({
+  env = process.env,
+  sessionApiBase = readSessionApiBase(),
+  branding = safeBranding(),
+} = {}) {
+  const envBase = normalizeBase(ic.resolveEnv('API_BASE', { env }));
+  const session = normalizeBase(sessionApiBase);
+  const brandOrigin = normalizeBase(branding && branding.domains && branding.domains.publicOrigin);
+
+  const base = envBase || session || brandOrigin || null;
+  let source = null;
+  if (envBase) source = 'env';
+  else if (session) source = 'session';
+  else if (brandOrigin) source = 'branding';
+
+  const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+  return {
+    base,
+    source,
+    envVar: envBase ? matchedApiBaseVar(env) : null,
+    sessionApiBase: session,
+    mismatch: Boolean(base && session && !same(base, session)),
+  };
+}
+
+const SOURCE_LABELS = {
+  session: 'signed-in session api_base',
+  branding: 'branding domains.publicOrigin',
+};
+
+// The env leg names the variable that actually matched, so "clear the override"
+// is actionable — a builder with a stale OTB_API_BASE shouldn't have to guess
+// which of four names to unset (and shouldn't be shown a literal "<PREFIX>").
+const sourceLabel = ({ source, envVar }) =>
+  (source === 'env' ? `${envVar || 'API_BASE'} env override` : SOURCE_LABELS[source] || source);
+
+// formatTargetReport — the lines main() prints BEFORE any check runs, so every run
+// states what it is about to verify. A target that disagrees with the signed-in
+// session gets a loud banner: silence about the mismatch is what made the old
+// hardcoded fallback dangerous. Returns lines so the warning is unit-testable.
+function formatTargetReport({ base, source, envVar, sessionApiBase, mismatch }) {
+  const label = sourceLabel({ source, envVar });
+  const lines = [`=== GDS smoke target: ${base}  (source: ${label}) ===`];
+  if (!mismatch) return lines;
+  const bar = '!'.repeat(72);
+  lines.push(
+    bar,
+    '!! WARNING: the smoke target is NOT the instance you are signed into.',
+    `!!   smoke target : ${base}  (${label})`,
+    `!!   your session : ${sessionApiBase}`,
+    '!! These checks verify the smoke target ONLY. A ship that reports',
+    '!! "smoke=clean" off this run is making a claim about the target above,',
+    `!! not about your own instance. Unset ${envVar || 'the API_BASE env override'} to verify`,
+    '!! the instance you are signed into.',
+    bar,
+  );
+  return lines;
+}
+
+// Laptop-ergonomics preflight (#958 / V4.R20). The smoke checks need a running
+// GDS server. When BASE points at a LOCAL listener that isn't up, every check
+// floods with ECONNREFUSED and fails the ship for a reason that is not a real
+// defect (sessions 328, 1113). We detect the missing LOCAL listener and skip with
+// an explicit notice. A REMOTE base (prod) that's unreachable still fails — that
+// is a genuine problem, not a laptop convenience.
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0']);
+function isLocalTarget(hostname) {
+  return LOCAL_HOSTS.has(String(hostname).toLowerCase());
+}
+
+// TCP connect probe: resolves true if something accepts a connection on host:port
+// within timeoutMs, false on refusal/timeout/error. Never throws.
+function probeListener(host, port, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    let done = false;
+    const sock = net.connect({ host, port });
+    const finish = (v) => { if (!done) { done = true; sock.destroy(); resolve(v); } };
+    sock.setTimeout(timeoutMs);
+    sock.once('connect', () => finish(true));
+    sock.once('error', () => finish(false));
+    sock.once('timeout', () => finish(false));
+  });
+}
+
+// Built per-run from the resolved base (was a module-level const off a hardcoded
+// BASE): resolution now happens inside main(), so requiring this module for its
+// helpers stays side-effect-free.
+const buildChecks = (BASE) => [
+  // Public read-only surface
+  ['GET /api/gds/healthz',              `${BASE}/api/gds/healthz`,             200],
+  ['GET /api/gds/versions',             `${BASE}/api/gds/versions`,            200],
+  ['GET /api/gds/leaderboard',          `${BASE}/api/gds/leaderboard`,         200],
+  ['GET /api/gds/public/versions',      `${BASE}/api/gds/public/versions`,     200],
+  ['GET /api/gds/public/progress',      `${BASE}/api/gds/public/progress`,     200],
+  ['GET /api/gds/public/cost-summary',  `${BASE}/api/gds/public/cost-summary`, 200],
+  ['GET /api/gds/public/recent-shipped',`${BASE}/api/gds/public/recent-shipped`,200],
+  ['GET /api/gds/public/leaderboard',   `${BASE}/api/gds/public/leaderboard`,  200],
+  // Auth-gated: must return 401 when called without a token
+  ['GET /api/gds/me (unauth)',              `${BASE}/api/gds/me`,                   401],
+  ['GET /api/gds/tasks (unauth)',           `${BASE}/api/gds/tasks`,                401],
+  ['GET /api/gds/tasks/claimable (unauth)', `${BASE}/api/gds/tasks/claimable`,      401],
+  ['GET /api/gds/memory/files (unauth)',    `${BASE}/api/gds/memory/files`,         401],
+  ['GET /api/gds/memory/file (unauth)',     `${BASE}/api/gds/memory/file?path=MEMORY.md`, 401],
+  ['GET /api/gds/memory/builders/1/files (unauth)', `${BASE}/api/gds/memory/builders/1/files`, 401],
+  ['GET /api/gds/memory/builders/1/file (unauth)',  `${BASE}/api/gds/memory/builders/1/file?path=MEMORY.md`, 401],
+  // Search (#949): the recall endpoint is requireBuilder-gated — POST without a
+  // token must 401, never serve. (POST because the route is POST-only; a GET
+  // would 404, which wouldn't prove the auth gate.)
+  ['POST /api/gds/search (unauth)',     `${BASE}/api/gds/search`,              401, 'POST'],
+  // Legacy /api/pms/* removed in V3.R01-followup (#308)
+  ['GET /api/pms/healthz (removed)',    `${BASE}/api/pms/healthz`,             404],
+];
+
+function checkUrl(label, url, expectStatus, method = 'GET') {
+  return new Promise((resolve) => {
+    const parsed = new URL(url);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const opts = {
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method,
+      timeout: 10000,
+    };
+    const req = lib.request(opts, (res) => {
+      // drain the response body
+      res.resume();
+      res.on('end', () => {
+        const ok = res.statusCode === expectStatus;
+        console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}  (${res.statusCode}${ok ? '' : ` expected=${expectStatus}`})`);
+        resolve(ok);
+      });
+    });
+    req.on('error', (err) => {
+      console.log(`FAIL  ${label}  (error: ${err.message})`);
+      resolve(false);
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      console.log(`FAIL  ${label}  (timeout)`);
+      resolve(false);
+    });
+    req.end();
+  });
+}
+
+async function main() {
+  const target = resolveSmokeTarget();
+  if (!target.base) {
+    console.log('=== GDS smoke FAILED: no target ===');
+    console.log('Could not resolve which instance to verify: no <PREFIX>_API_BASE env var,');
+    console.log('no signed-in session (node scripts/bongos/setup.js), and no readable branding');
+    console.log('domains.publicOrigin. Refusing to guess a host — a smoke run against the');
+    console.log('wrong instance passes and certifies nothing (task 1002418).');
+    process.exit(1);
+  }
+  const BASE = target.base;
+  for (const line of formatTargetReport(target)) console.log(line);
+
+  let parsed;
+  try {
+    parsed = new URL(BASE);
+  } catch (_) {
+    console.log(`=== GDS smoke FAILED: unusable target ===`);
+    console.log(`"${BASE}" is not an absolute URL — it needs a scheme (https://host).`);
+    process.exit(1);
+  }
+  const host = parsed.hostname;
+  const port = Number(parsed.port) || (parsed.protocol === 'https:' ? 443 : 80);
+
+  if (isLocalTarget(host) && !(await probeListener(host, port))) {
+    console.log('=== GDS smoke SKIPPED ===');
+    console.log(`No server listening on ${host}:${port} (local target ${BASE}).`);
+    console.log('The smoke checks need a running GDS server — start one (npm start) or point');
+    console.log('GDS_API_BASE at a reachable host. Skipping: not a ship-blocking failure.');
+    process.exit(0);
+  }
+
+  const results = await Promise.all(buildChecks(BASE).map(([label, url, status, method]) => checkUrl(label, url, status, method)));
+  const passed = results.filter(Boolean).length;
+  const failed = results.length - passed;
+  console.log(`=== ${passed} passed, ${failed} failed ===`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { isLocalTarget, probeListener, resolveSmokeTarget, formatTargetReport, buildChecks };