@bongos/core 1.18.0 → 1.18.18

package/modules/lifecycle/routes/done-when.js

@@ -15,8 +15,64 @@ const api = require('../../../src/module-api');
 const auth = api;
 const doneWhen = require('../done-when');
 const db = require('../db');
+// The goal authority PREDICATE (ADR 0154) — the same owner|manager test routes/goals.js
+// uses for visibility / invites / roles, so "who may manage this goal" has
+// one definition. A module sibling, like ../db.
+const { isGoalOwnerOrManager } = require('../goal-authz');
 const { validateOrRespond, parseId, asyncHandler, LIMITS } = api;
 
+// authorizeCriterionCreate — the ORDERED, FAIL-CLOSED decision for a non-Archon
+// POST /versions/:id/done-when (ADR 0154). PURE + exported so every rejection is
+// pinned by a DB-free unit test (the authorizeGoalTaskCreate precedent in
+// routes/goals.js). The route resolves goal/version first — their absence is a
+// 404/400 there — so this gate only decides AUTHORITY, in this order:
+//   archon → allow · goal named? · owner|manager? (MASKED) · goal open? · version open?
+// Authority sits ahead of both state checks on purpose — see the no-leak note below.
+// An Archon short-circuits: version-level (goal-less) criteria and any goal in any
+// state stay theirs. Returns { ok:true }, { ok:false, status, body }, or
+// { ok:false, maskAsBadGoalId:true } (the route renders the identical 400).
+//
+// "Version open" = `planning` or `building`. NOT just `building`: a planning session
+// scopes a version at status='planning', which is the main moment criteria get
+// written. `shipped` is closed (the same `version_closed` refusal
+// authorizeGoalTaskCreate uses), and `frozen` means the scope is deliberately
+// locked — for a SCOPE write that is a refusal, even though task authoring allows it.
+const CRITERION_OPEN_VERSION_STATUSES = ['planning', 'building'];
+
+function authorizeCriterionCreate({ goal, version, actorId, actorRank, actorMembership }) {
+  if (actorRank === 'archon') return { ok: true };
+  if (!goal) {
+    return { ok: false, status: 403, body: {
+      error: 'goal_id_required',
+      message: 'Name the goal this criterion belongs to — a version-level criterion is Archon-only (ADR 0154).',
+    } };
+  }
+  // NO-LEAK ORDERING — authority BEFORE state, and the refusal is MASKED.
+  // Before ADR 0154 this route was Archon-only, and an Archon can already read
+  // every goal, so no probe existed. Now a Metic may call it, and distinguishable
+  // refusals (400 "no such goal" vs 403 "not yours" vs 409 "not open") would turn
+  // it into an oracle for which goal ids exist on a version — including PRIVATE
+  // goals (ADR 0112). So a caller who is not the owner/manager gets byte-identical
+  // `bad_goal_id` to a caller naming a goal that does not exist. Only someone who
+  // already holds the goal learns anything further about it.
+  if (!isGoalOwnerOrManager({ goal, actorId, actorRank, actorMembership })) {
+    return { ok: false, maskAsBadGoalId: true };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Only an open goal can be given new criteria.',
+    } };
+  }
+  if (!version || !CRITERION_OPEN_VERSION_STATUSES.includes(version.status)) {
+    return { ok: false, status: 409, body: {
+      error: 'version_closed', status: version ? version.status : null,
+      message: 'Only an Archon may add a criterion to a shipped or frozen version.',
+    } };
+  }
+  return { ok: true };
+}
+
 module.exports = function buildDoneWhenRouter() {
   const router = express.Router();
 
@@ -35,16 +91,32 @@ module.exports = function buildDoneWhenRouter() {
     res.json({ version_id: versionId, criteria, goals });
   }, { errorCode: 'list_failed' }));
 
