@bongos/core 1.18.3 → 1.18.19

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

@@ -0,0 +1,610 @@
+// devbox-app/src/main.js — Electron main process for OTB Dev Box (#904,
+// ADR 0045). A tray-resident switch for the builder's hosted dev box:
+// pairing sign-in (browser clicks only), box on/off over the existing
+// own-scoped GDS endpoints, native notifications, and the local SSH /
+// Claude Desktop plumbing the old connect.sh could never finish.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const {
+  app, BrowserWindow, ipcMain, shell, Notification, clipboard, net,
+} = require('electron');
+
+const brand = require('./brand');
+const { apiBase, appVersion } = require('./config');
+const { isUpdateAvailable, resolveTarget, updateBannerText } = require('./updater');
+const sessionStore = require('./session-store');
+const { createClient } = require('./gds-client');
+const { createPairing } = require('./pairing');
+const { createBoxController, terminalAuthUrl, TERMINAL_USER } = require('./box-controller');
+const { shapeClaimableTasks, boxScopeMessage, claimErrorMessage } = require('./task-picker');
+const { createTray } = require('./tray');
+const sshSetup = require('./ssh-setup');
+
+// Windows: required for Notification to display, must match build.appId.
+app.setAppUserModelId(brand.APP_ID);
+
+// One instance only — a second launch just surfaces the panel.
+if (!app.requestSingleInstanceLock()) {
+  app.quit();
+} else {
+  app.on('second-instance', () => showWindow());
+}
+
+let session = sessionStore.read();
+let win = null;
+let tray = null;
+let controller = null;
+let pairing = null;
+let pairingState = null; // { phase, pairCode, verifyUrl } while a pairing runs
+let updateInfo = null;   // { version, url } when a newer release exists
+let lastSetupHostname = null;
+let setupInFlight = false; // re-entrancy guard: setHostKeys → emit → onChange → onActiveSetup
+
+const client = createClient({
+  getToken: () => (session ? session.token : null),
+  getApiBase: () => (session ? session.api_base : null),
+});
+
+// Log to console AND a small persistent file — the Parallels hardware test
+// (#909) showed GUI-launched failures vanish without a trace. The log lives
+// in userData (Help-able path: app.getPath('userData')/devbox.log), truncated
+// when it grows past ~256KB.
+const LOG_FILE = () => path.join(app.getPath('userData'), 'devbox.log');
+function log(...args) {
+  const line = `${new Date().toISOString()} ${args.map(String).join(' ')}`;
+  console.log('[devbox]', ...args);
+  try {
+    const f = LOG_FILE();
+    try { if (require('node:fs').statSync(f).size > 262_144) require('node:fs').truncateSync(f, 0); } catch { /* fresh file */ }
+    require('node:fs').appendFileSync(f, `${line}\n`);
+  } catch { /* logging must never break the app */ }
+}
+
+function notify({ title, body }) {
+  try { new Notification({ title, body }).show(); }
+  catch (e) { log('notification failed:', e.message); }
+}
+
+function meta() {
+  return {
+    civName: brand.CIV_NAME,
+    productName: brand.PRODUCT_NAME,
+    envName: brand.DESKTOP_ENV_NAME,
+    tagline: brand.TAGLINE,
+    version: appVersion(),
+    builder: session && session.builder
+      ? { login: session.builder.github_login, rank: session.builder.rank }
+      : null,
+    pairing: pairingState,
+    update: updateInfo,
+    settingsPath: sshSetup.managedSettingsPath(),
+  };
+}
+
+function pushState() {
+  if (win && !win.isDestroyed()) {
+    win.webContents.send('state', { snapshot: controller.snapshot(), meta: meta() });
+  }
+  if (tray) tray.update(controller.snapshot());
+  captureForVerification();
+}
+
+// Dev/verification hook (README): with OTB_DEVBOX_SCREENSHOT_DIR set, write a
+// PNG of the panel after each state settles — how stub runs and CI capture
+// visual proof without a human watching the tray.
+let captureTimer = null;
+function captureForVerification() {
+  const dir = process.env.OTB_DEVBOX_SCREENSHOT_DIR;
+  if (!dir || !win || win.isDestroyed()) return;
+  clearTimeout(captureTimer);
+  captureTimer = setTimeout(async () => {
+    try {
+      const img = await win.webContents.capturePage();
+      const status = controller ? controller.snapshot().status : 'init';
+      const file = path.join(dir, `panel-${Date.now()}-${status}.png`);
+      require('node:fs').writeFileSync(file, img.toPNG());
+      log('screenshot', file);
+    } catch (e) { log('screenshot failed:', e.message); }
+  }, 600);
+}
+
+// --- window ----------------------------------------------------------------
+
+function createWindow() {
+  win = new BrowserWindow({
+    width: 380,
+    height: 600,
+    show: false,
+    resizable: false,
+    maximizable: false,
+    fullscreenable: false,
+    skipTaskbar: process.platform === 'darwin',
+    title: brand.PRODUCT_NAME,
+    backgroundColor: brand.BG_COLOR,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+    },
+  });
+  win.loadFile(path.join(__dirname, '..', 'renderer', 'index.html'));
+  // Closing hides — the app lives in the tray.
+  win.on('close', (e) => {
+    if (!app.isQuittingForReal) {
+      e.preventDefault();
+      win.hide();
+    }
+  });
+  // leg 3: a visible panel means the builder is actively engaging the box, so keep
+  // it alive (heartbeat) while shown and let it reap normally once hidden.
+  win.on('show', () => { if (controller) controller.setPanelVisible(true); });
+  win.on('hide', () => { if (controller) controller.setPanelVisible(false); });
+  win.webContents.on('did-finish-load', pushState);
+  // The renderer never navigates and opens nothing — belt and braces.
+  win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
+  win.webContents.on('will-navigate', (e) => e.preventDefault());
+}
+
+function showWindow() {
+  if (!win || win.isDestroyed()) createWindow();
+  if (process.platform === 'darwin' && tray) {
+    // Anchor under the menu-bar icon.
+    const b = tray.bounds();
+    if (b && b.x) {
+      win.setPosition(Math.round(b.x + b.width / 2 - 190), Math.round(b.y + b.height + 6), false);
+    }
+  }
+  win.show();
+  win.focus();
+  controller.refresh().catch(() => {});
+}
+
+// --- sign-in / sign-out ----------------------------------------------------
+
+async function signIn() {
+  if (pairing) return; // one at a time
+  pairing = createPairing({ client, openExternal: (u) => shell.openExternal(u) });
+  try {
+    const grant = await pairing.run((update) => {
+      pairingState = update;
+      pushState();
+    });
+    session = sessionStore.write({
+      token: grant.token,
+      builder: grant.builder,
+      apiBase: apiBase(session && session.api_base),
+    });
+    notify({ title: 'Signed in', body: `Connected as @${grant.builder.github_login}.` });
+    afterSignIn().catch((e) => log('post-sign-in setup:', e.message));
+  } catch (err) {
+    if (err.message !== 'cancelled') {
+      pairingState = { phase: 'failed', reason: err.message };
+    }
+  } finally {
+    pairing = null;
+    if (pairingState && pairingState.phase === 'waiting') pairingState = null;
+    pushState();
+    controller.refresh().catch(() => {});
+  }
+}
+
+async function afterSignIn() {
+  pairingState = null;
+  // Register the SSH key (idempotent) + install the Claude Desktop connection
+  // file once, right after sign-in — one elevation prompt at a moment the
+  // user expects setup, not mid-flow later.
+  await runKeySetup();
+  await installSettings();
+  pushState();
+}
+
+// Generate-if-missing + register + VERIFY the builder key, and publish the outcome
+// to the panel. Never throws. Registration failing here used to be logged and
+// forgotten, leaving the box with no builder key in authorized_keys and every later
+// connect refused with nothing to act on (task 1002509).
+async function runKeySetup() {
+  try {
+    const r = await sshSetup.ensureKey({
+      registerKey: (pk, label) => client.registerSshKey(pk, label),
+      listKeys: () => client.listSshKeys(),
+      log,
+    });
+    controller.setKeyRegistered(r.registration);
+    return r.registration;
+  } catch (e) {
+    log('ssh key setup failed:', e.message);
+    const state = { ok: false, reason: 'key_setup_failed', detail: e.message };
+    controller.setKeyRegistered(state);
+    return state;
+  }
+}
+
+// One re-attempt per activation while the key is still unverified — the leg that
+// turns "registration failed at sign-in, silently, forever" into self-healing.
+// Fire-and-forget with its own guards so it never serializes with host-key pinning.
+const keyRegState = { activation: null, inFlight: false };
+function retryKeyRegistration(activationKey) {
+  if (keyRegState.inFlight || keyRegState.activation === activationKey) return;
+  const s = controller.snapshot();
+  if (s.keyRegistered && s.keyRegistered.ok) return;
+  keyRegState.activation = activationKey;
+  keyRegState.inFlight = true;
+  runKeySetup().finally(() => { keyRegState.inFlight = false; });
+}
+
+async function installSettings() {
+  try {
+    const settings = await client.managedSettings();
+    // The load-bearing step (#910): the Desktop environment picker reads
+    // sshConfigs from the PER-USER ~/.claude/settings.json — written here
+    // with no elevation. "Linked ✓" means THIS succeeded.
+    const user = sshSetup.installUserSshConfig(settings, { log });
+    controller.setSettingsInstalled(Boolean(user.ok));
+    // Optional hardening layer: the system managed file (sshHostAllowlist).
+    // Best-effort — a declined UAC/admin prompt must not affect the link.
+    const managed = await sshSetup.installManagedSettings(`${JSON.stringify(settings, null, 2)}\n`, { log });
+    if (!managed.ok && managed.reason !== 'skipped' && managed.reason !== 'unsupported') {
+      log('managed-settings (optional allowlist) not installed:', managed.reason);
+    }
+    return user;
+  } catch (e) {
+    log('settings fetch/install failed:', e.message);
+    controller.setSettingsInstalled(false);
+    return { ok: false, reason: 'failed' };
+  }
+}
+
+async function signOut() {
+  try { await client.logout(); } catch { /* token may already be dead */ }
+  sessionStore.clear();
+  session = null;
+  pairingState = null;
+  controller.refresh().catch(() => {});
+  pushState();
+}
+
+// --- box plumbing on activation ---------------------------------------------
+
+// When the box turns active, line up the local SSH side: fresh host keys in
+// known_hosts (they change on every re-provision). The #909 hardware test
+// found the original one-shot version latched its "done" guard BEFORE the
+// scan succeeded — a box whose sshd wasn't up yet (or a transient tool/PATH
+// failure) meant known_hosts was never written and never retried, silently.
+// Now: retry with backoff while the box stays active, latch only on success,
+// and surface the state to the panel (controller.setHostKeys).
+const hostKeysState = { key: null, attempts: 0, retryPendingKey: null };
+async function onActiveSetup(snapshot, { force = false } = {}) {
+  const hostname = snapshot.box && snapshot.box.hostname;
+  if (!hostname) return;
+  // A box is only reachable if the builder's key is actually on their account, so
+  // re-attempt an unverified registration alongside the host-key work (not awaited —
+  // it must not delay pinning). Guarded to one attempt per activation.
+  retryKeyRegistration(`${hostname}|${(snapshot.box && snapshot.box.activeSince) || ''}`);
+  // Re-entrancy guard. controller.setHostKeys() → emit() → onChange → onActiveSetup,
+  // so without this a single run recursively re-pins; on the keyscan path (which a
+  // just-rebuilt box forces until it re-reports its keys) the overlapping scans
+  // thrash each other and the panel flickers (v1.0.8 bug, task 1319). One at a time.
+  if (setupInFlight) return;
+  setupInFlight = true;
+  try {
+    const key = `${hostname}|${snapshot.box.provisionedAt || ''}`;
+    // Reported keys are only usable when they describe the droplet running NOW. A
+    // report older than active_since belongs to a box that has been rebuilt since —
+    // pinning it IS the "Host denied (verification failed)" lockout — and it must not
+    // be treated as the expected identity by the self-verify below either, or every
+    // poll would condemn a correctly-scanned pin and re-scan (task 1002509).
+    // A GDS that predates active_since on /box/me gives us nothing to compare, and a
+    // SHIPPED binary may well be talking to one — so the veto only applies when the
+    // server actually served it. Otherwise the pre-existing authoritative path stands.
+    const activeSince = snapshot.box && snapshot.box.activeSince;
+    const staleReport = Boolean(activeSince) && sshSetup.reportedKeysAreStale({
+      hostKeysAt: snapshot.box && snapshot.box.hostKeysAt,
+      activeSince,
+    });
+    const rawReported = snapshot.box && snapshot.box.hostKeysText;
+    const reported = staleReport ? null : rawReported;
+    // Self-heal, not "pin once". Skip ONLY if we already pinned for this activation
+    // AND the box's CURRENT identity is still actually present in known_hosts. A
+    // rebuild (fresh host keys, unchanged provisionedAt) or a hand `ssh-keygen -R`
+    // invalidates the pinned line without changing `key` — trusting the latch alone
+    // is what stranded builders behind a green "pinned ✓" with no recovery. Cheap
+    // (file read + string scan), runs every active poll.
+    if (key === lastSetupHostname && !force) {
+      if (sshSetup.verifyKnownHosts(hostname, reported).ok) return;
+      // Believed-pinned but the file no longer matches → drop the latch + show truth.
+      lastSetupHostname = null;
+      controller.setHostKeys({ ok: false, reason: 'stale_pin' });
+    }
+    // A backoff retry is already scheduled for this activation → let the timer drive
+    // it instead of letting every emit re-fire the async, flaky keyscan. This is
+    // what PACES the retries rather than hammering them (the flicker's second cause).
+    if (hostKeysState.retryPendingKey === key && !force) return;
+    if (key !== hostKeysState.key) { hostKeysState.key = key; hostKeysState.attempts = 0; }
+    // Prefer the AUTHORITATIVE keys the box reported to the GDS (task 1187 / idea
+    // 235): no ssh-keyscan, no TOFU window, no KEX-negotiation flakiness (#910/#925).
+    // Fall back to keyscan only when the box hasn't reported yet (pre-report window /
+    // older server). Retries re-read a fresh snapshot, so once the box reports its
+    // keys the authoritative path takes over on the next attempt.
+    if (rawReported && staleReport) {
+      log(`ignoring reported host keys for ${hostname} — they predate this box; scanning instead`);
+    }
+    let out = reported
+      ? sshSetup.refreshKnownHostsFromKeys(hostname, reported, { log })
+      : { ok: false, reason: rawReported ? 'stale_reported_keys' : 'no_reported_keys' };
+    if (!out.ok) {
+      out = await sshSetup.refreshKnownHosts(hostname, { log });
+    }
+    if (out.ok) {
+      lastSetupHostname = key;
+      hostKeysState.attempts = 0;
+      hostKeysState.retryPendingKey = null;
+      controller.setHostKeys({ ok: true });
+      return;
+    }
+    hostKeysState.attempts += 1;
+    controller.setHostKeys({ ok: false, reason: out.reason, attempt: hostKeysState.attempts });
+    if (out.reason !== 'tool_missing' && hostKeysState.attempts <= 10) {
+      // sshd typically trails 'active' by seconds-to-a-minute on a fresh box.
+      hostKeysState.retryPendingKey = key; // gate emit-driven re-fires until the timer
+      const delay = Math.min(10_000 * hostKeysState.attempts, 60_000);
+      log(`host-key pinning retry ${hostKeysState.attempts} in ${delay / 1000}s (${out.reason})`);
+      setTimeout(() => {
+        hostKeysState.retryPendingKey = null; // release the gate; let this attempt run
+        const s = controller.snapshot();
+        if (s.status === 'active') onActiveSetup(s).catch((e) => log(e.message));
+      }, delay).unref?.();
+    } else {
+      hostKeysState.retryPendingKey = null;
+    }
+  } finally {
+    setupInFlight = false;
+  }
+}
+
+// --- update check ------------------------------------------------------------
+
+// Poll the server's version endpoint and, when it advertises a STRICTLY newer
+// release for our platform, latch updateInfo so the panel shows the banner. The
+// compare is a proper semver one (updater.isUpdateAvailable) — NOT the old `!==`,
+// which advertised a *downgrade* whenever the published config trailed the
+// installed app (#924). Offline / unpublished / no installer for this platform →
+// clear the banner and retry next tick. Never throws.
+async function checkForUpdate() {
+  try {
+    const latest = await client.latestRelease();
+    const target = resolveTarget(process.platform, process.arch);
+    if (latest && target && isUpdateAvailable(appVersion(), latest.version)) {
+      updateInfo = {
+        version: latest.version,
+        target,
+        url: `${apiBase(session && session.api_base)}/downloads/devbox/${target}`,
+        banner: updateBannerText(latest.version),
+      };
+    } else {
+      updateInfo = null;
+    }
+    pushState();
+  } catch { /* offline or not yet published — try again next tick */ }
+}
+
+// Tier-1 one-click update (#924): download the installer for this platform to the
+// Downloads dir, then hand it to the OS — macOS mounts the .dmg (drag-to-
+// Applications; unsigned, so a one-time "Open Anyway"), Windows runs the NSIS
+// oneClick installer + quits so it can replace the running app. ANY failure
+// (offline, disk, blocked) falls back to opening the branded URL in the browser —
+// the safe, always-works path (the pre-#924 behaviour) — so a one-click attempt
+// can never leave the builder worse off than a manual download.
+//
+// ⚠ The download + OS hand-off leg is NOT yet hardware-verified (no signing; a GUI
+// installer can't run in CI — mirrors the #928 sandbox-gate verify gap). The
+// browser fallback is what guarantees the feature works in the field today.
+function downloadTo(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const request = net.request(url); // Electron net follows 302s (apex → GitHub asset)
+    request.on('response', (response) => {
+      if (response.statusCode >= 400) { reject(new Error(`download HTTP ${response.statusCode}`)); return; }
+      const out = fs.createWriteStream(destPath);
+      response.on('data', (chunk) => out.write(chunk));
+      response.on('end', () => out.end(() => resolve(destPath)));
+      response.on('error', reject);
+      out.on('error', reject);
+    });
+    request.on('error', reject);
+    request.end();
+  });
+}
+
+async function performUpdate() {
+  if (!updateInfo || !updateInfo.url) return false;
+  try {
+    const dir = app.getPath('downloads') || app.getPath('temp');
+    const ext = process.platform === 'darwin' ? 'dmg' : 'exe';
+    const dest = path.join(dir, `${brand.PRODUCT_SLUG}-${updateInfo.version}-${updateInfo.target}.${ext}`);
+    await downloadTo(updateInfo.url, dest);
+    const openErr = await shell.openPath(dest); // mac: mount dmg; win: run installer
+    if (openErr) throw new Error(openErr);
+    if (process.platform === 'darwin') {
+      notify({ title: `${brand.PRODUCT_NAME} v${updateInfo.version}`, body: 'Drag the app to Applications, then right-click → Open once (unsigned build).' });
+    } else if (process.platform === 'win32') {
+      app.isQuittingForReal = true;
+      setTimeout(() => app.quit(), 1500); // let the NSIS installer take over
+    }
+    return true;
+  } catch (e) {
+    log('in-app update failed; opening the download in the browser instead:', e.message);
+    shell.openExternal(updateInfo.url);
+    return false;
+  }
+}
+
+// --- wiring ------------------------------------------------------------------
+
+app.whenReady().then(() => {
+  if (process.platform === 'darwin') app.dock.hide(); // pure menu-bar app
+
+  controller = createBoxController({
+    client,
+    signedIn: () => Boolean(session && session.token),
+    envName: brand.DESKTOP_ENV_NAME,
+    onChange: (snapshot) => {
+      pushState();
+      if (snapshot.status === 'active') onActiveSetup(snapshot).catch((e) => log(e.message));
+    },
+    onNotify: notify,
+  });
+
+  tray = createTray({
+    onOpen: showWindow,
+    onToggle: () => {
+      const s = controller.snapshot();
+      (s.status === 'active' ? controller.turnOff() : controller.turnOn()).catch(() => {});
+    },
+    onOpenTerminal: () => {
+      controller.markConnectAttempt(); // leg 3: connect action → keep the box alive
+      const url = terminalAuthUrl(controller.snapshot().terminal);
+      if (url) shell.openExternal(url);
+      showWindow(); // the credential lives in the panel
+    },
+    onOpenHall: () => shell.openExternal(brand.BUILDERS_ORIGIN),
+    onQuit: () => { app.isQuittingForReal = true; app.quit(); },
+    getLoginItem: () => app.getLoginItemSettings().openAtLogin,
+    setLoginItem: (v) => app.setLoginItemSettings({ openAtLogin: v }),
+  });
+
+  createWindow();
+  controller.start();
+  checkForUpdate();
+  // #924: re-check every 12h while the app runs, so a builder who leaves the
+  // tray app up for days still sees a release that lands after launch. unref()
+  // so the timer never keeps the process alive on its own.
+  setInterval(checkForUpdate, 12 * 60 * 60 * 1000).unref?.();
+
+  // First launch, not signed in → open the panel so the one button is visible.
+  if (!session) showWindow();
+
+  // If we ARE signed in, make sure the key is registered + settings current
+  // (no-op elevation prompt when the file already matches).
+  if (session) afterSignIn().catch((e) => log('startup setup:', e.message));
+
+  // Dev/verification hook (README): OTB_DEVBOX_AUTOFLOW=1 self-drives the
+  // whole journey — pair sign-in → switch on → active → switch off → quit —
+  // against a STUB GDS, capturing screenshots along the way. Guarded on
+  // OTB_DEVBOX_API_BASE being set so it can never run against production.
+  if (process.env.OTB_DEVBOX_AUTOFLOW === '1' && process.env.OTB_DEVBOX_API_BASE) {
+    autoflow().catch((e) => { log('autoflow FAILED:', e.message); process.exitCode = 1; app.isQuittingForReal = true; app.quit(); });
+  }
+});
+
+async function autoflow() {
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  const waitFor = async (want, timeoutMs) => {
+    const until = Date.now() + timeoutMs;
+    while (Date.now() < until) {
+      if (controller.snapshot().status === want) return;
+      await sleep(1000);
+    }
+    throw new Error(`autoflow: timed out waiting for status=${want} (at ${controller.snapshot().status})`);
+  };
+  log('autoflow: begin');
+  showWindow();
+  await sleep(2000);
+  if (controller.snapshot().status === 'signed_out') {
+    await signIn();
+    if (!session) throw new Error('autoflow: sign-in did not complete');
+    log('autoflow: signed in as', session.builder.github_login);
+  }
+  await waitFor('none', 20_000);
+  log('autoflow: box off — flipping on');
+  await controller.turnOn();
+  await waitFor('active', 180_000);
+  log('autoflow: ACTIVE — terminal:', JSON.stringify(controller.snapshot().terminal));
+  await sleep(8_000);
+  log('autoflow: flipping off');
+  await controller.turnOff();
+  await waitFor('none', 120_000);
+  log('autoflow: box closed — SUCCESS');
+  await sleep(3_000);
+  app.isQuittingForReal = true;
+  app.quit();
+}
+
+app.on('window-all-closed', () => { /* tray app — never quit on window close */ });
+app.on('before-quit', () => { app.isQuittingForReal = true; });
+
+// --- IPC (renderer is sandboxed; every action is a named verb, no raw URLs) --
+
+ipcMain.handle('state:get', () => ({ snapshot: controller.snapshot(), meta: meta() }));
+ipcMain.handle('auth:signIn', () => { signIn(); return true; });
+ipcMain.handle('auth:cancelPairing', () => { if (pairing) pairing.cancel(); return true; });
+ipcMain.handle('auth:signOut', () => signOut());
+ipcMain.handle('box:on', async () => {
+  try { return { ok: true, out: await controller.turnOn() }; }
+  catch (e) { return { ok: false, error: e.message }; }
+});
+ipcMain.handle('box:off', async () => {
+  try { return { ok: true, out: await controller.turnOff() }; }
+  catch (e) { return { ok: false, error: e.message }; }
+});
+// BV1.R100: "What are you working on?" — list the builder's claimable tasks.
+ipcMain.handle('tasks:claimable', async () => {
+  try { return { ok: true, tasks: shapeClaimableTasks(await client.claimableTasks()) }; }
+  catch (e) { return { ok: false, error: e.message }; }
+});
+// Pick + confirm: claim the task over the API, then read the credential-free box
+// scope so we can name exactly what the box will hold. The scope read is
+// best-effort — the claim already succeeded, so a scope hiccup still confirms.
+ipcMain.handle('tasks:pick', async (_e, taskId) => {
+  try {
+    await client.claimTask(taskId);
+    controller.markConnectAttempt(); // picking a task is a connect-intent (leg-3 keep-alive)
+    let scope = null;
+    try { scope = await client.boxScope(); } catch (e) { log('tasks:pick scope read failed (non-fatal):', e.message); }
+    return { ok: true, message: boxScopeMessage({ task: { id: String(taskId) }, scope }), scope };
+  } catch (e) {
+    return { ok: false, error: claimErrorMessage(e) };
+  }
+});
+ipcMain.handle('open:terminal', () => {
+  controller.markConnectAttempt(); // leg 3: opening the terminal is a connect action
+  // Embed the basic-auth userinfo so the terminal opens already signed in.
+  const url = terminalAuthUrl(controller.snapshot().terminal);
+  if (url) shell.openExternal(url);
+  return Boolean(url);
+});
+ipcMain.handle('open:hall', () => shell.openExternal(brand.BUILDERS_ORIGIN));
+ipcMain.handle('open:pairPage', () => {
+  if (pairingState && pairingState.verifyUrl) shell.openExternal(pairingState.verifyUrl);
+  return true;
+});
+ipcMain.handle('open:update', () => performUpdate());
+ipcMain.handle('copy', (_e, what) => {
+  const s = controller.snapshot();
+  if (what === 'ssh' && s.box && s.box.hostname) {
+    clipboard.writeText(`ssh -i ~/.ssh/otb_builder root@${s.box.hostname}`);
+    return true;
+  }
+  if (what === 'terminal-credential' && s.terminal && s.terminal.credential) {
+    clipboard.writeText(s.terminal.credential);
+    return true;
+  }
+  if (what === 'terminal-user' && s.terminal && s.terminal.credential) {
+    clipboard.writeText(TERMINAL_USER);
+    return true;
+  }
+  return false;
+});
+ipcMain.handle('settings:install', () => installSettings());
+ipcMain.handle('hostkeys:retry', async () => {
+  hostKeysState.attempts = 0;
+  const s = controller.snapshot();
+  if (s.status === 'active') await onActiveSetup(s, { force: true }).catch((e) => log(e.message));
+  return controller.snapshot().hostKeys;
+});
+ipcMain.handle('key:retry', async () => {
+  keyRegState.activation = null; // an explicit ask overrides the once-per-activation gate
+  await runKeySetup();
+  return controller.snapshot().keyRegistered;
+});
+ipcMain.handle('panel:hide', () => { if (win) win.hide(); return true; });

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

