@bongos/core 1.18.0 → 1.18.18

package/modules/dev-box/app/scripts/gen-icons.js

@@ -0,0 +1,286 @@
+// modules/dev-box/app/scripts/gen-icons.js — generate the app + tray icons from
+// pixel grids (no binary sources to maintain; re-run after edits: npm run icons).
+//
+// The MOTIF is a bongo pair — a large drum and a small one, joined, the emblem
+// the neutral pack already draws in its favicon and the DMG backdrop. It is
+// brand-NEUTRAL geometry: it says "this is the Dev Box", not "this is one
+// particular host's world". (It replaces a shipping-container + wave-footer motif
+// that belonged to one instance's lore and shipped into every build.)
+//
+// The COLOURS are a build input, not baked in — the posture gen-brand.js holds for
+// the app's strings and gen-dmg-backdrop.py holds for the install screen (ADR 0145).
+// The palette comes from the resolved pack's `theme.ui.colors`, so ONE source tree
+// renders the vanilla Cloud Bongos icons here and a host instance's own icons there.
+//
+// ONE source, resolved exactly as gen-brand.js resolves it (docs/branding-contract.md):
+//     BONGOS_BRANDING_FILE -> config/branding.json -> config/branding.neutral.json
+//
+// Uses sharp from the REPO ROOT's node_modules (the art pipeline already
+// depends on it) so this subproject keeps zero runtime deps of its own.
+//
+// Outputs (committed):
+//   build-resources/icon.png             1024×1024 app icon (electron-builder
+//                                        derives .icns/.ico from it)
+//   assets/tray/mac-<state>Template.png  16px mono template (+@2x 32px)
+//   assets/tray/win-<state>.png          32px colored
+// States: off | on | busy | alert
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+// sharp is a repo-root devDep (the art pipeline already needs it), not a dep
+// of this subproject — so resolve it from a few candidate roots rather than a
+// single brittle relative path: normal resolution (NODE_PATH / a local
+// install) first, then the repo root walked up from here. Fail with an
+// actionable message instead of a raw MODULE_NOT_FOUND.
+function resolveSharp() {
+  const candidates = [
+    'sharp',
+    path.join(__dirname, '..', 'node_modules', 'sharp'),
+    path.join(__dirname, '..', '..', 'node_modules', 'sharp'),
+  ];
+  for (const c of candidates) {
+    try { return require(c); } catch { /* try the next root */ }
+  }
+  throw new Error(
+    "gen-icons: cannot find 'sharp'. Run `npm install` at the repo root " +
+    '(sharp is a root devDep shared with the art pipeline), then retry.'
+  );
+}
+const sharp = resolveSharp();
+
+const APP_DIR = path.resolve(__dirname, '..');             // modules/dev-box/app
+const REPO_ROOT = path.resolve(APP_DIR, '..', '..', '..'); // repo root
+const OUT_TRAY = path.join(APP_DIR, 'assets', 'tray');
+const OUT_BUILD = path.join(APP_DIR, 'build-resources');
+
+// theme.ui.colors key → the value used when a pack omits it. Every fallback here
+// is the NEUTRAL pack's own colour, so a literal in this file is never a brand.
+//
+// Every role MUST be one gen-brand.js's buildThemeCss emits into the app's :root —
+// that CSS block is the surface a host pack author actually fills. A role outside
+// it has nothing prompting a host to define it, so its "fallback" would paint a
+// Cloud Bongos colour into a fully-specified host build.
+const COLOR_ROLES = {
+  bgCard: '#ffffff', bgDeep: '#ffedd5', ink: '#2a1f17',
+  rule: '#fdba74', ruleSoft: '#fed7aa',
+  accent: '#f97316', accentDeep: '#ea580c', terracotta: '#fb7185',
+};
+
+// The pack, resolved exactly as gen-brand.js resolves it (env → instance → neutral).
+//
+// Deliberately NOT read from src/brand.generated.json, which also carries colours:
+// that artifact is TRACKED holding the neutral values and nothing on the icon path
+// regenerates it, so preferring it would let a stale checked-in file outrank the
+// host's own pack. The pack decides, every time.
+function readBranding() {
+  const candidates = [
+    process.env.BONGOS_BRANDING_FILE,
+    path.join(REPO_ROOT, 'config', 'branding.json'),
+    path.join(REPO_ROOT, 'config', 'branding.neutral.json'),
+  ].filter(Boolean);
+  for (const f of candidates) {
+    try { return { file: f, branding: JSON.parse(fs.readFileSync(f, 'utf8')) }; } catch { /* try next */ }
+  }
+  throw new Error('gen-icons: no branding file found (looked for config/branding.json, config/branding.neutral.json)');
+}
+
+// A pack colour, or the neutral fallback when the pack omits it or writes junk —
+// one malformed hex must not abort a build over an icon.
+function palette(branding) {
+  const colors = (((branding.theme || {}).ui) || {}).colors || {};
+  const out = {};
+  for (const [role, fallback] of Object.entries(COLOR_ROLES)) {
+    const v = String(colors[role] || '').trim();
+    out[role] = /^#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3})?$/.test(v) ? v : fallback;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 16×16 tray grids. Legend: '.' transparent · '#' rim/shell · 'h' head · 'f' shell
+// fill · 'm' state mark
+//
+// The bongo pair, three-quarter view: a large drum left, the small one joined at
+// its right with its head sitting two rows lower. Two things make it read as DRUMS
+// at 16px rather than boxes: the head is an oval that OVERHANGS the narrower shell
+// (a flat top of the same size reads as a crate), and the profile is SQUAT — a
+// bongo is about as wide as it is tall, so a tall shell reads as a jar.
+//
+// Every state keeps that silhouette and differs in SHAPE as well as colour,
+// because the macOS template icons are monochrome: hollow (off) · filled (on) ·
+// struck heads + beats overhead (busy) · a corner badge (alert).
+// ---------------------------------------------------------------------------
+const GRIDS = {
+  off: [
+    '................',
+    '................',
+    '................',
+    '................',
+    '..#######.......',
+    '.#.......#......',
+    '..#######.......',
+    '...#...#.#####..',
+    '...#...##.....#.',
+    '...#...#.#####..',
+    '...#...#.#...#..',
+    '...#...#.#...#..',
+    '...#####.#####..',
+    '................',
+    '................',
+    '................',
+  ],
+  on: [
+    '................',
+    '................',
+    '................',
+    '................',
+    '..#######.......',
+    '.#hhhhhhh#......',
+    '..#######.......',
+    '...#fff#.#####..',
+    '...#fff##hhhhh#.',
+    '...#fff#.#####..',
+    '...#fff#.#fff#..',
+    '...#fff#.#fff#..',
+    '...#####.#####..',
+    '................',
+    '................',
+    '................',
+  ],
+  busy: [
+    '................',
+    '................',
+    '....m...m...m...',
+    '................',
+    '..#######.......',
+    '.#hhhhhhh#......',
+    '..#######.......',
+    '...#...#.#####..',
+    '...#...##hhhhh#.',
+    '...#...#.#####..',
+    '...#...#.#...#..',
+    '...#...#.#...#..',
+    '...#####.#####..',
+    '................',
+    '................',
+    '................',
+  ],
+  alert: [
+    '............mmm.',
+    '............mmm.',
+    '............mmm.',
+    '................',
+    '..#######.......',
+    '.#.......#......',
+    '..#######.......',
+    '...#...#.#####..',
+    '...#...##.....#.',
+    '...#...#.#####..',
+    '...#...#.#...#..',
+    '...#...#.#...#..',
+    '...#####.#####..',
+    '................',
+    '................',
+    '................',
+  ],
+};
+
+function gridToSvg(grid, pal, cell = 1) {
+  const h = grid.length;
+  const w = grid[0].length;
+  const rects = [];
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const color = pal[grid[y][x]];
+      if (!color) continue;
+      rects.push(`<rect x="${x * cell}" y="${y * cell}" width="${cell}" height="${cell}" fill="${color}"/>`);
+    }
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w * cell}" height="${h * cell}" shape-rendering="crispEdges">${rects.join('')}</svg>`;
+}
+
+async function renderPng(svg, size, file) {
+  await sharp(Buffer.from(svg)).resize(size, size, { kernel: 'nearest' }).png().toFile(file);
+  console.log('wrote', path.relative(process.cwd(), file));
+}
+
+// The app icon: the pack's field + border, the bongo pair, a beat line at the foot.
+// Built as a 32×32 grid then nearest-upscaled to 1024 so it keeps the pixel look at
+// every size electron-builder derives.
+function buildAppGrid() {
+  const rows = [];
+  for (let y = 0; y < 32; y++) rows.push('.'.repeat(32).split(''));
+  const put = (x, y, c) => { if (rows[y] && rows[y][x] !== undefined) rows[y][x] = c; };
+  // Radii are nudged by half a cell so the boundary row/column lands ON the grid
+  // instead of being clipped away — otherwise a 3-row oval renders as 1.
+  const oval = (cx, cy, rx, ry, c) => {
+    for (let y = cy - ry; y <= cy + ry; y++) for (let x = cx - rx; x <= cx + rx; x++) {
+      const dx = (x - cx) / (rx + 0.5);
+      const dy = (y - cy) / (ry + 0.5);
+      if (dx * dx + dy * dy <= 1) put(x, y, c);
+    }
+  };
+
+  for (let y = 2; y < 30; y++) for (let x = 2; x < 30; x++) put(x, y, 'p');
+  for (let x = 2; x < 30; x++) { put(x, 2, 'b'); put(x, 29, 'b'); }
+  for (let y = 2; y < 30; y++) { put(2, y, 'b'); put(29, y, 'b'); }
+
+  // One drum: a shell hanging from the head's centre line, then the head oval
+  // drawn over it — so the head overhangs the shell, the cue that reads as a drum.
+  const drum = (cx, cy, rx, ry, shellRx, yBase, shell) => {
+    for (let y = cy; y <= yBase; y++) for (let x = cx - shellRx; x <= cx + shellRx; x++) put(x, y, 'k');
+    for (let y = cy; y < yBase; y++) for (let x = cx - shellRx + 1; x < cx + shellRx; x++) put(x, y, shell);
+    oval(cx, cy, rx, ry, 'k');
+    oval(cx, cy, rx - 1, ry - 1, 'h');
+  };
+  drum(11, 12, 7, 3, 5, 24, 't');  // the large drum
+  drum(22, 15, 5, 3, 3, 24, 's');  // the small one, drawn second so it sits in front
+
+  // The beat: four even strokes across the foot — rhythm without a world-specific
+  // motif, echoing the DMG backdrop's beat line. Spanning the full width (rather
+  // than sitting under each shell) keeps them reading as a strip, not as legs.
+  for (let x = 5; x <= 23; x += 6) for (let dx = 0; dx < 3; dx++) { put(x + dx, 26, 'd'); put(x + dx, 27, 'd'); }
+
+  return rows.map((r) => r.join(''));
+}
+
+async function main() {
+  fs.mkdirSync(OUT_TRAY, { recursive: true });
+  fs.mkdirSync(OUT_BUILD, { recursive: true });
+
+  const { file, branding } = readBranding();
+  const p = palette(branding);
+
+  // macOS template: pure black + alpha, for EVERY state. This is an OS
+  // requirement, not a brand choice — the system recolours a *Template.png itself
+  // (menu-bar light/dark, inverted when selected), and any colour in the source
+  // is discarded. Branding one of these would be a bug, not a feature.
+  const MAC = { '#': '#000000', f: '#000000', h: '#000000', m: '#000000' };
+  // Windows: state via colour on a taskbar we don't control — it may be light OR
+  // dark, so every state outlines in the pack's DEEP accent, the one tone that
+  // holds contrast against both. The pale tints only ever appear as fill inside
+  // that outline, where the shape is already legible.
+  const WIN = {
+    off: { '#': p.accentDeep },
+    on: { '#': p.accentDeep, f: p.accent, h: p.bgDeep },
+    busy: { '#': p.accentDeep, h: p.accent, m: p.accent },
+    alert: { '#': p.accentDeep, m: p.terracotta },
+  };
+
+  for (const state of Object.keys(GRIDS)) {
+    const macSvg = gridToSvg(GRIDS[state], MAC);
+    await renderPng(macSvg, 16, path.join(OUT_TRAY, `mac-${state}Template.png`));
+    await renderPng(macSvg, 32, path.join(OUT_TRAY, `mac-${state}Template@2x.png`));
+    await renderPng(gridToSvg(GRIDS[state], WIN[state]), 32, path.join(OUT_TRAY, `win-${state}.png`));
+  }
+
+  const APP_PALETTE = {
+    p: p.bgCard, b: p.rule, k: p.ink,
+    t: p.accent, s: p.terracotta, h: p.ruleSoft, d: p.accentDeep,
+  };
+  await renderPng(gridToSvg(buildAppGrid(), APP_PALETTE), 1024, path.join(OUT_BUILD, 'icon.png'));
+  console.log(`gen-icons: palette ← ${path.relative(REPO_ROOT, file)}`);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/modules/dev-box/app/scripts/vendor-client.js

@@ -0,0 +1,23 @@
+// devbox-app/scripts/vendor-client.js — vendor the generated CJS API client
+// into src/vendor/ so it ships INSIDE the packaged asar.
+//
+// The devbox app is a self-contained, zero-dependency subproject (ADR 0045): it
+// is never `npm install`ed and electron-builder packages `src/**` only, so it
+// cannot require() the repo's clients/bongos-client/ at runtime. This copies the
+// committed CJS build in verbatim (byte-for-byte) so gds-client.js can require
+// './vendor/bongos-client.cjs'. Vendoring a generated FILE (not an npm dep) keeps
+// the subproject dependency-free. The main repo's api_client test asserts this
+// copy stays byte-identical to the canonical build, so drift fails CI.
+//
+// Run: npm run vendor  (also invoked before `start`, `test`, and `dist:*`).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SRC = path.resolve(__dirname, '../../../../clients/bongos-client/index.cjs');
+const DEST = path.resolve(__dirname, '../src/vendor/bongos-client.cjs');
+
+const bytes = fs.readFileSync(SRC);
+fs.mkdirSync(path.dirname(DEST), { recursive: true });
+fs.writeFileSync(DEST, bytes);
+console.log(`vendor-client: ${path.relative(process.cwd(), DEST)} (${bytes.length} bytes) ← clients/bongos-client/index.cjs`);

package/modules/dev-box/app/src/box-controller.js

@@ -0,0 +1,287 @@
+// devbox-app/src/box-controller.js — the app's state machine.
+//
+// Owns: the polled view of GET /box/me (+ /box/terminal), the on/off actions,
+// poll cadence, and transition events (for notifications + tray updates). The
+// pure decision helpers are exported separately so test/unit.mjs can pin them
+// without Electron.
+//
+// Status vocabulary the UI/tray consume (derived, NOT the raw box.state):
+//   signed_out | loading | none | provisioning | active
+//   | closing | error
+//
+// Cost posture (deliberate, with one narrow exception): the app NEVER sends
+// claude_active heartbeats, so the droplet's idle sweep stays authoritative — a
+// box nobody is using is reclaimed in ~10–15 min and the app just reflects that.
+// The exception (leg 3): while the app is ACTIVELY pointed at the box (panel open,
+// or within HEARTBEAT_WINDOW_MS of a connect action) it sends BODY-LESS heartbeats
+// that bump last_activity_at only — never claude_active. That stops the box reaping
+// out from under a builder who is mid-connect (the vicious cycle where a failing
+// connect lets the box rebuild with fresh host keys) WITHOUT keeping a genuinely
+// idle box (app closed, no recent connect) alive. See shouldHeartbeat().
+
+// Derive the UI status from a GET /box/me payload.
+function deriveStatus(payload) {
+  if (!payload || !payload.box) return 'none';
+  const state = payload.box.state || 'none';
+  const intent = payload.open_intent || null;
+  if (intent && intent.action === 'deprovision') return 'closing';
+  if (intent && (intent.action === 'provision' || intent.action === 'wake')) return 'provisioning';
+  if (state === 'active') return 'active';
+  if (state === 'provisioning' || state === 'waking') return 'provisioning';
+  if (state === 'parking') return 'closing';
+  // parked = off-but-resumable; surfaced as plain "off" — the switch wakes it.
+  if (state === 'parked' || state === 'none' || state === 'destroyed') return 'none';
+  if (state === 'error') return 'error';
+  return 'none';
+}
+
+// Poll cadence by status (ms). Transitions poll fast; settled states slow.
+function pollDelayMs(status) {
+  switch (status) {
+    case 'provisioning':
+    case 'closing': return 5_000;
+    case 'active': return 60_000;
+    case 'error': return 60_000;
+    default: return 120_000; // none / signed_out idle tick
+  }
+}
+
+// Leg 3 — connect-window keep-alive. The heartbeat timer ticks at this cadence,
+// well under the box-side cron (5 min) and the idle threshold (10 min), so even a
+// short connect window defers a reap.
+const HEARTBEAT_TICK_MS = 120_000;     // 2 min
+// Keep beating for this long after a deliberate connect action (box on / terminal
+// open) so retries during a flaky connect stay covered even if the panel is hidden.
+const HEARTBEAT_WINDOW_MS = 600_000;   // 10 min
+
+// PURE (unit-tested): should the app send a keep-alive heartbeat right now? Only
+// when the box is active AND the app is actively pointed at it — panel visible, or
+// within HEARTBEAT_WINDOW_MS of a connect action. An idle box (app closed, no
+// recent connect) returns false, so it still reaps on schedule (cost posture).
+function shouldHeartbeat({ status, panelVisible, lastConnectActionAt, now }) {
+  if (status !== 'active') return false;
+  if (panelVisible) return true;
+  return Boolean(lastConnectActionAt) && (now - lastConnectActionAt) < HEARTBEAT_WINDOW_MS;
+}
+
+// Map a status transition to a user-facing notification (or null).
+// `ctx.envName` = the Claude Desktop environment name.
+function transitionNotification(prev, next, ctx = {}) {
+  if (prev === next) return null;
+  if (next === 'active') {
+    return {
+      title: 'Your dev box is ready',
+      body: ctx.settingsInstalled
+        ? `Restart Claude Desktop, then Code → Environment → “${ctx.envName}”. The browser terminal works too.`
+        : 'Connect from the app panel — browser terminal or SSH.',
+    };
+  }
+  if (prev === 'active' && next === 'none') {
+    return {
+      title: 'Your dev box closed',
+      body: 'It shut down (boxes rest after ~10 idle minutes, or when closed). Flip the switch to raise it again.',
+    };
+  }
+  if (next === 'error') {
+    return {
+      title: 'Your dev box hit an error',
+      body: 'Flip the switch to try again, or ask in #support on Discord.',
+    };
+  }
+  return null;
+}
+
+// createBoxController({ client, signedIn, onChange, onNotify, sleep? })
+// onChange(snapshot) fires on every refresh; onNotify({title, body}) on
+// meaningful transitions. Snapshot shape is what ipc.js ships to the renderer.
+function createBoxController({ client, signedIn, onChange, onNotify, envName }) {
+  let status = 'loading';
+  let box = null;
+  let terminal = null;          // { url, credential } when active+ready
+  let lastError = null;
+  let settingsInstalled = false; // set by main.js after ssh-setup runs
+  let hostKeys = null;           // { ok, reason?, attempt? } — #909 pinning status
+  let keyRegistered = null;      // { ok, reason, fingerprint, attempts } — task 1002509
+  let busy = false;              // an ensure/close request is in flight
+  let timer = null;
+  let stopped = false;
+  let panelVisible = false;      // leg 3: main.js pushes BrowserWindow show/hide
+  let lastConnectActionAt = 0;   // leg 3: stamped on box-on / terminal-open
+  let hbTimer = null;            // leg 3: keep-alive timer (separate from the poll)
+
+  function snapshot() {
+    return {
+      status: signedIn() ? status : 'signed_out',
+      busy,
+      box: box && {
+        state: box.state,
+        hostname: box.hostname,
+        size: box.size_slug,
+        provisionedAt: box.provisioned_at,
+        // task 1187 / idea 235: the box's GDS-reported PUBLIC host keys
+        // (`<keytype> <base64>` per line). main.js pins known_hosts from these
+        // (authoritative — no keyscan/TOFU) when present, else falls back to keyscan.
+        hostKeysText: box.host_keys || null,
+        // When those keys were reported, and when the CURRENT droplet came up. A
+        // report older than the activation belongs to a box that no longer exists,
+        // so main.js keyscans instead of pinning a dead identity (task 1002509).
+        hostKeysAt: box.host_keys_at || null,
+        activeSince: box.active_since || null,
+      },
+      terminal,
+      lastError,
+      settingsInstalled,
+      hostKeys,
+      keyRegistered,
+    };
+  }
+
+  function emit() { onChange(snapshot()); }
+
+  function schedule(ms) {
+    if (stopped) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => refresh().catch(() => {}), ms ?? pollDelayMs(status));
+    // Don't hold the process open for a poll timer.
+    if (timer.unref) timer.unref();
+  }
+
+  // Leg 3: body-less keep-alive while the app is actively pointed at the box (see
+  // the cost-posture note up top). Best-effort — a failed beat just retries next
+  // tick; it never blocks or surfaces an error to the user.
+  function heartbeatTick() {
+    if (stopped || !signedIn()) return;
+    if (!shouldHeartbeat({ status, panelVisible, lastConnectActionAt, now: Date.now() })) return;
+    Promise.resolve(client.boxHeartbeat()).catch(() => {});
+  }
+
+  async function refresh() {
+    if (stopped) return snapshot();
+    if (!signedIn()) {
+      status = 'signed_out';
+      box = null; terminal = null;
+      emit();
+      return snapshot();
+    }
+    try {
+      const payload = await client.boxMe();
+      const prev = status;
+      box = payload.box && payload.box.state !== 'none' ? payload.box : null;
+      status = deriveStatus(payload);
+      lastError = null;
+      // Terminal link only matters when active; warming_up → keep polling.
+      if (status === 'active') {
+        try {
+          const t = await client.boxTerminal();
+          terminal = t && t.url ? { url: t.url, credential: t.credential } : null;
+        } catch { terminal = null; }
+      } else {
+        terminal = null;
+        hostKeys = null; // re-pinned on next activation (#909)
+      }
+      const note = transitionNotification(prev, status, { envName, settingsInstalled });
+      if (note && prev !== 'loading') {
+        onNotify(note);
+      }
+      if (note && status === 'active') {
+        // 'ready' fires even from a cold start (prev === 'loading') if the
+        // box JUST became active from this app's own ensure — handled by main.
+      }
+    } catch (err) {
+      if (err && err.status === 401) {
+        status = 'signed_out';
+      } else {
+        lastError = err.message || 'unreachable';
+        if (status === 'loading') status = 'error';
+      }
+    }
+    emit();
+    schedule();
+    return snapshot();
+  }
+
+  return {
+    snapshot,
+    refresh,
+    setSettingsInstalled(v) { settingsInstalled = v; emit(); },
+    setHostKeys(v) { hostKeys = v; emit(); },
+    // Registration outcome from ssh-setup.registerKeyWithVerify. Unlike hostKeys it
+    // is NOT cleared when the box goes inactive: the key lives on the builder's
+    // account, so a failure stays visible (and retryable) until it verifies.
+    setKeyRegistered(v) { keyRegistered = v; emit(); },
+    // Leg 3: main.js pushes panel visibility; connect actions stamp a window.
+    setPanelVisible(v) { panelVisible = !!v; },
+    markConnectAttempt() { lastConnectActionAt = Date.now(); },
+
+    // Flip ON: POST /box/ensure, then poll fast. Returns the server message.
+    async turnOn() {
+      lastConnectActionAt = Date.now(); // leg 3: turning the box on is a connect action
+      busy = true; lastError = null; emit();
+      try {
+        return await client.boxEnsure();
+      } catch (err) {
+        lastError = err.body && err.body.error === 'BOX_PROVISION_DENIED'
+          ? `Not allowed: ${err.body.reason || 'provision denied'}`
+          : (err.message || 'request failed');
+        throw err;
+      } finally {
+        busy = false;
+        await refresh();
+      }
+    },
+
+    // Flip OFF: POST /box/close (active only — the API 409s otherwise).
+    async turnOff() {
+      busy = true; lastError = null; emit();
+      try {
+        return await client.boxClose();
+      } catch (err) {
+        lastError = err.body && err.body.error === 'box_not_active'
+          ? 'The box is mid-change — wait for it to settle, then try again.'
+          : (err.message || 'request failed');
+        throw err;
+      } finally {
+        busy = false;
+        await refresh();
+      }
+    },
+
+    start() {
+      stopped = false;
+      refresh().catch(() => {});
+      // leg 3: a separate, unref'd keep-alive timer (gated by shouldHeartbeat).
+      if (!hbTimer) { hbTimer = setInterval(heartbeatTick, HEARTBEAT_TICK_MS); if (hbTimer.unref) hbTimer.unref(); }
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(timer);
+      if (hbTimer) { clearInterval(hbTimer); hbTimer = null; }
+    },
+  };
+}
+
+// ttyd's HTTP-basic username is the fixed `otb` user (box-terminal.service:
+// --credential "otb:<pass>"); the password is the long hex `credential`.
+const TERMINAL_USER = 'otb';
+
+// Browser-terminal URL with the basic-auth userinfo embedded, so opening it
+// lands signed-in (browsers still honor user:pass@host for top-level
+// navigation; ttyd auth is plain HTTP basic). Falls back to the bare URL if
+// there's no credential or the URL doesn't parse.
+function terminalAuthUrl(terminal) {
+  if (!terminal || !terminal.url) return null;
+  if (!terminal.credential) return terminal.url;
+  try {
+    const u = new URL(terminal.url);
+    u.username = TERMINAL_USER;
+    u.password = terminal.credential;
+    return u.toString();
+  } catch {
+    return terminal.url;
+  }
+}
+
+module.exports = {
+  createBoxController, deriveStatus, pollDelayMs, transitionNotification,
+  terminalAuthUrl, TERMINAL_USER, shouldHeartbeat,
+};

