@bongos/core 1.18.3 → 1.18.18

package/scripts/gds/seed-bv1-profiles-tasks.js

@@ -0,0 +1,126 @@
+// Seed the tasks for goal 1000045 "Public builder profiles" (BONGOS-V1, internal).
+// Source of truth: docs/specs/bongos-v1-public-builder-profiles.md (status: final).
+// Idempotent on (source, source_ref). Re-running resolves to the existing rows.
+//
+// Run: node scripts/gds/seed-bv1-profiles-tasks.js
+const os = require('os');
+const sess = require(os.homedir() + '/.config/cloudbongos/gds-session.json');
+const BASE = sess.api_base.replace(/\/$/, '');
+const TOKEN = sess.token;
+const VER = 'BONGOS-V1';
+const GOAL = 1000045;
+const SRC = 'planning-session';
+const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function api(method, path, body, _tries = 0) {
+  await sleep(400); // base throttle to stay under the per-IP rate limit
+  const res = await fetch(`${BASE}/api/gds${path}`, {
+    method, headers: H, body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = { _raw: text.slice(0, 300) }; }
+  if (res.status === 429 && _tries < 8) {
+    const wait = ((json.error && json.error.details && json.error.details.retry_after_seconds) || 30) + 1;
+    console.log(`  …rate-limited, waiting ${wait}s`);
+    await sleep(wait * 1000);
+    return api(method, path, body, _tries + 1);
+  }
+  return { status: res.status, ok: res.ok, json };
+}
+
+// disc: engineer (backend/API/spike) | ui (frontend). kind: spike | feature | verify (proofs).
+const TASKS = [
+  // Phase 1 — profile shows cross-project record + hide (C1,C2) — P5
+  { ref:'R01', kind:'spike',   disc:'engineer', prio:5, est:180, crit:['C1','C2'], deps:[],            title:'R01 · Design profile↔cross-project rollup join + consent model', desc:'Needs-exploration: how the public profile reads the platform-identity rollup (listScoutingRollup / platform_identity_builder_project_activity), public-by-default, and where the hide flag (C2) lives. Output an ADR + sub-tasks. See docs/specs/bongos-v1-public-builder-profiles.md.' },
+  { ref:'R02', kind:'feature', disc:'engineer', prio:5, est:240, crit:['C1'],      deps:['R01'],        title:'R02 · Profile API returns cross-project record + project names', desc:'Extend GET /builders/:id/profile to include aggregated cross-project credits/ships/karma/disciplines + the list of projects by name, from the platform-identity rollup; public by default; respects the whitelist + leak test (tests/profile_route.mjs). Done-when: another account sees the aggregate + project names, no private columns. Deps R01.' },
+  { ref:'R03', kind:'feature', disc:'engineer', prio:5, est:180, crit:['C2'],      deps:['R01'],        title:'R03 · Hide flag: builder hides cross-project stats (opt-out, live)', desc:'Self-serve opt-out that hides the cross-project record from the profile + applications, honored live everywhere. Default is shown. Deps R01.' },
+  { ref:'R04', kind:'feature', disc:'ui',       prio:5, est:180, crit:['C1','C2'], deps:['R02','R03'],  title:'R04 · Profile UI: cross-project section + self hide-toggle', desc:'Render the cross-project section (totals + project names) on the profile; show the hide toggle to the profile owner. Deps R02,R03.' },
+  { ref:'R05', kind:'feature', disc:'ui',       prio:4, est:120, crit:['C1'],      deps:['R02'],        title:'R05 · Shareable-by-login profile URL (?builder=<login>)', desc:'Add a login-addressable profile URL alongside ?id=. Promotes idea #1000522. Deps R02.' },
+  { ref:'R06', kind:'verify',  disc:'engineer', prio:4, est:90,  crit:['C1','C2'], deps:['R04','R03'],  title:'R06 · PROOF: cross-project record shows to a viewer; hide removes it live', desc:'Verify a 2-project builder\'s combined record shows to another account, and hiding removes it within one load. Extends tests/profile_route.mjs. Deps R04,R03.' },
+
+  // Phase 2 — apply from orbs + application carries profile (C3,C4) — P5
+  { ref:'R07', kind:'spike',   disc:'engineer', prio:5, est:180, crit:['C3','C4'], deps:[],             title:'R07 · Design application model + "project owner (registrant+delegates)" authz', desc:'Needs-exploration: extend access_requests vs a new cross-project applications record; how the profile snapshot travels hub→target; the owner (registrant + delegates) authz; pending queue + approve/decline. Output an ADR + sub-tasks. Deps none.' },
+  { ref:'R08', kind:'feature', disc:'engineer', prio:5, est:240, crit:['C3','C4'], deps:['R07'],        title:'R08 · Application API: apply / list-pending / approve / decline', desc:'Cross-project application flow reusing the join relay (/my-projects/join → target /access-requests). Deps R07.' },
+  { ref:'R09', kind:'feature', disc:'engineer', prio:5, est:150, crit:['C4'],      deps:['R08','R02'],  title:'R09 · Application carries the applicant\'s cross-project record (+note)', desc:'Attach the applicant\'s cross-project record (subject to the C2 hide, live) + optional note to the application the owner sees. Deps R08,R02.' },
+  { ref:'R10', kind:'feature', disc:'ui',       prio:5, est:180, crit:['C3'],      deps:['R08'],        title:'R10 · "Apply" affordance on the in-core browse surface', desc:'Apply action + state (applied/pending/member) on the project cards / My Projects. Deps R08.' },
+  { ref:'R11', kind:'feature', disc:'ui',       prio:5, est:180, crit:['C4'],      deps:['R08'],        title:'R11 · Owner pending-applications view (approve/decline)', desc:'A project owner sees pending applications for their project and approves/declines. Deps R08.' },
+  { ref:'R12', kind:'feature', disc:'ui',       prio:4, est:150, crit:['C3'],      deps:['R10'],        title:'R12 · Surface "Apply" on the orbs front door', desc:'Wire the Apply affordance onto the orbs page. NOTE: the orbs front door is a separate static site — this likely lands instance-side. Deps R10.' },
+  { ref:'R13', kind:'verify',  disc:'engineer', prio:5, est:90,  crit:['C3','C4'], deps:['R10','R11','R09'], title:'R13 · PROOF: apply → owner sees record → approves → applicant joins', desc:'End-to-end verify of the apply→approve flow carrying the profile. Deps R10,R11,R09.' },
+
+  // Phase 3 — owners browse builder profiles (C5) — P4
+  { ref:'R14', kind:'feature', disc:'engineer', prio:4, est:210, crit:['C5'],      deps:['R02'],        title:'R14 · Graduate /scouting to project-owner-facing + opt-out-of-recruiting flag', desc:'Widen the Archon-only /scouting to a project owner (registrant+delegates); add a builder opt-out-of-recruiting flag. Touches authz → Metic+ floor. Deps R02.' },
+  { ref:'R15', kind:'feature', disc:'ui',       prio:4, est:210, crit:['C5'],      deps:['R14'],        title:'R15 · Owner recruiting UI (search/filter/sort; honors hide + opt-out)', desc:'Owner-facing recruiting surface: search/filter by discipline, sort by track record; honors C2 hide + recruiting opt-out. Deps R14.' },
+  { ref:'R16', kind:'feature', disc:'ui',       prio:4, est:150, crit:['C5'],      deps:['R15','R08'],  title:'R16 · Browse → invite/recruit a builder to your project', desc:'Invite/recruit a builder from the browse surface, tying into the application/invite flow. Deps R15,R08.' },
+  { ref:'R17', kind:'verify',  disc:'engineer', prio:4, est:90,  crit:['C5'],      deps:['R15','R16'],  title:'R17 · PROOF: non-Archon owner browses, filters, invites', desc:'Verify a non-Archon project owner browses builder profiles, filters by discipline, invites one. Deps R15,R16.' },
+
+  // Phase 4 — builder-to-builder connections + degrees (C6) — P4
+  { ref:'R18', kind:'spike',   disc:'engineer', prio:4, est:180, crit:['C6'],      deps:[],             title:'R18 · Design connections model incl. 1st/2nd/3rd-degree traversal', desc:'Needs-exploration: platform-level connections (account↔account) with request/accept/decline/remove; degree-of-separation traversal (1st/2nd/3rd); "people you may know" from native signals. Output an ADR + sub-tasks. Deps none.' },
+  { ref:'R19', kind:'feature', disc:'engineer', prio:4, est:240, crit:['C6'],      deps:['R18'],        title:'R19 · Connections API: request/accept/decline/remove/list + degree queries', desc:'The connection graph API incl. degree-of-separation queries. Deps R18.' },
+  { ref:'R20', kind:'feature', disc:'ui',       prio:4, est:180, crit:['C6'],      deps:['R19','R04'],  title:'R20 · Connections on the profile (with degree labels) + connect button', desc:'Show a builder\'s connections (public) with 1st/2nd/3rd-degree labels; connect/pending/accept from the profile. Deps R19,R04.' },
+  { ref:'R21', kind:'feature', disc:'engineer', prio:4, est:150, crit:['C6'],      deps:['R19'],        title:'R21 · "Builders you may know" from mutuals + shared projects/guilds', desc:'Suggest connections from mutual connections + shared projects/guilds (2nd/3rd degree). Deps R19.' },
+  { ref:'R22', kind:'verify',  disc:'engineer', prio:4, est:90,  crit:['C6'],      deps:['R20','R21'],  title:'R22 · PROOF: two builders connect; each sees the other + a 2nd-degree suggestion', desc:'Verify request→accept, mutual visibility, and a 2nd-degree suggestion appears. Deps R20,R21.' },
+
+  // Phase 5 — guilds + apply/invite + guild map (C7,C8,C9) — P3
+  { ref:'R23', kind:'spike',   disc:'engineer', prio:3, est:210, crit:['C7','C8','C9'], deps:['R18','R07'], title:'R23 · Design guild model (tables, roles, public/unlisted, rollup, map ranking)', desc:'Needs-exploration: platform-level guilds + guild_members (multi-guild, distinct from goal_members); roles; public/unlisted visibility; collective rollup (excludes hidden members); guild↔project application reuse; map ranking. Output an ADR + sub-tasks. Deps R18,R07.' },
+  { ref:'R24', kind:'feature', disc:'engineer', prio:3, est:240, crit:['C7'],      deps:['R23'],        title:'R24 · Guild CRUD + membership API + public/unlisted visibility', desc:'Create guild, invite/accept/join-request, roster, leave; owner sets public/unlisted. Deps R23.' },
+  { ref:'R25', kind:'feature', disc:'ui',       prio:3, est:210, crit:['C7'],      deps:['R24'],        title:'R25 · Guild page UI (identity, roster, collective record)', desc:'Guild page: identity, roster, collective track record (N of M counted). Deps R24.' },
+  { ref:'R26', kind:'feature', disc:'engineer', prio:3, est:180, crit:['C7'],      deps:['R24','R02'],  title:'R26 · Guild collective track-record rollup (excludes hidden members)', desc:'Aggregate members\' cross-project stats into the guild total; exclude C2-hidden members ("N of M counted"). Deps R24,R02.' },
+  { ref:'R27', kind:'feature', disc:'engineer', prio:3, est:210, crit:['C8'],      deps:['R24','R08'],  title:'R27 · Guild → project applications + owner invites a guild (each-member-opt-in)', desc:'Guild applies to / is invited to a project (guild-level mirror of R08); each member opts in before being attached. Deps R24,R08.' },
+  { ref:'R28', kind:'feature', disc:'ui',       prio:3, est:150, crit:['C8'],      deps:['R27','R11'],  title:'R28 · Owner view: pending guild applications', desc:'Extends the owner application view (R11) to guild applications. Deps R27,R11.' },
+  { ref:'R29', kind:'spike',   disc:'engineer', prio:3, est:150, crit:['C9'],      deps:['R26'],        title:'R29 · Design guild map ranking + orb-sky viz approach', desc:'Needs-exploration: rank guilds by size/success; render on the orb-sky visual language (goal 1000044). Output design + sub-tasks. Deps R26.' },
+  { ref:'R30', kind:'feature', disc:'engineer', prio:3, est:150, crit:['C9'],      deps:['R26'],        title:'R30 · Guild map API (ranked; public guilds only; honors hide)', desc:'Ranked guilds by size/success; only public (not unlisted) guilds; honors member hide. Deps R26.' },
+  { ref:'R31', kind:'feature', disc:'ui',       prio:3, est:210, crit:['C9'],      deps:['R30','R29','R15'], title:'R31 · Guild map UI on the recruiting surface (orb-sky visual)', desc:'Visual guild map on the owner recruiting surface. Deps R30,R29,R15.' },
+  { ref:'R32', kind:'verify',  disc:'engineer', prio:3, est:120, crit:['C7','C8','C9'], deps:['R25','R27','R31'], title:'R32 · PROOF: form guild → applies (members opt in) → owner approves → ranked on map', desc:'End-to-end verify of the guild lifecycle incl. the map. Deps R25,R27,R31.' },
+
+  // Phase 6 — connection proximity via orb-sky physics (C10) — P3
+  { ref:'R33', kind:'spike',   disc:'engineer', prio:3, est:210, crit:['C10'],     deps:['R19','R23'],  title:'R33 · Design connection→orb-physics proximity + degree model', desc:'Needs-exploration: connection strength (direct + mutuals + shared projects/guilds + co-shipped; no time-decay) feeding orb-world physics (goals 1000044/1000049); cluster detection. NOTE cross-goal dependency on orb-physics infra. Output an ADR + sub-tasks. Deps R19,R23.' },
+  { ref:'R34', kind:'feature', disc:'engineer', prio:3, est:210, crit:['C10'],     deps:['R33'],        title:'R34 · Connection-strength + degree + cluster compute API', desc:'Compute connection strength + degrees + close-knit clusters; feeds orb physics + recruiting. Deps R33.' },
+  { ref:'R35', kind:'feature', disc:'ui',       prio:3, est:180, crit:['C10'],     deps:['R34','R25'],  title:'R35 · Builder-side: clusters in the orb sky → invite a close cluster to a guild', desc:'Close connections cluster in the orb sky; invite a cluster to form a guild from it. Deps R34,R25.' },
+  { ref:'R36', kind:'feature', disc:'ui',       prio:3, est:180, crit:['C10'],     deps:['R34','R16'],  title:'R36 · Project-side: recruit a close-knit cluster together', desc:'Surface close-knit clusters on the recruiting surface; recruit them together. Deps R34,R16.' },
+  { ref:'R37', kind:'verify',  disc:'engineer', prio:3, est:120, crit:['C10'],     deps:['R35','R36'],  title:'R37 · PROOF: cluster forms a guild from the sky; owner recruits a cluster', desc:'End-to-end verify of the proximity-driven guild-forming + cluster-recruiting. Deps R35,R36.' },
+];
+
+const ROOTS = ['R01', 'R07', 'R18']; // zero-dep entry spikes to open for claiming
+
+(async () => {
+  const idByRef = {};
+  let created = 0, existing = 0;
+  console.log(`Seeding ${TASKS.length} tasks under goal ${GOAL} (${VER})…`);
+  for (const t of TASKS) {
+    const r = await api('POST', '/tasks', {
+      version_id: VER, goal_id: GOAL, title: t.title, description: t.desc,
+      kind: t.kind, discipline: t.disc, priority: t.prio, est_minutes: t.est,
+      criterion_ids: t.crit, source: SRC, source_ref: `bv1-profiles-${t.ref}`,
+    });
+    if (!r.ok) { console.log(`  ${t.ref}: FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    const task = r.json.task || r.json;
+    idByRef[t.ref] = task.id;
+    if (r.json.idempotent || r.json.existing) existing++; else created++;
+    console.log(`  ${t.ref} → task ${task.id} (${t.kind}/${t.disc}, P${t.prio}, [${t.crit.join(',')}])`);
+  }
+
+  console.log('Wiring dependencies…');
+  let edges = 0;
+  for (const t of TASKS) {
+    if (!t.deps.length) continue;
+    const id = idByRef[t.ref];
+    const depIds = t.deps.map((d) => idByRef[d]).filter(Boolean);
+    if (!id || depIds.length !== t.deps.length) { console.log(`  ${t.ref}: dep resolve gap, skipping`); continue; }
+    const r = await api('POST', `/tasks/${id}/dependencies`, { depends_on_task_ids: depIds });
+    if (!r.ok) { console.log(`  ${t.ref}: dep FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    edges += (r.json.added || depIds.length);
+    console.log(`  ${t.ref} depends on ${t.deps.join(',')}`);
+  }
+
+  console.log('Promoting root spikes to ready…');
+  for (const ref of ROOTS) {
+    const id = idByRef[ref];
+    if (!id) continue;
+    const r = await api('POST', `/tasks/${id}/promote`, {});
+    console.log(`  ${ref} (task ${id}): ${r.ok ? 'ready' : 'promote note ' + JSON.stringify(r.json).slice(0,120)}`);
+  }
+
+  console.log(`\nDONE. created=${created} existing=${existing} depEdges=${edges}. Roots opened: ${ROOTS.join(', ')}.`);
+  console.log('ref→id:', JSON.stringify(idByRef));
+})();

package/scripts/gds/sequence.js

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+// /builder-sequence — walk a dependency chain end to end from one kickoff.
+//
+// Two-thirds of the open backlog is dependency-gated. Shipping a task
+// auto-promotes its dependents backlog→ready (the promote_dependents_on_ship
+// trigger, migrations 020/163) — but nothing picks the newly-unblocked task
+// up, so an N-task chain needs N separate kickoffs. This is the plumbing that
+// lets one session walk the whole chain: resolve scope → next → claim → build
+// → ship → next.
+//
+// Calling forms:
+//   node scripts/gds/sequence.js --from 1002277          plan the chain below a task
+//   node scripts/gds/sequence.js --goal 1000045          plan a goal's open tasks
+//   node scripts/gds/sequence.js --from 1002277 --next   the one task to claim now
+//   node scripts/gds/sequence.js --check 1002277         stop-reasons for one task
+//
+// Flags:
+//   --next         emit only the next claimable task (or a named stop reason)
+//   --check <id>   evaluate the halt matrix for one task
+//   --json         machine-readable output
+//   --limit N      cap the planned chain at N tasks (default 50)
+//
+// This script DECIDES NOTHING it cannot decide from facts. Every halt is a
+// named reason a human can act on — see HALT_REASONS. The judgement half of
+// the loop (actually building each task) lives in .claude/skills/builder-sequence.
+
+const { cliClient, requireSession, fmtMinutes, hallBase } = require('./cli-lib');
+const { matchProtected } = require('../../src/bongos/permission-path-check');
+
+// Rank → tier, mirroring REQUIRES_RANK_TIER. Imported shape would drag the
+// server's db.js (and its pool) into a CLI that only needs four integers.
+const RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
+
+// A task in one of these statuses is done as far as the chain is concerned —
+// 'completed'/'confirmed' are mid-ship states, so the chain must not re-claim
+// them, but they are also not yet 'shipped' so successors stay gated.
+const TERMINAL = new Set(['shipped', 'abandoned']);
+const IN_FLIGHT = new Set(['active', 'completed', 'confirmed']);
+
+const DEFAULT_LIMIT = 50;
+
+// A description shorter than this can't carry acceptance criteria worth
+// verifying against, so the runner refuses to guess at what "done" means.
+const MIN_SPEC_CHARS = 120;
+
+// Kinds whose whole point is a judgement call the owner should see before it
+// lands: a decision needs an ADR, a spike's output is a recommendation.
+const JUDGEMENT_KINDS = new Set(['decision', 'spike']);
+
+const HALT_REASONS = {
+  needs_migration: 'wants a schema migration — needs a reserved number and human eyes',
+  security_sensitive: 'flagged security-sensitive',
+  protected_path: 'touches the permission/deploy core',
+  rank_floor: 'requires a rank above yours',
+  thin_spec: 'has no acceptance criteria to verify against',
+  judgement_kind: 'is a judgement call (decision/spike), not mechanical work',
+  not_claimable: 'is ready but the server will not hand it over',
+  deps_unmet: 'is still waiting on a predecessor',
+  in_flight: 'is already mid-ship',
+  cycle: 'sits in a dependency cycle',
+  chain_complete: 'nothing left in this chain',
+};
+
+// -------------------------------------------------------------------------
+// Argv
+// -------------------------------------------------------------------------
+
+function readArgv(argv) {
+  const out = { from: null, goal: null, check: null, next: false, json: false, limit: DEFAULT_LIMIT };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--next') { out.next = true; continue; }
+    if (a === '--json') { out.json = true; continue; }
+    if (a === '--from') { out.from = Number(argv[++i]); continue; }
+    if (a.startsWith('--from=')) { out.from = Number(a.slice(7)); continue; }
+    if (a === '--goal') { out.goal = Number(argv[++i]); continue; }
+    if (a.startsWith('--goal=')) { out.goal = Number(a.slice(7)); continue; }
+    if (a === '--check') { out.check = Number(argv[++i]); continue; }
+    if (a.startsWith('--check=')) { out.check = Number(a.slice(8)); continue; }
+    if (a === '--limit') { out.limit = Number(argv[++i]); continue; }
+    if (a.startsWith('--limit=')) { out.limit = Number(a.slice(8)); continue; }
+    if (!out.from && /^\d+$/.test(a)) { out.from = Number(a); continue; }
+  }
+  return out;
+}
+
+// -------------------------------------------------------------------------
+// Pure core (exported for tests)
+// -------------------------------------------------------------------------
+
+// Ids a task object points at, tolerating both the bare-number and the
+// {id,kind} row shapes GET /tasks/:id has returned across schema versions.
+// Ids must come out positive: Number(null) is 0, so a null edge would
+// otherwise enter the graph as task 0 and be chased as a real dependency.
+function edgeIds(list) {
+  return (list || [])
+    .map((d) => Number(d && typeof d === 'object' ? d.id : d))
+    .filter((n) => Number.isFinite(n) && n > 0);
+}
+
+// Kahn's algorithm over edges BETWEEN the given tasks. An out-of-scope
+// dependency doesn't block ordering the scope itself — it surfaces later as a
+// deps_unmet halt, which is the honest place for it. Ties break on the same
+// keys the claimable feed sorts by, so a plan reads in the order the board
+// would have offered the work.
+function topoOrder(tasks) {
+  const inScope = new Set(tasks.map((t) => Number(t.id)));
+  const byId = new Map(tasks.map((t) => [Number(t.id), t]));
+  const remaining = new Set(inScope);
+  const order = [];
+
+  const rank = (id) => {
+    const t = byId.get(id);
+    return [
+      t.priority == null ? 99 : Number(t.priority),
+      Number(t.est_minutes_calibrated ?? t.est_minutes ?? 0) || 0,
+      Number(t.id),
+    ];
+  };
+  const cmp = (a, b) => {
+    const [pa, ma, ia] = rank(a);
+    const [pb, mb, ib] = rank(b);
+    return pa - pb || ma - mb || ia - ib;
+  };
+
+  let progressed = true;
+  while (remaining.size && progressed) {
+    progressed = false;
+    const free = Array.from(remaining).filter((id) => {
+      const deps = edgeIds(byId.get(id).dependencies).filter((d) => remaining.has(d));
+      return deps.length === 0;
+    });
+    if (free.length === 0) break;
+    free.sort(cmp);
+    for (const id of free) {
+      order.push(byId.get(id));
+      remaining.delete(id);
+      progressed = true;
+    }
+  }
+
+  return { order, cycle: Array.from(remaining).sort((a, b) => a - b) };
+}
+
+// The chain below a head: the head plus every task transitively reachable
+// through dependents[]. Terminal tasks are walked THROUGH (a shipped task's
+// successors are exactly what we want) but not included in the plan.
+function chainFrom(headId, byId, { limit = DEFAULT_LIMIT } = {}) {
+  const seen = new Set();
+  const picked = [];
+  const queue = [Number(headId)];
+  while (queue.length) {
+    const id = queue.shift();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const t = byId.get(id);
+    if (!t) continue;
+    if (!TERMINAL.has(t.status)) picked.push(t);
+    for (const d of edgeIds(t.dependents)) queue.push(d);
+    if (picked.length >= limit) break;
+  }
+  return picked;
+}
+
+// The halt matrix. Facts only — every entry is something the runner can read
+// off the task row, never a judgement about the work itself.
+function haltReasons(task, { rank, claimableIds = null } = {}) {
+  const reasons = [];
+  if (!task) return [{ code: 'not_found', detail: 'no such task' }];
+
+  if (task.needs_migration) {
+    reasons.push({ code: 'needs_migration', detail: HALT_REASONS.needs_migration });
+  }
+  if (task.security_sensitive) {
+    reasons.push({ code: 'security_sensitive', detail: HALT_REASONS.security_sensitive });
+  }
+
+  const hits = matchProtected(task.touches || []);
+  if (hits.length) {
+    reasons.push({
+      code: 'protected_path',
+      detail: `${HALT_REASONS.protected_path} (${hits.map((h) => h.glob).join(', ')})`,
+    });
+  }
+
+  const floor = RANK_TIER[task.requires_rank] ?? 0;
+  const mine = RANK_TIER[rank] ?? 0;
+  if (floor > mine) {
+    reasons.push({
+      code: 'rank_floor',
+      detail: `needs rank '${task.requires_rank}', you are '${rank || 'unknown'}'`,
+    });
+  }
+
+  if (JUDGEMENT_KINDS.has(task.kind)) {
+    reasons.push({ code: 'judgement_kind', detail: `kind '${task.kind}' ${HALT_REASONS.judgement_kind}` });
+  }
+
+  const spec = String(task.description || '').trim();
+  if (spec.length < MIN_SPEC_CHARS) {
+    reasons.push({
+      code: 'thin_spec',
+      detail: spec ? `description is ${spec.length} chars — too thin to verify against` : 'no description',
+    });
+  }
+
+  if (IN_FLIGHT.has(task.status)) {
+    reasons.push({ code: 'in_flight', detail: `status is '${task.status}'` });
+  } else if (task.status !== 'ready') {
+    reasons.push({ code: 'deps_unmet', detail: `status is '${task.status}', not 'ready'` });
+  } else if (claimableIds && !claimableIds.has(Number(task.id))) {
+    // 'ready' but absent from the server's own claimable feed means an open
+    // blocker, a touches collision with a live claim, or a rank filter. Rather
+    // than re-deriving that query client-side (and drifting from it), defer.
+    reasons.push({ code: 'not_claimable', detail: HALT_REASONS.not_claimable });
+  }
+
+  return reasons;
+}
+
+function summarize(tasks) {
+  return tasks.reduce(
+    (acc, t) => ({
+      count: acc.count + 1,
+      credits: acc.credits + (Number(t.credits_reward) || 0),
+      minutes: acc.minutes + (Number(t.est_minutes_calibrated ?? t.est_minutes) || 0),
+    }),
+    { count: 0, credits: 0, minutes: 0 },
+  );
+}
+
+// -------------------------------------------------------------------------
+// Fetching
+// -------------------------------------------------------------------------
+
+async function fetchTask(api, id) {
+  const r = await api.tasks.getTasksId({ id });
+  if (!r.ok) return null;
+  return r.data.task || r.data;
+}
+
+// Breadth-first over dependents[], fetching each task's detail once. The list
+// endpoint omits the edge arrays, so the detail route is the only source.
+async function fetchChain(api, headId, limit) {
+  const byId = new Map();
+  const queue = [Number(headId)];
+  const seen = new Set();
+  while (queue.length && byId.size < limit * 4) {
+    const wave = queue.splice(0, 12).filter((id) => !seen.has(id));
+    wave.forEach((id) => seen.add(id));
+    if (!wave.length) continue;
+    const rows = await Promise.all(wave.map((id) => fetchTask(api, id)));
+    for (const t of rows) {
+      if (!t) continue;
+      byId.set(Number(t.id), t);
+      for (const d of edgeIds(t.dependents)) if (!seen.has(d)) queue.push(d);
+    }
+  }
+  return byId;
+}
+
+async function fetchGoalTasks(api, goalId, limit) {
+  const r = await api.tasks.getTasks({ query: { limit: 1000 } });
+  const rows = (r.ok ? rowsOf(r.data) : null) || [];
+  const mine = rows
+    .filter((t) => Number(t.goal_id) === Number(goalId) && !TERMINAL.has(t.status))
+    .slice(0, limit);
+  const byId = new Map();
+  for (let i = 0; i < mine.length; i += 12) {
+    const rowsD = await Promise.all(mine.slice(i, i + 12).map((t) => fetchTask(api, t.id)));
+    rowsD.forEach((t) => t && byId.set(Number(t.id), t));
+  }
+  return byId;
+}
+
+// GET /tasks/claimable returns its rows under `claimable`; GET /tasks under
+// `tasks`. Returning null (not an empty Set) on an unreadable response matters:
+// haltReasons treats null as "couldn't check" and stays quiet, where an empty
+// Set would mark every task not_claimable and halt the runner on its first step.
+function rowsOf(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== 'object') return null;
+  for (const key of ['claimable', 'tasks', 'rows', 'items']) {
+    if (Array.isArray(payload[key])) return payload[key];
+  }
+  return null;
+}
+
+async function fetchClaimableIds(api) {
+  const r = await api.tasks.getTasksClaimable({ query: { limit: 500 } });
+  if (!r.ok) return null;
+  const rows = rowsOf(r.data);
+  return rows ? new Set(rows.map((t) => Number(t.id))) : null;
+}
+
+// -------------------------------------------------------------------------
+// Output
+// -------------------------------------------------------------------------
+
+function taskLine(t, i) {
+  const est = t.est_minutes_calibrated ?? t.est_minutes;
+  return `  ${String(i + 1).padStart(2)}. task ${t.id} · ${t.status} · ${t.credits_reward ?? 0}c · ${est ? fmtMinutes(est) : '—'}\n      ${t.title}`;
+}
+
+function printPlan({ plan, cycle, scope, base }) {
+  if (!plan.length) {
+    console.log(`No open tasks in ${scope}. ${HALT_REASONS.chain_complete}.`);
+    return;
+  }
+  const tot = summarize(plan);
+  console.log(`Chain for ${scope} — ${tot.count} open task(s), ${tot.credits}c, ${fmtMinutes(tot.minutes)}\n`);
+  plan.forEach((t, i) => console.log(taskLine(t, i)));
+  if (cycle.length) {
+    console.log(`\n⚠ ${cycle.length} task(s) could not be ordered — dependency cycle: ${cycle.join(', ')}`);
+  }
+  console.log(`\nHall: ${base}#/task/${plan[0].id}`);
+  console.log(`Next: node scripts/gds/sequence.js --from ${plan[0].id} --next`);
+}
+
+function printHalt(task, reasons) {
+  console.log(`HALT — task ${task.id}: ${task.title}\n`);
+  for (const r of reasons) console.log(`  • [${r.code}] ${r.detail}`);
+  console.log('\nThis one needs a human. Everything already shipped stays shipped.');
+}
+
+// -------------------------------------------------------------------------
+// Main
+// -------------------------------------------------------------------------
+
+async function main() {
+  const opts = readArgv(process.argv.slice(2));
+  if (!opts.from && !opts.goal && !opts.check) {
+    console.error('usage: sequence.js --from <task-id> | --goal <goal-id> | --check <task-id> [--next] [--json]');
+    process.exit(2);
+  }
+
+  await requireSession();
+  const api = await cliClient();
+  const meR = await api.me.getMe();
+  const rank = meR.ok ? meR.data.builder?.rank : null;
+  const base = hallBase();
+
+  // --check: one task, halt matrix, non-zero exit if anything fires.
+  if (opts.check) {
+    const t = await fetchTask(api, opts.check);
+    const claimableIds = await fetchClaimableIds(api);
+    const reasons = haltReasons(t, { rank, claimableIds });
+    if (opts.json) {
+      console.log(JSON.stringify({ task_id: opts.check, ok: reasons.length === 0, reasons }, null, 2));
+    } else if (!reasons.length) {
+      console.log(`task ${opts.check} is clear to run.`);
+    } else {
+      printHalt(t || { id: opts.check, title: '(not found)' }, reasons);
+    }
+    process.exit(reasons.length ? 1 : 0);
+  }
+
+  const byId = opts.goal
+    ? await fetchGoalTasks(api, opts.goal, opts.limit)
+    : await fetchChain(api, opts.from, opts.limit);
+
+  const scope = opts.goal ? `goal ${opts.goal}` : `task ${opts.from}`;
+  const candidates = opts.goal
+    ? Array.from(byId.values()).filter((t) => !TERMINAL.has(t.status))
+    : chainFrom(opts.from, byId, { limit: opts.limit });
+
+  const { order, cycle } = topoOrder(candidates);
+  const plan = order.slice(0, opts.limit);
+
+  // --next: the first task in the plan that clears the halt matrix.
+  if (opts.next) {
+    const claimableIds = await fetchClaimableIds(api);
+    const head = plan[0];
+    if (!head) {
+      const payload = { next: null, stop: 'chain_complete', detail: HALT_REASONS.chain_complete };
+      console.log(opts.json ? JSON.stringify(payload, null, 2) : `${HALT_REASONS.chain_complete} in ${scope}.`);
+      process.exit(0);
+    }
+    const reasons = haltReasons(head, { rank, claimableIds });
+    if (reasons.length) {
+      const payload = { next: null, stop: reasons[0].code, reasons, task: { id: head.id, title: head.title } };
+      if (opts.json) console.log(JSON.stringify(payload, null, 2));
+      else printHalt(head, reasons);
+      process.exit(1);
+    }
+    const remaining = summarize(plan);
+    if (opts.json) {
+      console.log(JSON.stringify({ next: head, remaining, scope }, null, 2));
+    } else {
+      console.log(`Next in ${scope}: task ${head.id} — ${head.title}`);
+      console.log(`  ${head.credits_reward ?? 0}c · ${fmtMinutes(head.est_minutes_calibrated ?? head.est_minutes ?? 0)} · ${remaining.count - 1} more after this`);
+      console.log(`  node scripts/gds/claim.js ${head.id}`);
+    }
+    process.exit(0);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ scope, plan, cycle, totals: summarize(plan) }, null, 2));
+    return;
+  }
+  printPlan({ plan, cycle, scope, base });
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err.message || err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  readArgv,
+  edgeIds,
+  rowsOf,
+  topoOrder,
+  chainFrom,
+  haltReasons,
+  summarize,
+  HALT_REASONS,
+  RANK_TIER,
+  MIN_SPEC_CHARS,
+  JUDGEMENT_KINDS,
+  TERMINAL,
+  IN_FLIGHT,
+};

