@bongos/core 1.19.617 → 1.19.619

package/scripts/gds/backlog-review.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+// /backlog-review — walk the tasks sitting at status='backlog' and give each one
+// the nod, the axe, or a reset clock (task 1003746).
+//
+// WHY THIS EXISTS. `backlog` is the PRE-WORKABLE state: a task lands there when
+// the system will not put it in the claimable queue without a human saying go
+// (`modules/ideas/routing.js` — "'backlog' means a human still says go"), and
+// ADR 0234 §2 records why: a feature/cleanup/refactor filing "reshape[s] what
+// gets built and a filer should not be able to set the queue's agenda alone".
+// Every OTHER queue in the methodology has a walkable cadence — /idea-triage for
+// idea_inbox, /blocker-review for blockers, /bug-triage for kind=bug,
+// /goal-review for criteria. The backlog had none. Its only pull surfaces were
+// the nod queue (`GET /inbox/awaiting-nod`, scoped `WHERE origin='route'`, so it
+// sees only filings that came through the idea inbox) and the 30-day rot timer.
+// This is the missing walk.
+//
+// Usage:
+//   node scripts/gds/backlog-review.js [--limit N] [--goal ID] [--all]
+//
+// THE FOUR BUCKETS, AND WHY ONLY TWO GET WALKED. One read
+// (`GET /tasks?status=backlog&include=deps`) partitions into four populations,
+// and conflating them is the whole trap this script exists to avoid — a row
+// waiting on a TRIGGER is not a row waiting on a PERSON, and asking a human to
+// verdict the former wastes the cadence on rows it cannot move:
+//
+//   stranded   — dep-gated, but at least one dependency is ABANDONED. That edge
+//                can never satisfy, so the migration-163 auto-promote trigger
+//                will NEVER fire: the row is stuck, not waiting. WALKED FIRST,
+//                because it is the only bucket that gets worse by being left.
+//   nod        — no unsatisfied dependency: nothing is gating it but a human.
+//                THE REVIEW SUBJECT. This is what "review the backlog" means.
+//   dep-gated  — an unsatisfied dependency that is still alive. COUNTED, NEVER
+//                WALKED: shipping the dependency auto-promotes it (migration
+//                163), so a human verdict here is noise at best and, if it
+//                promotes, races the trigger.
+//   spikes     — kind='spike' rows live at backlog BY CONVENTION (migration 020:
+//                "Spikes stay in backlog by convention"), so they are not
+//                un-nodded work. COUNTED, NEVER WALKED.
+//
+// THE VERBS ARE STATUS-DERIVED, NOT A FIXED LIST. The rot card publishes four
+// task verbs (prioritise/prune/kill/water — `modules/lifecycle/rot.js`), but two
+// of them are status-conditional at the route: `POST /tasks/:id/promote` accepts
+// only backlog|blocked|abandoned, and `POST /tasks/:id/demote` accepts only
+// 'ready' (`modules/lifecycle/routes/tasks.js`). So on a BACKLOG row "prune" is
+// a guaranteed 409 `cannot_demote` — it is already at the bottom. `verbsFor`
+// below derives the offer from the row's actual status instead of hardcoding a
+// list, so this walk can never offer a button the server will refuse.
+//
+// Prompts per row:
+//   [p]romote   → POST /tasks/:id/promote  (backlog → ready; the nod. Also the
+//                 point the reward gate auto-assigns credits_reward if it is
+//                 0/NULL — ADR 0096 — so the assigned price is echoed back)
+//   [k]ill      → POST /tasks/:id/abandon {reason} (it is not going to happen)
+//   [w]ater     → POST /tasks/:id/water (leave it; reset the rot clock. The one
+//                 verb that changes no status and destroys nothing)
+//   [s]kip      → no write; the row surfaces again next review
+//   [q]uit      → exit early, print the partial summary
+//
+// Exit codes:
+//   0  walked cleanly (incl. an empty queue)
+//   1  api / network error
+//   2  no session
+
+const readline = require('node:readline');
+const { cliClient, requireSession, cliExit, hasFlag, arg } = require('./cli-lib');
+
+// The API caps ?limit at 1000 (`routes/tasks.js` — "limit must be a positive
+// integer up to 1000"). Spelled here rather than passed larger-and-hoped:
+// scripts/gds/audit-deps.js asks for 3000 and every run of it dies on a 400,
+// which is exactly how the stranded rows below went unnoticed.
+const MAX_API_LIMIT = 1000;
+
+// How many rows one sitting offers by default. The queue is routinely in the
+// hundreds; a walk that demands all of them gets abandoned halfway, which is
+// worse than a walk that reliably clears twenty. --all overrides.
+const DEFAULT_WALK_LIMIT = 20;
+
+// A dependency in one of these statuses can never satisfy, so anything gated on
+// it is stranded rather than waiting. Mirrors modules/lifecycle/dead-deps.js
+// DEAD_DEP_STATUSES — kept as its own constant because this script must run from
+// a plain checkout without loading the server's module tree.
+const DEAD_DEP_STATUSES = new Set(['abandoned']);
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function trim(s, n) {
+  const str = String(s || '');
+  return str.length > n ? `${str.slice(0, n - 1)}…` : str;
+}
+
+// unsatisfiedDeps(task) — the dependency edges still holding this row down.
+// `include=deps` returns blocked_by[] with a per-edge `satisfied` flag already
+// computed server-side (modules/lifecycle/db-deps-criteria.js), so this trusts
+// that flag rather than re-deriving "shipped" from a status string here.
+function unsatisfiedDeps(task) {
+  return (task.blocked_by || []).filter((d) => d && !d.satisfied);
+}
+
+function deadDeps(task) {
+  return (task.blocked_by || []).filter((d) => d && DEAD_DEP_STATUSES.has(String(d.status)));
+}
+
+// partitionBacklog(tasks) — the four buckets, from one list of backlog rows.
+// Pure and exported: tests/backlog_review.mjs pins the bucket rules without
+// standing up Postgres, and the ordering below IS the review's priority claim.
+//
+// Order of tests matters and is deliberate: a stranded row is reported as
+// stranded even though it is also dep-gated, because "your gate is dead" is the
+// actionable fact and "you have a gate" is not.
+function partitionBacklog(tasks) {
+  const out = { stranded: [], nod: [], depGated: [], spikes: [] };
+  for (const t of Array.isArray(tasks) ? tasks : []) {
+    if (!t || String(t.status) !== 'backlog') continue;
+    const dead = deadDeps(t);
+    if (dead.length) { out.stranded.push({ ...t, dead_deps: dead }); continue; }
+    if (String(t.kind) === 'spike') { out.spikes.push(t); continue; }
+    if (unsatisfiedDeps(t).length) { out.depGated.push(t); continue; }
+    out.nod.push(t);
+  }
+  // Oldest first in both walked buckets: the row that has waited longest for a
+  // human is the one the cadence exists to catch, and a stable order means an
+  // interrupted walk resumes roughly where it stopped.
+  const byAge = (a, b) => String(a.created_at || '').localeCompare(String(b.created_at || '')) || Number(a.id) - Number(b.id);
+  out.stranded.sort(byAge);
+  out.nod.sort(byAge);
+  return out;
+}
+
+// groupByGoal(rows) — cluster rows into goal groups so the walk is presented
+// goal-by-goal instead of as one flat list.
+//
+// WHY GROUP AT ALL. The nod decision is mostly a SCOPE judgment — "does this goal
+// want this work next" — and that judgment is made once per goal, not once per
+// row. Walking a flat age-ordered list makes the reviewer rebuild the same goal
+// context every few rows and re-decide the same question; clustering lets one
+// context answer five rows in a row.
+//
+// The ORDER still honours oldest-first, one level up: goals are ordered by their
+// own oldest waiting row, and rows inside a goal by age. So the goal that has
+// been ignored longest comes first, and nothing is buried by a chatty neighbour.
+// Returns [{ goal_id, rows }] — pure, exported, and the shape the walk iterates.
+function groupByGoal(rows) {
+  const byAge = (a, b) => String(a.created_at || '').localeCompare(String(b.created_at || '')) || Number(a.id) - Number(b.id);
+  const groups = new Map();
+  for (const t of Array.isArray(rows) ? rows : []) {
+    if (!t) continue;
+    // A goal-less row is its own group rather than being dropped or merged into
+    // some other goal's context. ADR 0250 D4 makes goal_id required on new tasks,
+    // so this is the legacy/system-created tail — small, but it must still be
+    // walkable or the queue would quietly retain rows the walk never offers.
+    const key = t.goal_id == null ? '(no goal)' : String(t.goal_id);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  const out = [];
+  for (const [goal_id, groupRows] of groups) {
+    groupRows.sort(byAge);
+    out.push({ goal_id, rows: groupRows });
+  }
+  // Goals ordered by their oldest row — the age rule, lifted one level.
+  out.sort((a, b) => byAge(a.rows[0], b.rows[0]));
+  return out;
+}
+
+// verbsFor(task) — what the server will ACTUALLY accept on this row, derived
+// from its status. See the header note: promote and demote are each valid for
+// disjoint status sets, so a fixed four-verb list is wrong for every row.
+function verbsFor(task) {
+  const status = String(task && task.status);
+  const verbs = [];
+  if (status === 'backlog' || status === 'blocked' || status === 'abandoned') verbs.push('promote');
+  if (status === 'ready') verbs.push('demote');
+  if (status !== 'shipped' && status !== 'abandoned') verbs.push('kill');
+  verbs.push('water');
+  return verbs;
+}
+
+async function listBacklog({ goalId } = {}) {
+  const api = await cliClient();
+  const query = { status: 'backlog', include: 'deps', limit: MAX_API_LIMIT };
+  if (goalId) query.goal_id = goalId;
+  const r = await api.tasks.getTasks({ query });
+  if (!r.ok) throw new Error(`GET /tasks?status=backlog failed (${r.status}): ${JSON.stringify(r.data)}`);
+  // GET /tasks responds { tasks: [...] }, not a bare array — the same shape trap
+  // that made bug-triage.js throw before listing anything (see its listOpenBugTasks).
+  return r.data?.tasks ?? [];
+}
+
+// Goal id -> title, for the walk's group headers. Fails OPEN: a header that shows
+// a bare id is a cosmetic loss, and a review that refuses to start because the
+// goal list did not load would be a much worse trade.
+async function fetchGoalTitles() {
+  try {
+    const api = await cliClient();
+    const r = await api.goals.getGoals({ query: { limit: 200 } });
+    if (!r.ok) return new Map();
+    return new Map((r.data?.goals ?? []).map((g) => [String(g.id), g.title]));
+  } catch (_) {
+    return new Map();
+  }
+}
+
+async function promoteTask(id) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdPromote({ id, body: {} });
+  if (!r.ok) throw Object.assign(new Error(`promote failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+async function killTask(id, reason) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdAbandon({ id, body: { reason: reason || '' } });
+  if (!r.ok) throw Object.assign(new Error(`kill failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+// The gentlest verb: it changes no status and destroys nothing (routes/rot.js).
+// Its route is `requireBuilder` plus an ownership-or-atom check in the handler —
+// authorized iff you CREATED the task or you hold the see-all-rot atom — so it is
+// not unconditionally open, and a caller who is neither gets a 403 naming both
+// paths. Every caller of THIS script is already Metic+ (the skill's rank gate), who
+// hold that atom per ADR 0157, so in practice it always passes here; the 403 is
+// surfaced verbatim rather than swallowed in case that ever stops being true.
+async function waterTask(id) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdWater({ id, body: {} });
+  if (!r.ok) throw Object.assign(new Error(`water failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+function printCounts(buckets) {
+  const { stranded, nod, depGated, spikes } = buckets;
+  const total = stranded.length + nod.length + depGated.length + spikes.length;
+  console.log(`\nBacklog: ${total} rows`);
+  console.log(`  ${nod.length} awaiting a nod        — a human is the only thing gating these (walked)`);
+  console.log(`  ${stranded.length} stranded              — gated by an ABANDONED dependency; the auto-promote trigger can never fire (walked first)`);
+  console.log(`  ${depGated.length} waiting on a dependency — shipping the dep auto-promotes them (migration 163); not a human decision, not walked`);
+  console.log(`  ${spikes.length} spikes                — live at backlog by convention (migration 020); not walked`);
+}
+
+function printRow(task, idx, total, label) {
+  console.log(`\n[${idx + 1}/${total}] ${label} #${task.id}  ${task.title}`);
+  if (task.description) console.log(`  ${trim(task.description, 300)}`);
+  const bits = [];
+  if (task.goal_id) bits.push(`goal ${task.goal_id}`);
+  if (task.kind) bits.push(task.kind);
+  if (task.discipline && task.discipline !== 'unclassified') bits.push(task.discipline);
+  if (task.est_minutes) bits.push(`~${task.est_minutes}m`);
+  bits.push(task.credits_reward ? `${task.credits_reward} credits` : 'no reward set — promote assigns one');
+  if (task.created_at) bits.push(`filed ${String(task.created_at).slice(0, 10)}`);
+  console.log(`  ${bits.join(' · ')}`);
+  for (const d of task.dead_deps || []) {
+    console.log(`  ⚠ dependency ${d.id} is ${d.status}: "${trim(d.title, 60)}" — this edge can NEVER satisfy.`);
+  }
+  if (task.dead_deps && task.dead_deps.length) {
+    const first = task.dead_deps[0].id;
+    console.log('  → Resolve it deliberately: DROP the dead edge (DELETE /api/bongos/dependencies '
+      + `{"from_kind":"task","from_id":${task.id},"to_kind":"task","to_id":${first}}) `
+      + `or RESTORE the dependency (POST /api/bongos/tasks/${first}/promote returns an abandoned task to backlog).`);
+  }
+}
+
+// The per-row walk. Mutates `state.summary`; returns false when the user quits.
+async function walkRow(rl, task, idx, total, label, state) {
+  printRow(task, idx, total, label);
+  for (;;) {
+    const offer = verbsFor(task).includes('promote')
+      ? '  [p]romote (make claimable) / [k]ill / [w]ater (leave it, reset the clock) / [s]kip / [q]uit > '
+      : '  [k]ill / [w]ater / [s]kip / [q]uit > ';
+    const ans = (await prompt(rl, offer)).trim().toLowerCase();
+
+    if (ans === 'q' || ans === 'quit') return false;
+    if (ans === 's' || ans === 'skip' || ans === '') { state.summary.skipped++; return true; }
+
+    if (ans === 'p' || ans === 'promote') {
+      if (!verbsFor(task).includes('promote')) { console.log(`  ? #${task.id} is '${task.status}' — promote does not apply`); continue; }
+      try {
+        const data = await promoteTask(task.id);
+        state.summary.promoted++;
+        const assigned = data && data.assigned_credits_reward;
+        console.log(`  ✓ #${task.id} → ready${assigned ? ` (reward gate assigned ${assigned} credits)` : ''}`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    if (ans === 'k' || ans === 'kill') {
+      const reason = (await prompt(rl, '  reason (optional, enter to skip): ')).trim();
+      try {
+        await killTask(task.id, reason || 'retired during /backlog-review — not going to happen');
+        state.summary.killed++;
+        console.log(`  ✖ #${task.id} abandoned (restorable: POST /tasks/${task.id}/promote returns it to backlog)`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    if (ans === 'w' || ans === 'water') {
+      try {
+        await waterTask(task.id);
+        state.summary.watered++;
+        console.log(`  ~ #${task.id} watered — the rot clock is reset; nothing else changed`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    console.log('  ? unknown — type p, k, w, s, or q');
+  }
+}
+
+async function main() {
+  await requireSession();
+
+  const goalId = arg('--goal');
+  const walkAll = hasFlag('--all');
+  const limitRaw = Number(arg('--limit'));
+  const walkLimit = walkAll ? Infinity : (Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : DEFAULT_WALK_LIMIT);
+
+  let rows;
+  try {
+    rows = await listBacklog({ goalId });
+  } catch (err) {
+    console.error(`backlog-review: ${err.message}`);
+    return cliExit(1);
+  }
+
+  const buckets = partitionBacklog(rows);
+  printCounts(buckets);
+
+  // Goal titles for the group headers — one extra read so a header names the goal
+  // instead of showing a bare id the reviewer has to go look up.
+  const goalTitles = await fetchGoalTitles();
+
+  // Stranded first, then the nod queue — see partitionBacklog's header. Each
+  // bucket is walked goal-by-goal (groupByGoal), and the flattened result keeps
+  // that grouping so the walk's own loop stays a simple sequence.
+  const queue = [];
+  for (const [bucket, label] of [[buckets.stranded, 'STRANDED'], [buckets.nod, 'awaiting a nod']]) {
+    for (const group of groupByGoal(bucket)) {
+      queue.push(...group.rows.map((t, i) => ({
+        task: t,
+        label,
+        // The header rides on the FIRST row of each group, so it prints exactly
+        // once even after the --limit slice cuts the queue mid-group.
+        groupHeader: i === 0
+          ? `${label === 'STRANDED' ? 'Stranded in' : 'Goal'} ${group.goal_id}${goalTitles.get(group.goal_id) ? ` — ${goalTitles.get(group.goal_id)}` : ''} (${group.rows.length} row${group.rows.length === 1 ? '' : 's'})`
+          : null,
+      })));
+    }
+  }
+
+  if (!queue.length) {
+    console.log('\nNothing to review — no backlog row is waiting on a person today.');
+    return cliExit(0);
+  }
+
+  const slice = queue.slice(0, walkLimit === Infinity ? queue.length : walkLimit);
+  if (slice.length < queue.length) {
+    console.log(`\nWalking the ${slice.length} oldest of ${queue.length} (--limit N or --all for more).`);
+  }
+
+  const state = { summary: { promoted: 0, killed: 0, watered: 0, skipped: 0 } };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (let i = 0; i < slice.length; i++) {
+      if (slice[i].groupHeader) {
+        console.log(`\n${'─'.repeat(72)}\n${slice[i].groupHeader}\n${'─'.repeat(72)}`);
+      }
+      const keepGoing = await walkRow(rl, slice[i].task, i, slice.length, slice[i].label, state);
+      if (!keepGoing) { console.log('\n(quit early)'); break; }
+    }
+  } finally {
+    rl.close();
+  }
+
+  const s = state.summary;
+  console.log(`\nReviewed: ${s.promoted} promoted · ${s.killed} killed · ${s.watered} watered · ${s.skipped} skipped`);
+  const left = queue.length - (s.promoted + s.killed + s.watered);
+  if (left > 0) console.log(`${left} row(s) still awaiting a human — run /backlog-review again to continue.`);
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`backlog-review: ${err && err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  groupByGoal,
+  partitionBacklog,
+  verbsFor,
+  unsatisfiedDeps,
+  deadDeps,
+  DEAD_DEP_STATUSES,
+  MAX_API_LIMIT,
+  DEFAULT_WALK_LIMIT,
+};

package/scripts/gds/build-cli-package.js

@@ -35,7 +35,7 @@ const REPO_ROOT = path.join(__dirname, '..', '..');
 
 // The package's OWN version — deliberately independent of the core's. The core moves many times
 // a day (CI auto-patch, ADR 0161); the CLI's public contract should not.
-const PACKAGE_VERSION = '0.1.2';
+const PACKAGE_VERSION = '0.1.3';
 const PACKAGE_NAME = '@cloudbongos/cli';
 
 // ── What the package carries ────────────────────────────────────────────────────────────────

package/scripts/gds/cli-lib.js

@@ -229,12 +229,117 @@ async function loadSession() {
   return null;
 }
 
+// ---- the shared session store (task 1003741, ADR 0269) ---------------------
+// ONE FILE PER INSTANCE, at a FIXED anchor — deliberately NOT configHome().
+//
+// WHY A FIXED ANCHOR. configHome() is brand-derived, and the brand is read out of whatever checkout
+// the process is standing in. That gave the CLI exactly one session slot, and the slot MOVED: run
+// standalone (the public @cloudbongos/cli's whole situation) the brand cannot resolve, so every
+// instance shared one gds-session.json and signing into a second DESTROYED the first; run from
+// inside an instance repo and the session landed in ~/.config/<slug>/ where the standalone CLI
+// could never find it. The owner's own config dir carries a hand-made `hermeslines-clobber` backup
+// from the first mode.
+//
+// WHY HERE AND NOT instance-config.js. That module is generic config-path machinery shared with the
+// server; a CLI session store is not its concern, and cli-lib already owns SESSION_PATH and
+// SESSION_READ_PATHS. Keeping the two together means one file describes where a session lives.
+function sessionStoreDir() {
+  // Directory name deliberately NOT 'sessions': that is a live module key, and ADR 0083
+  // §Decision #4 forbids naming one in shared machinery. 'instances' is the truer name anyway —
+  // one file per instance is exactly what this holds.
+  return path.join(os.homedir(), '.config', ic.FALLBACK_DIR, 'instances');
+}
+
+// The store's filename for an instance, derived from its api_base host. Returns null when the base
+// names no host — an unkeyable session is simply not stored, never stored under a guessed name.
+function sessionHostKey(apiBase) {
+  const raw = String(apiBase || '').trim();
+  if (!raw) return null;
+  let host = null;
+  try { host = new URL(raw).host; } catch (_) { host = null; }
+  if (!host) return null;
+  // Filename-safe, and collision-free for real hosts: ':' (a port) is the only character a valid
+  // host adds beyond the safe set, and it maps to '_' which cannot otherwise appear in one.
+  const safe = host.replace(/[^A-Za-z0-9._-]/g, '_');
+  return safe && safe !== '.' && safe !== '..' ? safe : null;
+}
+
+function sessionStorePath(apiBase) {
+  const key = sessionHostKey(apiBase);
+  return key ? path.join(sessionStoreDir(), `${key}.json`) : null;
+}
+
+// Write one session into the shared, host-keyed store. No-op when the session names no host —
+// an unkeyable session is skipped, never filed under a guessed name.
+async function writeSessionToStore(session) {
+  const target = session && sessionStorePath(session.api_base);
+  if (!target) return null;
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  await fsp.chmod(path.dirname(target), 0o700).catch(() => {});
+  await fsp.writeFile(target, JSON.stringify(session, null, 2), { mode: 0o600 });
+  return target;
+}
+
+// Every instance's session is kept, not just the last one (task 1003741).
+//
+// This used to write ONE file, so `bongos login <another-instance>` silently DESTROYED the session
+// you already had — the owner's own config dir carries a hand-made `hermeslines-clobber` backup
+// from exactly that. Three steps now, and the order matters:
+//
+//   1. archive the OUTGOING session first. That is what rescues a session written before the store
+//      existed: it was never in the store, so without this step the very first login after
+//      upgrading would still lose it.
+//   2. store the incoming one under its own host.
+//   3. write the ACTIVE pointer exactly where it has always gone, so every existing reader —
+//      in-repo skills, hooks, the dev box — behaves identically.
 async function saveSession(session) {
   const dir = path.dirname(SESSION_PATH);
   await fsp.mkdir(dir, { recursive: true });
+
+  try {
+    const prev = await loadSession();
+    const prevKey = prev && prev.token ? sessionHostKey(prev.api_base) : null;
+    const nextKey = sessionHostKey(session && session.api_base);
+    if (prevKey && prevKey !== nextKey) await writeSessionToStore(prev);
+  } catch (_) {
+    // Archiving is best-effort — a lost previous session must never block a real sign-in.
+  }
+
+  await writeSessionToStore(session).catch(() => null);
   await fsp.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
 }
 
+// The stored session for one instance, or null. Used by `bongos login` to switch back to an
+// instance you are already signed into without a fresh device flow.
+async function loadStoredSession(apiBase) {
+  const target = sessionStorePath(apiBase);
+  if (!target) return null;
+  return readSessionFile(target);
+}
+
+// Every instance this machine has a stored session for — so the CLI can say which one it is
+// targeting and what else it remembers. Sorted for a stable listing; never throws.
+function listStoredSessions() {
+  let names = [];
+  try { names = fs.readdirSync(sessionStoreDir()); } catch (_) { return []; }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(sessionStoreDir(), name), 'utf8'));
+      if (j && j.token) {
+        out.push({
+          host: name.slice(0, -5),
+          api_base: j.api_base || null,
+          login: (j.builder && j.builder.github_login) || null,
+          instance: (j.instance && j.instance.name) || null,
+        });
+      }
+    } catch (_) { /* a corrupt entry is skipped, never fatal */ }
+  }
+  return out.sort((a, b) => a.host.localeCompare(b.host));
+}
+
 function loadSessionSync() {
   for (const p of SESSION_READ_PATHS) {
     if (!fs.existsSync(p)) continue;
@@ -1006,6 +1111,11 @@ module.exports = {
   loadSession,
   loadSessionSync,
   saveSession,
+  sessionStoreDir,
+  sessionHostKey,
+  sessionStorePath,
+  loadStoredSession,
+  listStoredSessions,
   arg,
   argText,
   hasFlag,

package/scripts/gds/login.js

@@ -22,7 +22,7 @@
 
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
-const { saveSession } = require('./cli-lib');
+const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
 const { branding } = require('../../src/branding');
 
 // --- pure helpers (unit-tested) ---------------------------------------------
@@ -204,6 +204,30 @@ async function main() {
   const idp = (man.data.auth && man.data.auth.idp) || null;
   log(`  Signing in to ${instanceName}${doorWord}${idp ? ' — via Cloud Bongos platform sign-in' : ''}`);
 
+  // 1b. Already signed in to THIS instance? Switch back instead of re-running a browser flow
+  //     (task 1003741). Sessions are now kept per instance, so moving between two projects should
+  //     cost nothing. The stored token is VERIFIED against the instance before it is trusted — an
+  //     expired or revoked one falls straight through to the real flow below.
+  if (!process.argv.includes('--force')) {
+    let stored = null;
+    try { stored = await loadStoredSession(base); } catch (_) { stored = null; }
+    if (stored && stored.token) {
+      const me = await fetchJson(`${base}/api/gds/me`, { headers: { Authorization: `Bearer ${stored.token}` } });
+      if (me.ok && me.data && me.data.builder) {
+        await saveSession({ ...stored, builder: me.data.builder, api_base: base,
+          instance: { name: instanceName, origin: base } });
+        const back = me.data.builder.github_login || me.data.builder.display_name || 'you';
+        log('');
+        log(`  ✓ Already signed in to ${instanceName} as ${back} — switched, no browser needed.`);
+        logOtherInstances(base, log);
+        log('  Next:  bongos start  (see what you can claim)');
+        log('  (Re-run with --force to sign in as somebody else.)');
+        return;
+      }
+      log('  Your saved session for this instance has expired — signing in again.');
+    }
+  }
+
   // 2. Device flow.
   let flow = await runDeviceFlow(base, { log, idp });
 
@@ -280,9 +304,23 @@ async function main() {
   const who = (flow.builder && (flow.builder.github_login || flow.builder.display_name)) || 'you';
   log('');
   log(`  ✓ Signed in to ${instanceName} as ${who}.`);
+  logOtherInstances(base, log);
   log('  Next:  bongos start  (see what you can claim)  ·  bongos code / bongos shell  (get on your dev box)');
 }
 
+// Name the OTHER instances this machine is signed into, and how to move between them (task
+// 1003741). Signing in used to destroy the session you already had, so there was never anything
+// to say; now that every instance is kept, silence would leave a builder unable to find them.
+function logOtherInstances(base, log) {
+  let others = [];
+  try {
+    others = listStoredSessions().filter((s) => s.api_base && s.api_base !== base);
+  } catch (_) { return; }
+  if (!others.length) return;
+  const names = others.map((s) => s.instance || s.host);
+  log(`  Also signed in to ${names.join(', ')} — switch with \`bongos login <url>\` (no browser needed).`);
+}
+
 if (require.main === module) {
   main().catch((err) => {
     console.error(`✖ ${err.message}`);
@@ -290,4 +328,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { normalizeInstanceBase, pollDecision, runDeviceFlow };
+module.exports = { normalizeInstanceBase, pollDecision, runDeviceFlow, logOtherInstances };

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.617'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.619'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -288,6 +288,32 @@ module.exports = {
   // it instead of reaching into src/branding.js directly (BV1.R86).
   userAgent: branding.userAgent,
   resolveEnv: instanceConfig.resolveEnv,
+  // --- the two ROOTS (ADR 0108 §1), added for task 1003739 because a module
+  //     that reads BOTH a core default and a host override cannot tell them
+  //     apart without these — and getting that wrong is silent, not loud.
+  //
+  //     resolveCoreRoot()     — where the core PACKAGE's own files live: core
+  //                             modules/, core migrations/, the *.neutral.json
+  //                             defaults. In a single checkout it is the repo
+  //                             root; once an instance installs the core as a
+  //                             dependency it is node_modules/@cloudbongos/core.
+  //     resolveInstanceRoot() — where HOST content lives: config/, instance
+  //                             modules/, identity. The instance repo, always.
+  //
+  //     THE FAILURE THEY EXIST TO PREVENT, stated because it already happened.
+  //     modules/government/config.js resolved BOTH from `path.resolve(__dirname,
+  //     '..', '..')` — correct while the two roots coincided, and wrong the day
+  //     cloudbongos.com started running a PINNED core. Its instance pack then
+  //     resolved to node_modules/@cloudbongos/core/config/government.json: the
+  //     host's real file was never read, and a ratified constitutional amendment
+  //     was written into node_modules, where the next `npm ci` erased it. The
+  //     board had decided and the decision quietly did not take. There is no
+  //     error to catch in that shape — both paths exist and both are writable —
+  //     so the only defence is resolving each from the root that owns it.
+  //     src/branding.js is the pattern to copy: NEUTRAL from the core root,
+  //     INSTANCE from the instance root.
+  resolveCoreRoot: instanceConfig.resolveCoreRoot,
+  resolveInstanceRoot: instanceConfig.resolveInstanceRoot,
   // --- the project's STALE-CLAIM TIMER (task 1003476, goal 1000072) — how long a
   //     claim may go silent before this project calls it abandoned. ONE number for
   //     every surface that reports or enforces it: before this, the sweeper that