@@ -0,0 +1,57 @@
+// devbox-app/src/pairing.js — browser-clicks-only sign-in (#904, ADR 0045).
+//
+// start() asks the GDS for a pairing, opens the approve page in the default
+// browser, and polls until the builder clicks Approve. The minted token comes
+// back over the app's own secret poll channel — it never transits the browser.
+// Counterpart server logic: src/bongos/app-pair.js + routes/auth.js.
+
+const os = require('node:os');
+const brand = require('./brand');
+
+function platformKey() {
+  if (process.platform === 'darwin') return 'mac';
+  if (process.platform === 'win32') return 'windows';
+  return 'linux';
+}
+
+function deviceName() {
+  const host = os.hostname().replace(/\.(local|lan|home)$/i, '');
+  return `${brand.PRODUCT_NAME} on ${host}`.slice(0, 80);
+}
+
+// createPairing({ client, openExternal, sleep }) — deps injected for tests.
+// run(onUpdate) resolves { token, builder, expires_at } or throws
+// Error('expired'|'cancelled').
+function createPairing({ client, openExternal, sleep }) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let cancelled = false;
+
+  return {
+    cancel() { cancelled = true; },
+    async run(onUpdate = () => {}) {
+      cancelled = false;
+      const start = await client.pairStart(deviceName(), platformKey());
+      onUpdate({ phase: 'waiting', pairCode: start.pair_code, verifyUrl: start.verify_url });
+      await openExternal(start.verify_url);
+      const intervalMs = Math.max(2, start.interval || 5) * 1000;
+      const deadline = Date.now() + (start.expires_in || 600) * 1000;
+      while (!cancelled && Date.now() < deadline) {
+        await wait(intervalMs);
+        if (cancelled) break;
+        let out;
+        try {
+          out = await client.pairPoll(start.poll_token);
+        } catch {
+          continue; // transient network blip — the deadline bounds us
+        }
+        if (out.status === 'approved') {
+          return { token: out.token, builder: out.builder, expires_at: out.expires_at };
+        }
+        if (out.status === 'expired') throw new Error('expired');
+      }
+      throw new Error(cancelled ? 'cancelled' : 'expired');
+    },
+  };
+}
+
+module.exports = { createPairing, platformKey, deviceName };