-  // Auth (Archon): create a done-when criterion at RUNTIME. ADR 0105 moved
-  // scope-truth seeds (versions/goals/criteria) out of the normal migration path,
-  // so a brand-new criterion on a RUNNING instance can no longer be added by a
-  // plain migration (migrations/instance/ applies only under the owner opt-in
-  // GDS_APPLY_INSTANCE_SEEDS=1, a DR step). This is the vector a planning session
-  // uses to add a criterion to a live version WITHOUT a droplet migrate. Archon-
-  // only — done_when_criteria is scope-shaping (mirrors the criterion-proposal
-  // ratify gate). Pinned in route-rank-check.MODULE_EXPECTED_RANKS.
-  // rank: archon — scope-truth write (a new criterion on a version).
-  router.post('/versions/:id/done-when', auth.requireBuilder, auth.requireRank('archon'), asyncHandler('POST /versions/:id/done-when', async (req, res) => {
+  // Auth (Metic+, then the goal's own authority): create a done-when criterion at
+  // RUNTIME. ADR 0105 moved scope-truth seeds (versions/goals/criteria) out of the
+  // normal migration path, so a brand-new criterion on a RUNNING instance can no
+  // longer be added by a plain migration (migrations/instance/ applies only under
+  // the owner opt-in GDS_APPLY_INSTANCE_SEEDS=1, a DR step). This is the vector a
+  // planning session uses to add a criterion to a live version WITHOUT a droplet
+  // migrate.
+  //
+  // ADR 0154 — authority over a GOAL's criteria follows GOAL OWNERSHIP, not global
+  // rank. A Metic who may create the goal (POST /goals) and author the tasks under
+  // it (POST /tasks, ADR 0090) may now write the criteria those tasks gate — but
+  // only inside a goal they own or manage. Deliberately NOT a flat re-rank:
+  //   - An unsatisfied criterion permanently blocks version close (version-close.js
+  //     counts satisfied === total per VERSION, regardless of goal) and goal
+  //     auto-achieve (db.achieveGoalIfComplete). There is NO delete route, so it
+  //     cannot be undone via the API — the same backward ratchet as unsatisfy,
+  //     which stays Archon.
+  //   - So a non-Archon must name a goal_id (version-level criteria stay Archon),
+  //     must be that goal's OWNER or MANAGER (isGoalOwnerOrManager — the same
+  //     predicate behind visibility/invite/role management), and the goal must be
+  //     open on a planning/building version. That bounds the blast radius to a
+  //     workspace they already hold. An unauthorized caller is masked behind
+  //     bad_goal_id so the route is not an existence oracle (ADR 0112).
+  // Pinned in route-rank-check.MODULE_EXPECTED_RANKS.
+  // rank: metic+archon — criterion create, walled by goal ownership (ADR 0154).
+  router.post('/versions/:id/done-when', auth.requireBuilder, auth.requireRank('metic', 'archon'), asyncHandler('POST /versions/:id/done-when', async (req, res) => {
     const versionId = String(req.params.id || '').trim();
     if (!versionId) return res.fail('version_id_required', 400);
     if (validateOrRespond(req, res, {
@@ -55,12 +127,29 @@ module.exports = function buildDoneWhenRouter() {
     })) return;
     const version = await db.getVersion(versionId);
     if (!version) return res.fail('version_not_found', { status: 404, message: `No version '${versionId}'.` });
+    // The ONE bad_goal_id refusal, used both for a genuinely absent/foreign goal
+    // and for the masked unauthorized case below — same code, same message, same
+    // envelope, so the two are indistinguishable on the wire.
+    const badGoalId = () => res.fail('bad_goal_id', { status: 400, message: `goal_id ${req.body.goal_id} does not exist on version '${versionId}'.` });
     // A goal_id, if given, must exist AND belong to this version.
+    let goal = null;
     if (req.body.goal_id != null) {
-      const goal = await db.getGoal(req.body.goal_id);
-      if (!goal || String(goal.version_id) !== String(versionId)) {
-        return res.fail('bad_goal_id', { status: 400, message: `goal_id ${req.body.goal_id} does not exist on version '${versionId}'.` });
-      }
+      goal = await db.getGoal(req.body.goal_id);
+      if (!goal || String(goal.version_id) !== String(versionId)) return badGoalId();
+    }
+    // ADR 0154: the authority wall. Checked AFTER the goal's version linkage so a
+    // bad ref is still the clearer 400. Membership is only read when a goal was
+    // named and the caller isn't an Archon — a primary-key hit on
+    // goal_members (goal_id, builder_id) (migration 160), on a low-frequency route.
+    const actorMembership = (goal && req.builder.rank !== 'archon')
+      ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id })
+      : null;
+    const decision = authorizeCriterionCreate({
+      goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+    });
+    if (!decision.ok) {
+      if (decision.maskAsBadGoalId) return badGoalId();
+      return res.status(decision.status).json(decision.body);
     }
     try {
       const criterion = await db.createCriterion({
@@ -98,7 +187,8 @@ module.exports = function buildDoneWhenRouter() {
   // criterion belongs to a goal and was its LAST unsatisfied one, the goal auto-
   // flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the
   // planner — not only the Archon — closes the criterion/goal loop; the route is
-  // pinned in route-rank-check.EXPECTED_RANKS so a further downgrade is caught.
+  // pinned in route-rank-check.MODULE_EXPECTED_RANKS.lifecycle so a further
+  // downgrade is caught.
   // rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).
   router.post('/done-when/:criterionId/satisfy', auth.requireBuilder, auth.requireRank('metic', 'archon'), asyncHandler('POST /done-when/:criterionId/satisfy', async (req, res) => {
     if (validateOrRespond(req, res, {
@@ -134,3 +224,8 @@ module.exports = function buildDoneWhenRouter() {
 
   return router;
 };
+
+// ADR 0154: the pure ordered gate for POST /versions/:id/done-when — exported for
+// tests/criterion_authoring_gate.mjs (DB-free), the authorizeGoalTaskCreate
+// precedent in routes/goals.js.
+module.exports.authorizeCriterionCreate = authorizeCriterionCreate;

package/modules/lifecycle/routes/goals.js

@@ -38,6 +38,11 @@ const { isModuleKey, scopeIncludesProtected, moduleKeys } = api.moduleScopeMap;
 const goalScopeCheck = api.goalScopeCheck;
 // The pure conflict detector (task 1736) — a module sibling, like ../db.
 const goalConflicts = require('../goal-conflicts');
+// The goal authority model (task 1002538 / ADR 0154) — moved to a module sibling
+// so done-when.js can share it verbatim. authorizeGoalManagement is re-exported at
+// the bottom of this file so the existing DB-free unit tests keep importing it from
+// here; isGoalOwner is used internally only and is exported from ../goal-authz.
+const { isGoalOwner, authorizeGoalManagement } = require('../goal-authz');
 
 const VALID_GOAL_STATUSES = ['open', 'achieved', 'archived'];
 const VALID_MEMBER_ROLES = ['lead', 'member'];
@@ -122,18 +127,9 @@ function authorizeGoalTaskCreate({ goal, version, isMember, builderRank, touches
   return { ok: true };
 }
 
-// The goal AUTHORITY MODEL (task 1735). Two layers, deliberately different kinds:
-//   - OWNER — goals.created_by, the fixed authority. Not a role row: it is set at
-//     create time (the creator) and moves only via the explicit transfer route.
-//     The owner holds every goal power.
-//   - MANAGER — the goal_members.role 'lead' value (the hall renders it
-//     "manager"). Owner-equivalent EXCEPT: a manager cannot DEMOTE a fellow
-//     manager (owner-only), and cannot transfer ownership.
-// A goal with created_by NULL (the migration-160 system defaults) has no owner;
-// Archons act as one — the archon arm of both gates below.
-function isGoalOwner(goal, builderId) {
-  return goal.created_by != null && String(goal.created_by) === String(builderId);
-}
+// The goal AUTHORITY MODEL (owner vs manager) now lives in ../goal-authz.js —
+// isGoalOwner + authorizeGoalManagement are imported at the top of this file and
+// re-exported at the bottom (task 1002538 / ADR 0154).
 
 // authorizeMemberRoleChange — the ORDERED, FAIL-CLOSED authorization decision for
 // PATCH /goals/:id/members/:builderId (task 1735). Today the only role-assignment
@@ -201,32 +197,6 @@ function authorizeMemberRoleChange({ goal, actorId, actorRank, actorMembership,
   return { ok: true };
 }
 
-// authorizeGoalManagement — the shared ORDERED, FAIL-CLOSED prefix for actions
-// a goal's own authority performs (task 1736: conflict resolution; the same
-// three steps open authorizeMemberRoleChange above): goal exists → goal open →
-// actor is owner|manager|Archon. Returns { ok:true } or { ok:false, status,
-// body }. PURE + exported, same precedent as its siblings.
-function authorizeGoalManagement({ goal, actorId, actorRank, actorMembership }) {
-  if (!goal) {
-    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
-  }
-  if (goal.status !== 'open') {
-    return { ok: false, status: 409, body: {
-      error: 'goal_not_open', status: goal.status,
-      message: 'Only an open goal can be managed.',
-    } };
-  }
-  const actorIsOwner = isGoalOwner(goal, actorId);
-  const actorIsManager = !!actorMembership && actorMembership.role === 'lead';
-  if (actorRank !== 'archon' && !actorIsOwner && !actorIsManager) {
-    return { ok: false, status: 403, body: {
-      error: 'not_owner_or_manager',
-      message: 'Only this goal\'s owner or a manager (or an Archon) may do this.',
-    } };
-  }
-  return { ok: true };
-}
-
 // authorizeOwnershipTransfer — the ORDERED, FAIL-CLOSED decision for
 // POST /goals/:id/transfer (task 1735): the owner hands the goal to another
 // builder (the old owner keeps their manager row). Ownership is creator-

package/modules/lifecycle/routes/tasks.js

@@ -8,6 +8,8 @@ const auth = api;
 const db = require('../db');
 const hierarchy = require('../hierarchy');
 const { suggestCriteria } = require('../criterion-suggest');
+// The orphan-task advisory (task 1002539) — pure, fail-open; see goal-advisory.js.
+const { buildGoalAdvisory } = require('../goal-advisory');
 // grading carved to modules/grading/ (BV1.R73 / ADR 0091 §4): the lifecycle no
 // longer imports the grader — it resolves the `grade` kernel PORT at grade time
 // (seams.resolveOptional('grade'), in POST /tasks/:id/grade below).
@@ -79,7 +81,7 @@ function detectsMigration(...texts) {
 // Same deliberate-locality call as the MIGRATION_KEYWORD_RE mirror above.
 
 // VOTABLE_TASK_STATUSES — a task is votable once it's verified work the project
-// keeps (confirmed = past the grader, credits landed; or shipped = deployed);
+// keeps (confirmed = past the grader, not yet paid; or shipped = deployed + paid);
 // backlog/ready/completed are not. Imported above from ../task-classifier (D1).
 
 // #853 (ADR 0041): temporary, default-OFF global grader bypass. When the env
@@ -216,6 +218,14 @@ module.exports = function buildTasksRouter() {
       }
     }
     const tasks = await db.listTasks({ versionId: version, status, kind, discipline, goalId });
+    // ?include=deps (hall redesign task 1002439) — enrich each task with its
+    // dependency summary (`blocked_by[]` with per-target satisfied state, and a
+    // `blocks` count) so the Goals rollup + Tasks dependency view can paint
+    // ready/blocked without an N+1 of /tasks/:id fetches. Opt-in so the default
+    // list shape stays unchanged for every other caller. Two aggregate queries.
+    if (String(req.query.include || '').split(',').includes('deps')) {
+      await db.attachTaskDepSummaries(tasks);
+    }
     res.json({ tasks });
   });
 
@@ -709,12 +719,17 @@ module.exports = function buildTasksRouter() {
           console.error('[gds] POST /tasks suggest-criteria (non-blocking)', e && e.message);
         }
       }
+      // task 1002539 — the orphan-task advisory (the /goal-create auto-pickup
+      // hook). Nothing 4xxs when a task has no goal, so surface it here instead of
+      // blocking. Non-blocking by construction — see goal-advisory.js.
+      const goal_advisory = await buildGoalAdvisory({ db, versionId: body.version_id, task });
       res.status(201).json({
         task,
         credits_reward: task.credits_reward,
         needs_migration: needsMigration,
         criteria,
         suggested_criteria,
+        goal_advisory,
       });
     } catch (err) {
       console.error('[gds] POST /tasks', err);
@@ -955,13 +970,26 @@ module.exports = function buildTasksRouter() {
   });
 
   // rank: metic+archon — backlog→ready promotion; scope mutation; ADR 0090 (was archon).
+  //
+  // Also the UN-ABANDON path (ADR 0152): 'abandoned' → 'backlog'. When abandon moved
+  // down to Metic+ it needed an undo at the same rank, or a Metic's mis-retire would
+  // be unrecoverable without Archon SQL (no other route restores an abandoned task —
+  // PATCH refuses `status` outright). A restore lands in **backlog**, never straight
+  // to ready: the task was retired for a reason, so it re-enters as un-workable and
+  // takes a second, deliberate promote to become claimable again.
   router.post('/tasks/:id/promote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
     const id = Number(req.params.id);
     const task = await db.getTask(id);
     if (!task) return res.fail('task_not_found', 404);
-    if (!['backlog', 'blocked'].includes(task.status)) {
+    if (!['backlog', 'blocked', 'abandoned'].includes(task.status)) {
       return res.fail('cannot_promote', 409, { current_status: task.status });
     }
+    // The restore branch returns early: no reward gate (that is a promote-to-WORKABLE
+    // concern and backlog is the pre-workable state — same reasoning as /demote).
+    if (task.status === 'abandoned') {
+      const restored = await db.restoreTask({ taskId: id });
+      return res.json({ ok: true, restored: true, status: restored.taskStatus });
+    }
     // task 1670 / ADR 0096 + task 1673 amendment (2026-06-28): a task must never
     // become workable paying 0 drachmae — but the gate AUTO-ASSIGNS rather than
     // BLOCKS. If credits_reward is 0/NULL, assign the capped suggestion (from
@@ -1113,10 +1141,14 @@ module.exports = function buildTasksRouter() {
   // on a task with an active claim (release it first); idempotent on an already-
   // abandoned task. The abandon + its `reason` land in audit_log via the writing
   // middleware, so the ledger keeps a record of who retired what.
-  // rank: archon — terminal lifecycle mutation / scope removal (ADR 0016). This
-  // is the inverse of /promote and belongs to the same archon-gated scope-control
-  // surface, never self-serviceable by a lower rank.
-  router.post('/tasks/:id/abandon', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  // rank: metic+archon — scope removal; the inverse of /promote, and re-ranked to
+  // match it (ADR 0152, was archon under ADR 0090). A Metic who may author, shape,
+  // and promote work may also retire it: leaving the kill switch an Archon rung
+  // higher than the create switch only forced the owner to clean up after the
+  // triage they already delegated. Not one-way any more — /promote restores an
+  // abandoned task to backlog at the same rank — and the guards below (shipped
+  // refused, active claim refused) plus the audit_log entry are unchanged.
+  router.post('/tasks/:id/abandon', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
     if (validateOrRespond(req, res, {
       reason: { type: 'string' },  // free-text retire reason (sliced to 2000 below)
     })) return;

package/modules/lifecycle/ship-card.js

@@ -247,6 +247,12 @@ function buildCardModel(input = {}) {
     } else if (credits.awarded != null) {
       const total = fmtInt(credits.total);
       creditsText = total ? `+${credits.awarded} → ${total} ${brand.currency}` : `+${credits.awarded} ${brand.currency}`;
+      // cost-plus-only (ADR 0146): the per-task estimate is withheld, so a `+0`
+      // here is correct. Say why on the card itself — unexplained it reads as a
+      // broken payout (task 1002469). `perTaskCredit` is injected by the caller
+      // (which resolves economy's rewardPolicy); absent ⇒ assume the paying
+      // default and print nothing, so other instances are untouched.
+      if (credits.perTaskCredit === false) creditsText += ' · est. not paid (cost-plus only)';
     }
     // Usage — lead with the dollar cost (the honest measure of the work), then
     // split the token count into 'new' (fresh input + Claude's output + the

package/modules/onboarding/onboarding-state.js

@@ -129,7 +129,7 @@ const STAGE_HINTS = {
   auth_complete:    'First obtain the repo — clone it (or open thy hosted dev box, where it is already cloned) — then sign in via GitHub Device Flow or the web sign-in.',
   pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
   first_start:      'Run /builder-start to see claimable works.',
-  first_claim:      'Claim a task with /builder-claim N.',
+  first_claim:      'Claim a task with /builder-claim N — then on thy dev box run /builder-sync, and thy box pulls exactly that task\'s code (naught else) within seconds.',
   ship_three:       'Carry three tasks through with /builder-ship — the third makes thee a Thetes.',
   graduated:        '',
 };

package/modules/platform-identity/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/platform-identity/hub-device.js

@@ -0,0 +1,147 @@
+// modules/platform-identity/hub-device.js — the hub's GitHub device flow for CLI
+// federation (ADR 0141 §1, task #1002108).
+//
+// This is a DELIBERATELY SELF-CONTAINED GitHub device flow — it does NOT reuse
+// core auth's startDeviceFlow/pollDeviceFlow, because those mint a hub BUILDER
+// session (and run the hub's invite-only admission gate). Federation must instead
+// establish a platform ACCOUNT — open to anyone with a GitHub account, since a
+// platform account is pure identity and project admission stays LOCAL (ADR 0141:
+// identity federated, authority local). So the flow here runs GitHub's device
+// endpoints against the hub's own OAuth app and returns the raw GitHub identity;
+// the route then upserts the platform account and mints an assertion. The ~40
+// lines of GitHub mechanics duplicated from core auth are boundary-forced
+// duplication (ADR 0091 §2) — the module cannot import core internals.
+'use strict';
+
+const api = require('../../src/module-api');
+
+const { resolveEnv, userAgent } = api;
+const SCOPE = 'read:user';
+
+// In-memory device_code -> { client_id, interval, expires_at, last_polled_at }.
+// Ephemeral, like core auth's deviceFlows: a hub restart drops pending flows (the
+// CLI just re-runs). The client_id is BOUND here at start (resolved from the
+// user-typed origin by the route) so the poll mints for exactly that client — the
+// CLI never gets to name the audience (ADR 0141 §1 security fix).
+const hubDeviceFlows = new Map();
+
+// Absolute cap on concurrent pending flows — a backstop against memory growth from
+// a flood of /sso/device/start calls (the per-IP write limiter is the primary
+// control; this bounds a distributed flood). Old expired entries are reaped first,
+// so a legitimate load never hits this.
+const MAX_FLOWS = 2000;
+
+// The hub's own GitHub OAuth-app client id (public). Device flow needs only the
+// client_id (no secret) for both start and the token poll.
+function hubGithubClientId() {
+  return resolveEnv('GITHUB_CLIENT_ID') || null;
+}
+
+function hubDeviceConfigured() {
+  return !!hubGithubClientId();
+}
+
+// Start a GitHub device flow against the hub's app, BOUND to `federatedClientId`
+// (the client the route resolved from the user-typed origin). Returns the codes to
+// show the user. Throws with an actionable message on a GitHub OAuth-app misconfig.
+async function startHubGithubDevice(federatedClientId) {
+  const clientId = hubGithubClientId();
+  if (!clientId) throw new Error('hub GitHub app not configured');
+  if (!federatedClientId) throw new Error('federated client_id required');
+  // Reap expired first, then refuse a NEW start past the cap (never evict a live one).
+  for (const [k, v] of hubDeviceFlows) if (v.expires_at < Date.now()) hubDeviceFlows.delete(k);
+  if (hubDeviceFlows.size >= MAX_FLOWS) throw new Error('too many device flows in flight; try again shortly');
+  const res = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams({ client_id: clientId, scope: SCOPE }).toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`github device/code failed (${res.status}): ${text.slice(0, 160)}`);
+  }
+  const data = await res.json();
+  if (data.error) {
+    const hint = data.error === 'device_flow_disabled'
+      ? ' — enable Device Flow on the hub GitHub app'
+      : '';
+    throw new Error(`github rejected device-flow start: ${data.error}${hint}`);
+  }
+  if (!data.device_code) throw new Error('github device/code returned no device_code');
+  hubDeviceFlows.set(data.device_code, {
+    client_id: federatedClientId,
+    interval: data.interval || 5,
+    expires_at: Date.now() + (data.expires_in || 900) * 1000,
+    last_polled_at: 0,
+  });
+  return {
+    device_code: data.device_code,
+    user_code: data.user_code,
+    verification_uri: data.verification_uri,
+    interval: data.interval || 5,
+    expires_in: data.expires_in || 900,
+  };
+}
+
+// Poll GitHub for the device flow's completion. Returns:
+//   { state: 'pending' } | { state: 'slow_down', interval } | { state: 'expired' }
+//   | { state: 'denied' } | { state: 'ok', identity: { github_id, github_login,
+//     display_name, avatar_url } }
+// Identity ONLY — no session, no rank. The route mints the assertion from it.
+async function pollHubGithubDevice(deviceCode) {
+  const flow = hubDeviceFlows.get(deviceCode);
+  if (!flow) return { state: 'expired' };
+  if (flow.expires_at < Date.now()) { hubDeviceFlows.delete(deviceCode); return { state: 'expired' }; }
+  const now = Date.now();
+  if (now - flow.last_polled_at < flow.interval * 1000) return { state: 'slow_down', interval: flow.interval };
+  flow.last_polled_at = now;
+
+  const clientId = hubGithubClientId();
+  const res = await fetch('https://github.com/login/oauth/access_token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams({
+      client_id: clientId,
+      device_code: deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    }).toString(),
+  });
+  const data = await res.json();
+  if (data.error === 'authorization_pending') return { state: 'pending' };
+  if (data.error === 'slow_down') { flow.interval = (flow.interval || 5) + 5; return { state: 'slow_down', interval: flow.interval }; }
+  if (data.error === 'expired_token') { hubDeviceFlows.delete(deviceCode); return { state: 'expired' }; }
+  if (data.error === 'access_denied') { hubDeviceFlows.delete(deviceCode); return { state: 'denied' }; }
+  if (data.access_token) {
+    hubDeviceFlows.delete(deviceCode);
+    const ghRes = await fetch('https://api.github.com/user', {
+      headers: {
+        Authorization: `Bearer ${data.access_token}`,
+        'User-Agent': userAgent(),
+        Accept: 'application/vnd.github+json',
+      },
+    });
+    if (!ghRes.ok) throw new Error(`github /user failed (${ghRes.status})`);
+    const u = await ghRes.json();
+    return {
+      state: 'ok',
+      // client_id is the one BOUND at start (from the user-typed origin) — the CLI
+      // never names the audience; the mint uses this (ADR 0141 §1 security fix).
+      client_id: flow.client_id,
+      identity: {
+        github_id: u.id,
+        github_login: u.login,
+        display_name: u.name || u.login,
+        avatar_url: u.avatar_url,
+      },
+    };
+  }
+  return { state: 'pending' };
+}
+
+module.exports = {
+  hubGithubClientId,
+  hubDeviceConfigured,
+  startHubGithubDevice,
+  pollHubGithubDevice,
+  _flows: hubDeviceFlows, // exposed for tests
+};