package/scripts/gds/session-cost.js

@@ -42,7 +42,16 @@ function encodeCwd(cwd) {
 // grader transcript's first user message is the worker system prompt — match it
 // to exclude it from the newest-file fallback. (The SessionEnd hook path is
 // unaffected: it passes an explicit transcript_path and never calls this.)
-const GRADER_WORKER_SIGNATURE = /You are the \*\*(Quality|Hacker|Narc|Efficiency)/;
+// Match the SHAPE of the worker preamble, not a closed list of persona names: a
+// new worker added to modules/grading/grader-workers/ would otherwise slip past
+// this and be treated as a builder session — which now means real money, since
+// backfill-sessions.js uses this to decide what NOT to pay for. Every worker
+// opens `You are the **<Persona>** … adversarial subagent` (narc/hacker/efficiency
+// say "a specialist adversarial subagent", quality says "specialist — an
+// adversarial subagent"). Still anchored on that preamble rather than the bare
+// phrase, so a real session that merely DISCUSSES adversarial subagents in its
+// first message is not misread as one.
+const GRADER_WORKER_SIGNATURE = /You are the \*\*[^*\n]{1,40}\*\*[^\n]{0,60}?adversarial subagent/;
 
 function firstUserText(file) {
   // Scan only until the first user message — avoids fully parsing a large

package/scripts/gds/setup.js

@@ -19,7 +19,18 @@
 // home directory) and prints the builder profile.
 
 const readline = require('readline');
-const { cliClient, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE } = require('./cli-lib');
+const { cliClient, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE, hallBase } = require('./cli-lib');
+
+// The instance's status dashboard, from branding — never a hardcoded host, so a
+// non-OTB instance points its builders at ITS OWN dashboard (task 1002428).
+// Falls back to the resolved API base when branding is unreadable.
+function statusOrigin() {
+  try {
+    const d = require('../../src/branding').branding().domains || {};
+    if (d.statusOrigin) return d.statusOrigin;
+  } catch (_) { /* fall through */ }
+  return API_BASE;
+}
 const onboardingConfig = require('./onboarding-config');
 
 const DRY_RUN = process.argv.includes('--dry-run');
@@ -70,9 +81,9 @@ async function promptGeminiKey() {
     console.log('Google AI Studio key for the pixel-art pipeline (per-builder, optional).');
     console.log('  Get one at https://aistudio.google.com/app/apikey');
     console.log('  (Or skip this and add it later with browser clicks: hall Settings →');
-    console.log('   https://amazonprimea.com/builders/settings#art-key — stored encrypted, ADR 0073.)');
+    console.log(`   ${hallBase()}/settings#art-key — stored encrypted, ADR 0073.)`);
     console.log('  Each builder pays their own Gemini bill so spend is attributed to them');
-    console.log('  on https://status.amazonprimea.com.');
+    console.log(`  on ${statusOrigin()}.`);
     let prompt;
     if (existing && typeof existing === 'string' && existing.length >= 4) {
       const last4 = existing.slice(-4);
@@ -265,6 +276,21 @@ async function promptOnboardingConsent() {
 (async () => {
   const forceFlag = process.argv.includes('--force');
 
+  // Environment preflight (task 1002401, onboarding-audit area 4). Before auth,
+  // surface the three things that used to bite a new builder one reactive crash
+  // at a time — Node, installed deps, a launchable `claude` CLI — each with a
+  // copy-paste fix, instead of `node: command not found` / `Cannot find module
+  // 'pg'` / SUBAGENT_SPAWN_FAILED turning up deep in the session. Read-only and
+  // NON-blocking: a fail is actionable, not fatal to sign-in, so it also runs in
+  // --dry-run. Shares one source of truth with `bongos doctor` (preflight.js).
+  try {
+    const { preflightChecks, formatPreflight } = require('./preflight');
+    console.log(formatPreflight(preflightChecks(), { color: process.stdout.isTTY, heading: true }));
+    console.log('');
+  } catch (err) {
+    console.error(`(environment preflight skipped: ${err.message})`);
+  }
+
   // --dry-run: describe every side effect the real flow would perform, without
   // doing any of them. No API calls, no file writes, no TTY prompts. Suitable
   // for a newcomer to read before running for real. Intentionally calls
@@ -452,7 +478,7 @@ async function promptOnboardingConsent() {
     if (poll.data && poll.data.state === 'not_approved') {
       console.error('');
       console.error('This GitHub account has not been approved yet.');
-      console.error('Off the Boats admits new builders by invitation: an Archon must');
+      console.error(`${require('./cli-lib').productName()} admits new builders by invitation: an Archon must`);
       console.error('approve your access request before you can enroll.');
       console.error('  → Ask an Archon to invite you / approve your access request,');
       console.error('    then re-run /builder-setup (or: node scripts/gds/setup.js).');
@@ -526,7 +552,7 @@ async function promptOnboardingConsent() {
           printOnboardingNudge(meRes.data);
           console.log('');
           console.log('Newcomer path:');
-          console.log('  1. Choose thy craft:  open https://amazonprimea.com/builders (creative / engineering)');
+          console.log(`  1. Choose thy craft:  open ${hallBase()} (creative / engineering)`);
           console.log('  2. Survey work:       /builder-start');
           console.log('  3. Claim + ship:      /builder-claim N    →    /builder-ship');
           console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');