package/modules/dev-box/app/src/brand.generated.json

@@ -0,0 +1,13 @@
+{
+  "CIV_NAME": "Cloud Bongos",
+  "PRODUCT_NAME": "Cloud Bongos Dev Box",
+  "DESKTOP_ENV_NAME": "Cloud Bongos Dev Box",
+  "PUBLIC_ORIGIN": "http://localhost:3000",
+  "BUILDERS_ORIGIN": "http://localhost:3000",
+  "PRODUCT_SLUG": "Cloud-Bongos-Dev-Box",
+  "APP_ID": "com.cloudbongos.devbox",
+  "COPYRIGHT": "© Cloud Bongos",
+  "CONFIG_DIR": "cloudbongos",
+  "TAGLINE": "Building software is laying down a beat.",
+  "BG_COLOR": "#fff7ed"
+}

package/modules/dev-box/app/src/brand.js

@@ -0,0 +1,16 @@
+// modules/dev-box/app/src/brand.js — the app's brand strings, in ONE place.
+//
+// GENERATED, not hardcoded: scripts/gen-brand.js writes src/brand.generated.json
+// from the instance's config/branding.json at build time (prestart / pretest /
+// predist), so the SAME source tree renders a "Cloud Bongos Dev Box" here and an
+// "Amazonprimea Dev Box" on the OTB instance — no instance name is baked into
+// code (the ADR 0004 posture, generalised to every instance). The generated file
+// is committed (the Cloud Bongos default) so a fresh checkout runs without a
+// generate step; every build regenerates it from the local branding.
+//
+// Keys: CIV_NAME (world/instance name, runtime display only), PRODUCT_NAME,
+// DESKTOP_ENV_NAME, PUBLIC_ORIGIN, BUILDERS_ORIGIN, PRODUCT_SLUG (artifact
+// filenames), APP_ID, COPYRIGHT, CONFIG_DIR (matches the CLI session dir),
+// BG_COLOR (pre-CSS window bg), TAGLINE (panel epigraph).
+
+module.exports = require('./brand.generated.json');

package/modules/dev-box/app/src/config.js

@@ -0,0 +1,19 @@
+// devbox-app/src/config.js — runtime configuration resolution.
+
+const brand = require('./brand');
+
+function apiBase(sessionApiBase) {
+  // Priority: explicit env (dev/staging) → the base recorded in the session
+  // file at sign-in → production default. Trailing slashes are stripped so
+  // path concatenation stays uniform.
+  const raw = process.env.OTB_DEVBOX_API_BASE || sessionApiBase || brand.PUBLIC_ORIGIN;
+  return String(raw).replace(/\/+$/, '');
+}
+
+function appVersion() {
+  // package.json is inside the asar in production; require() resolves it both
+  // packed and in dev.
+  return require('../package.json').version;
+}
+
+module.exports = { apiBase, appVersion };