@oar-sh/oar 0.9.3 → 0.9.5

package/server/server-runtime.mjs

@@ -40,6 +40,13 @@ import { registerRelayBoardRoutes } from './routes/relay-board-routes.mjs';
 import { registerCacheRoutes } from './routes/cache-routes.mjs';
 import { registerGitRoutes } from './routes/git-routes.mjs';
 import { registerPreviewRoutes } from './routes/preview-routes.mjs';
+import { registerRemoteRelayRoutes } from './routes/remote-relay-routes.mjs';
+import { createRemoteRelayRepository } from './repositories/remote-relay-repository.mjs';
+import { createRemoteRelayClient } from './services/remote-relay-client.mjs';
+import { createRemoteRelayRegistry } from './services/remote-relay-registry-service.mjs';
+import { createRemoteRelayPairing } from './services/remote-relay-pairing.mjs';
+import { createRemoteRelayCallerContext } from './services/remote-relay-caller-context.mjs';
+import { createRemoteRelayDispatcher } from './services/remote-relay-dispatcher.mjs';
 import { createDeleteArchiveService } from './services/delete-archive-service.mjs';
 import { createStatusEventService } from './services/status-event-service.mjs';
 import { createClaudeAuthService } from './services/claude-auth-service.mjs';
@@ -48,6 +55,9 @@ import { createGrokAuthService } from './services/grok-auth-service.mjs';
 import { sweepUnreferencedUploads, UNREFERENCED_UPLOADS_QUERY } from './services/upload-sweep.mjs';
 import webpush from 'web-push';
 import { createPushDispatchService, ensurePushVapidKeys } from './services/push-dispatch-service.mjs';
+import { createHostSuspendService } from './services/host-suspend-service.mjs';
+import { createGitHubCiActivityService } from './services/github-ci-activity-service.mjs';
+import { runHostSuspendToRam } from './services/host-suspend-command.mjs';
 import { createActiveDeviceTracker } from './services/push-active-device-service.mjs';
 import { registerPushRoutes } from './routes/push-routes.mjs';
 import { createImageOperationService } from './services/image-operation-service.mjs';
@@ -3136,6 +3146,36 @@ function getRelayShutdownState() {
   };
 }
 
+// Every client shows a banner while a shutdown/restart is queued, so the
+// state goes out on each transition (request, cancel, drain) and on connect.
+function relayShutdownStatePayload() {
+  return { ...getRelayShutdownState(), queue: queueCounts() };
+}
+function emitRelayShutdownState() {
+  try { io.emit('relay_shutdown_state', relayShutdownStatePayload()); } catch {}
+}
+
+function cancelRelayShutdown({ requestedBy = 'localhost-api' } = {}) {
+  if (runtimeShutdownStarted) {
+    return { cancelled: false, status: 'shutting_down', ...relayShutdownStatePayload() };
+  }
+  if (!pendingRelayShutdownRequest) {
+    return { cancelled: false, ...relayShutdownStatePayload() };
+  }
+  const dropped = pendingRelayShutdownRequest;
+  pendingRelayShutdownRequest = null;
+  if (runtimeTimers.shutdownDrain) {
+    try { clearInterval(runtimeTimers.shutdownDrain); } catch {}
+    runtimeTimers.shutdownDrain = null;
+  }
+  console.log(
+    `${runtimeLogPrefix()}Relay ${dropped.action || 'shutdown'} request cancelled by `
+    + `${String(requestedBy || 'localhost-api').trim().slice(0, 80) || 'localhost-api'}`,
+  );
+  emitRelayShutdownState();
+  return { cancelled: true, dropped, ...relayShutdownStatePayload() };
+}
+
 function requestRelayShutdown({ reason = 'manual-request', requestedBy = 'localhost-api', restart = false } = {}) {
   const safeReason = String(reason || 'manual-request').trim().slice(0, 140) || 'manual-request';
   const safeRequestedBy = String(requestedBy || 'localhost-api').trim().slice(0, 80) || 'localhost-api';
@@ -3188,12 +3228,14 @@ function requestRelayShutdown({ reason = 'manual-request', requestedBy = 'localh
     );
     sessionWorkerWebSocketService.emitDraining(`api-${action}:${requestInfo?.reason || 'manual-request'}`);
     void shutdownRuntime(`api-${action}:${requestInfo?.reason || 'manual-request'}`, { exitCode });
+    emitRelayShutdownState();
   };
 
   if (!runtimeTimers.shutdownDrain) {
     runtimeTimers.shutdownDrain = setInterval(tryShutdownWhenIdle, 1000);
   }
   tryShutdownWhenIdle();
+  if (pendingRelayShutdownRequest) emitRelayShutdownState();
   const counts = queueCounts();
   return {
     accepted: true,
@@ -4883,6 +4925,98 @@ const backgroundTaskStore = {
   },
 };
 
+// ─── Deferred host suspend ───────────────────────────────────────────────────
+// "💤 Suspend host" waits until nothing runs any more: no queued/processing
+// turn, no live background task of a live worker, no open CI run in a
+// workspace that was busy since the request. The relay-side signals are read
+// synchronously each tick; CI is refreshed in the background and read from
+// the last snapshot (a never-checked workspace counts as busy).
+const hostActivityWorkerStatuses = new Set(['starting', 'ready', 'processing']);
+function hostActivityPidAlive(pidValue) {
+  const pid = Number(pidValue);
+  if (!Number.isInteger(pid) || pid <= 0) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+function hostActivityWorkerAlive(key) {
+  const worker = sessionWorkerRegistry?.getWorker?.(key)
+    || sessionWorkerRegistry?.getWorkerByConversationId?.(key)
+    || null;
+  if (!worker) return false;
+  return hostActivityWorkerStatuses.has(String(worker.status || '').trim().toLowerCase())
+    && hostActivityPidAlive(worker.pid);
+}
+const hostSuspendWatchedConversationIds = new Set();
+const githubCiActivityService = createGitHubCiActivityService({ logger: console });
+function hostActivityTitle(conversationId, fallbackTitle = null) {
+  const title = String(fallbackTitle || stmts.getConv?.get?.(conversationId)?.title || '').trim();
+  return title || String(conversationId || '').slice(0, 8);
+}
+function collectHostActivity({ request = null } = {}) {
+  const blockers = [];
+  const turnsByConversation = stmts.listActiveQueueCountsByConversation?.all?.() || [];
+  for (const row of turnsByConversation) {
+    const conversationId = String(row.conversation_id || '');
+    if (!conversationId) continue;
+    hostSuspendWatchedConversationIds.add(conversationId);
+    const count = Number(row.cnt || 0);
+    blockers.push({
+      kind: 'turn',
+      conversationId,
+      title: hostActivityTitle(conversationId, row.title),
+      count,
+      detail: count > 1 ? `${count} turns running` : 'turn running',
+    });
+  }
+  for (const [key, entry] of backgroundTaskStore.sets) {
+    const tasks = Array.isArray(entry?.tasks) ? entry.tasks : [];
+    if (!tasks.length || !hostActivityWorkerAlive(key)) continue;
+    const worker = sessionWorkerRegistry?.getWorker?.(key) || sessionWorkerRegistry?.getWorkerByConversationId?.(key) || null;
+    const conversationId = String(worker?.conversationId || key);
+    hostSuspendWatchedConversationIds.add(conversationId);
+    const what = tasks.slice(0, 3).map((task) => String(task?.description || task?.taskType || 'task').slice(0, 80)).join('; ');
+    blockers.push({
+      kind: 'background',
+      conversationId,
+      title: hostActivityTitle(conversationId),
+      count: tasks.length,
+      detail: `${tasks.length} background agent${tasks.length === 1 ? '' : 's'}: ${what}`,
+    });
+  }
+  const runningSubagents = Number(stmts.countRunningSubagentRuns?.get?.()?.cnt || 0);
+  // CI is only worth a network round-trip for workspaces that were busy since
+  // the request (or, for the modal's peek, that are busy right now).
+  const roots = [...hostSuspendWatchedConversationIds]
+    .map((conversationId) => {
+      try { return resolveConversationWorkspaceState({ conversationId })?.currentWorkspaceRootPath || ''; } catch { return ''; }
+    })
+    .filter(Boolean);
+  if (roots.length) void githubCiActivityService.describeRuns(roots).catch(() => {});
+  const ci = roots.length ? githubCiActivityService.snapshot(roots) : { repos: [], unknown: [], blockers: [] };
+  blockers.push(...ci.blockers);
+  if (!request && !hostSuspendService.getState().pending) hostSuspendWatchedConversationIds.clear();
+  return { blockers, runningSubagents, ci };
+}
+const hostSuspendService = createHostSuspendService({
+  collectActivity: collectHostActivity,
+  runSuspend: () => runHostSuspendToRam({ logger: console }),
+  logger: console,
+  onStateChange: (state) => {
+    if (state.status === 'idle') hostSuspendWatchedConversationIds.clear();
+    try { io.emit('host_suspend_state', state); } catch {}
+  },
+  onSuspended: () => {
+    void pushDispatchService.notifyHostSuspend({ body: 'All agents finished; the host is suspending now.' });
+  },
+  onDropped: (state, reason) => {
+    void pushDispatchService.notifyHostSuspend({ body: `Queued host suspend dropped: relay ${reason || 'restarting'}.` });
+  },
+});
+
 // The live turn among a conversation's processing rows. Mid-turn steering can
 // leave several processing at once — the running turn, steered messages the
 // CLI folded into it (no output of their own), a handed-off row still settling
@@ -5391,6 +5525,13 @@ const app        = express();
 // via config.trustProxy (e.g. a hop count or subnet).
 app.set('trust proxy', config.trustProxy ?? 'loopback');
 const httpServer = http.createServer(app);
+// Node closes an idle keep-alive connection after 5 s. A client that pools
+// connections (a fronting proxy such as Caddy or cloudflared, an API client)
+// can pick such a socket in the very moment the relay closes it; its request
+// is then reset before the relay reads a byte, and a POST is not replayed.
+// Holding idle connections longer than those pools do closes that window.
+httpServer.keepAliveTimeout = 65_000;
+httpServer.headersTimeout = 66_000;
 httpServer.prependListener('request', (req, _res) => {
   rewriteSocketIoRequestPath(req, remotePath);
 });
@@ -6040,6 +6181,7 @@ const runtimeState = {
   set relayPaused(value) { relayPaused = value; },
   get ttyConsoleActive() { return Boolean(ttyConsoleRuntime?.tty); },
   get relayShutdown() { return getRelayShutdownState(); },
+  get hostSuspend() { return hostSuspendService.getState(); },
   get activeBridgeOwner() { return relayBridgeOwnerService.getOwner(); },
   get workerWebSocketStatus() { return sessionWorkerWebSocketService.status(); },
   get tmuxInspectorStatus() { return tmuxInspectorSocketService.status(); },
@@ -6056,6 +6198,82 @@ const windowsBootAutostartService = createWindowsBootAutostartService({
 });
 
 const gitChangesService = createGitChangesService();
+
+// ─── Remote Relays ────────────────────────────────────────────────────────────
+// Other OAR relays this one is paired with, so its agents can work there. Built
+// before the shared route deps: the message, session and question routes read
+// the registry for mentions, unlocks and the inbound switch.
+// Null when migration 0005 failed this boot (db-schema retries it next boot):
+// remotes still list and pair, nothing unlocks until then.
+const remoteRelayRepository = (() => {
+  try {
+    return createRemoteRelayRepository(db);
+  } catch (error) {
+    console.warn(`[remote-relays] unlock storage unavailable: ${error?.message || error}`);
+    return null;
+  }
+})();
+const remoteRelayClient = createRemoteRelayClient({
+  // A closure: the registry owning the instance id is declared just below.
+  getOwnRelayId: () => remoteRelayRegistry.instanceId(),
+  getOwnToken: () => config.authToken,
+});
+const remoteRelayRegistry = createRemoteRelayRegistry({
+  readSetting: readAppSettingValue,
+  writeSetting: (key, value) => stmts.upsertAppSetting.run(key, value, new Date().toISOString()),
+  client: remoteRelayClient,
+  repository: remoteRelayRepository,
+  getOwnToken: () => config.authToken,
+  getSelfName: getPwaAppName,
+  hostname: os.hostname(),
+  platform: process.platform,
+  version: RUNNING_VERSION,
+  emit: (event, payload) => io.emit(event, payload),
+  logger: console,
+});
+const remoteRelayPairing = createRemoteRelayPairing({
+  registry: remoteRelayRegistry,
+  client: remoteRelayClient,
+  getOwnToken: () => config.authToken,
+});
+// What the inbound routes need: no tokens, only ids, names and state.
+const remoteRelayInbound = {
+  listRelays: () => remoteRelayRegistry.list().map(({ id, name, url, lastStatus, version }) => ({ id, name, url, lastStatus, version })),
+  selfNames: () => [remoteRelayRegistry.selfName()],
+  inboundEnabled: () => remoteRelayRegistry.getSelfSettings().inboundEnabled,
+  recordUnlock: (conversationId, relayId, messageId) => remoteRelayRepository?.recordUnlock(conversationId, relayId, messageId) ?? false,
+  describeRelay: (id) => {
+    const relay = remoteRelayRegistry.get(id);
+    return relay ? { id: relay.id, name: relay.name, online: relay.lastStatus === 'online', version: relay.version } : null;
+  },
+  repository: remoteRelayRepository,
+};
+// The remote_relay tool: who is calling (live turn, provider, model, mode,
+// hops) and the Allow / Deny card write actions need in ask/plan mode.
+const remoteRelayCallerContext = createRemoteRelayCallerContext({
+  db,
+  repository: remoteRelayRepository,
+  questions: stmts,
+  resolveLiveTurnQueueRow,
+  formatQuestionRow,
+  normalizeRelayMode,
+  defaultRelayMode: DEFAULT_RELAY_MODE,
+  emit: (event, payload) => io.emit(event, payload),
+  notifyQuestion: (question) => pushDispatchService.notifyQuestion?.(question),
+  uuid: uuidv4,
+  logger: console,
+});
+const remoteRelayDispatcher = createRemoteRelayDispatcher({
+  registry: remoteRelayRegistry,
+  client: remoteRelayClient,
+  repository: remoteRelayRepository,
+  getCallerContext: (conversationId) => remoteRelayCallerContext.getCallerContext(conversationId),
+  requestApproval: (request) => remoteRelayCallerContext.requestApproval(request),
+  emitStatusEvent: ({ type, ...details }) => statusEventService.recordEvent(type, details),
+  resolveConversationId: (id) => resolveConversationRecord({ conversationId: id, sdkSessionId: id })?.id || id,
+  logger: console,
+});
+
 const sharedRouteDeps = {
   auth,
   gitChangesService,
@@ -6239,6 +6457,10 @@ const sharedRouteDeps = {
   getPwaAppName,
   setPwaAppName,
   requestRelayShutdown,
+  cancelRelayShutdown,
+  relayShutdownStatePayload,
+  hostSuspendService,
+  collectHostActivity,
   markSharedViewerPresence,
   getSharedWatcherCount,
   statusEventService,
@@ -6253,6 +6475,7 @@ const sharedRouteDeps = {
   windowsAutostartService,
   windowsBootAutostartService,
   pushDispatchService,
+  remoteRelayInbound,
 };
 registerMessagesRoutes(app, sharedRouteDeps);
 registerSessionsRoutes(app, sharedRouteDeps);
@@ -6265,6 +6488,12 @@ registerPushRoutes(app, {
   pushDispatchService,
   getPushVapidPublicKey: () => pushVapidKeys.publicKey,
 });
+registerRemoteRelayRoutes(app, {
+  auth,
+  registry: remoteRelayRegistry,
+  pairing: remoteRelayPairing,
+  dispatcher: remoteRelayDispatcher,
+});
 function markCliOffline(reason = 'offline', { clearOwner = true } = {}) {
   cliLastSeen = null;
   const wasOnline = cliOnline;
@@ -6619,6 +6848,9 @@ io.on('connection', (socket) => {
   });
   // Send current CLI status immediately on connect
   socket.emit('cli_status', { online: cliOnline });
+  // Pending host suspend / relay restart banners must survive a reconnect.
+  try { socket.emit('host_suspend_state', hostSuspendService.getState()); } catch {}
+  try { socket.emit('relay_shutdown_state', relayShutdownStatePayload()); } catch {}
   // Visibility heartbeats for push suppression; also clears a stale
   // deviceVisible flag restored by connectionStateRecovery.
   activeDeviceTracker.registerSocket(socket);
@@ -6753,6 +6985,9 @@ function shutdownRuntime(reason = 'unknown', { exitCode = 0 } = {}) {
   runtimeShutdownStarted = true;
   console.log(`${runtimeLogPrefix()}Runtime shutdown started (${reason}, exitCode=${runtimeShutdownExitCode})`);
   clearRuntimeTimers();
+  // A queued host suspend is in-memory only; drop it loudly rather than let
+  // the next runtime forget about it in silence.
+  try { hostSuspendService.dispose({ reason }); } catch {}
   try { updateCheckService?.stop(); } catch {}
   // Started here (flips the importer's closing flag synchronously) but awaited
   // below before the transports close: fire-and-forget disposal let a
@@ -6781,6 +7016,7 @@ function shutdownRuntime(reason = 'unknown', { exitCode = 0 } = {}) {
   sshTunnelManager.stop();
   cloudflaredTunnelManager.stop();
   previewHealthProbe.stop();
+  try { remoteRelayRegistry.stopHealthLoop(); } catch {}
   // Previews are in-memory by design: a restart is the only implicit cleanup,
   // so every public link dies with the process.
   previewRegistry.clear();
@@ -6913,6 +7149,8 @@ httpServer.listen(config.port, listenHost, () => {
   // Start SSH tunnel after server is listening
   sshTunnelManager.start();
   cloudflaredTunnelManager.start();
+  // Status, version and renames of paired relays; a first pass right away.
+  remoteRelayRegistry.startHealthLoop();
   // A preview-lane failure must never take the relay with it: the listener is
   // optional infrastructure, so a bind error is logged and the relay carries on
   // without previews.

package/server/services/github-ci-activity-service.mjs

@@ -0,0 +1,199 @@
+'use strict';
+
+import { execFile } from 'node:child_process';
+
+/**
+ * Open GitHub Actions runs for a set of workspace roots, via the `gh` CLI the
+ * host already has (same credentials the agents use). Nothing in the relay
+ * models CI, so this is a best-effort outside view: a repo whose runs cannot
+ * be read counts as "unknown" and blocks for a grace period, after which it is
+ * ignored rather than keeping the host awake forever over a GitHub outage.
+ */
+
+const DEFAULT_CACHE_MS = 20 * 1000;
+const DEFAULT_UNKNOWN_GRACE_MS = 15 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 20 * 1000;
+const RUN_LIST_LIMIT = 30;
+
+const OPEN_RUN_STATUSES = new Set(['queued', 'in_progress', 'waiting', 'requested', 'pending']);
+
+/** `git@github.com:o/r.git`, `https://github.com/o/r`, `ssh://git@github.com/o/r.git` → `o/r`. */
+export function parseGitHubRepoSlug(remoteUrl) {
+  const text = String(remoteUrl || '').trim();
+  if (!text) return null;
+  const match = text.match(/github\.com[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i);
+  if (!match) return null;
+  return `${match[1]}/${match[2]}`;
+}
+
+export function isOpenCiRunStatus(status) {
+  const value = String(status || '').trim().toLowerCase();
+  if (!value) return false;
+  return OPEN_RUN_STATUSES.has(value) || value !== 'completed';
+}
+
+function execText(execFileImpl, file, args, { cwd = undefined, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    try {
+      execFileImpl(file, args, { cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (settled) return;
+        settled = true;
+        if (error) {
+          const detail = String(stderr || error.message || '').trim().split('\n')[0] || 'command failed';
+          reject(new Error(detail.slice(0, 200)));
+          return;
+        }
+        resolve(String(stdout || ''));
+      });
+    } catch (error) {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    }
+  });
+}
+
+export function createGitHubCiActivityService({
+  execFileImpl = execFile,
+  now = () => Date.now(),
+  cacheMs = DEFAULT_CACHE_MS,
+  unknownGraceMs = DEFAULT_UNKNOWN_GRACE_MS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  logger = console,
+} = {}) {
+  // root → { slug: string|null, at }
+  const slugByRoot = new Map();
+  // slug → { runs, error, at, unknownSince, inFlight }
+  const runsBySlug = new Map();
+
+  async function resolveSlug(root) {
+    const key = String(root || '').trim();
+    if (!key) return null;
+    const cached = slugByRoot.get(key);
+    if (cached && cached.at !== null && now() - cached.at < 10 * cacheMs) return cached.slug;
+    let slug = null;
+    try {
+      const url = await execText(execFileImpl, 'git', ['-C', key, 'remote', 'get-url', 'origin'], { timeoutMs });
+      slug = parseGitHubRepoSlug(url);
+    } catch {
+      slug = null;
+    }
+    slugByRoot.set(key, { slug, at: now() });
+    return slug;
+  }
+
+  async function fetchRuns(slug) {
+    const entry = runsBySlug.get(slug) || { runs: [], error: null, at: null, unknownSince: null, inFlight: null };
+    runsBySlug.set(slug, entry);
+    if (entry.inFlight) return entry.inFlight;
+    if (entry.at !== null && now() - entry.at < cacheMs) return entry;
+    entry.inFlight = (async () => {
+      try {
+        const out = await execText(execFileImpl, 'gh', [
+          'run', 'list', '-R', slug, '--limit', String(RUN_LIST_LIMIT),
+          '--json', 'status,name,headBranch,databaseId,event',
+        ], { timeoutMs });
+        const parsed = JSON.parse(out || '[]');
+        entry.runs = (Array.isArray(parsed) ? parsed : [])
+          .filter((run) => run && isOpenCiRunStatus(run.status))
+          .map((run) => ({
+            id: run.databaseId ?? null,
+            name: String(run.name || 'workflow').slice(0, 120),
+            headBranch: String(run.headBranch || '').slice(0, 160),
+            status: String(run.status || '').slice(0, 40),
+            event: String(run.event || '').slice(0, 40),
+          }));
+        entry.error = null;
+        entry.unknownSince = null;
+      } catch (error) {
+        entry.error = String(error?.message || error || 'gh failed').slice(0, 200);
+        if (entry.unknownSince === null) entry.unknownSince = now();
+        try { logger.warn?.(`[host-suspend] CI state for ${slug} unknown: ${entry.error}`); } catch {}
+      } finally {
+        entry.at = now();
+        entry.inFlight = null;
+      }
+      return entry;
+    })();
+    return entry.inFlight;
+  }
+
+  /**
+   * @param {string[]} workspaceRoots
+   * @returns {Promise<{ repos: Array<{ repo, runs }>, unknown: Array<{ repo, error, since, ignored }>, blockers: Array<object> }>}
+   */
+  async function describeRuns(workspaceRoots = []) {
+    const roots = [...new Set((Array.isArray(workspaceRoots) ? workspaceRoots : []).map((r) => String(r || '').trim()).filter(Boolean))];
+    const slugs = new Set();
+    for (const root of roots) {
+      const slug = await resolveSlug(root);
+      if (slug) slugs.add(slug);
+    }
+    const repos = [];
+    const unknown = [];
+    const blockers = [];
+    for (const slug of slugs) {
+      const entry = await fetchRuns(slug);
+      if (entry.error) {
+        const since = entry.unknownSince === null ? now() : entry.unknownSince;
+        const ignored = now() - since >= unknownGraceMs;
+        unknown.push({ repo: slug, error: entry.error, since: new Date(since).toISOString(), ignored });
+        if (!ignored) {
+          blockers.push({ kind: 'ci-unknown', detail: `CI state of ${slug} unknown (${entry.error})`, title: slug });
+        }
+        continue;
+      }
+      if (entry.runs.length) {
+        repos.push({ repo: slug, runs: entry.runs.map((r) => ({ ...r })) });
+        const what = entry.runs.slice(0, 4).map((r) => `${r.name} on ${r.headBranch || '?'} (${r.status})`).join(', ');
+        blockers.push({ kind: 'ci', title: slug, count: entry.runs.length, detail: what });
+      }
+    }
+    return { repos, unknown, blockers };
+  }
+
+  /**
+   * Last known picture without touching git/gh — for synchronous collectors
+   * that kick describeRuns() off in the background. A root or repo that has
+   * never been resolved yet reports a `ci-checking` blocker so the host does
+   * not sleep during the very first lookup.
+   */
+  function snapshot(workspaceRoots = []) {
+    const blockers = [];
+    const repos = [];
+    const unknown = [];
+    const slugs = new Set();
+    let checking = 0;
+    // Several busy conversations usually share one workspace; count it once.
+    const roots = new Set((Array.isArray(workspaceRoots) ? workspaceRoots : []).map((root) => String(root || '').trim()));
+    for (const key of roots) {
+      if (!key) continue;
+      const cached = slugByRoot.get(key);
+      if (!cached) { checking += 1; continue; }
+      if (cached.slug) slugs.add(cached.slug);
+    }
+    for (const slug of slugs) {
+      const entry = runsBySlug.get(slug);
+      if (!entry || entry.at === null) { checking += 1; continue; }
+      if (entry.error) {
+        const since = entry.unknownSince === null ? now() : entry.unknownSince;
+        const ignored = now() - since >= unknownGraceMs;
+        unknown.push({ repo: slug, error: entry.error, since: new Date(since).toISOString(), ignored });
+        if (!ignored) blockers.push({ kind: 'ci-unknown', title: slug, detail: `CI state of ${slug} unknown (${entry.error})` });
+        continue;
+      }
+      if (entry.runs.length) {
+        repos.push({ repo: slug, runs: entry.runs.map((r) => ({ ...r })) });
+        const what = entry.runs.slice(0, 4).map((r) => `${r.name} on ${r.headBranch || '?'} (${r.status})`).join(', ');
+        blockers.push({ kind: 'ci', title: slug, count: entry.runs.length, detail: what });
+      }
+    }
+    if (checking > 0) {
+      blockers.push({ kind: 'ci-checking', count: checking, detail: `Checking CI state of ${checking} workspace${checking === 1 ? '' : 's'}` });
+    }
+    return { repos, unknown, blockers };
+  }
+
+  return { describeRuns, snapshot, parseGitHubRepoSlug };
+}

package/server/services/host-suspend-command.mjs

@@ -0,0 +1,38 @@
+'use strict';
+
+import { spawn } from 'node:child_process';
+
+/**
+ * The actual suspend-to-RAM call. Windows only: `SetSuspendState 0,0,0` puts
+ * the box into S3 (hibernation is not enabled on the host, so this never
+ * hibernates). Detached so the relay does not wait on it.
+ *
+ * `OAR_HOST_SUSPEND_DRY_RUN=1` logs instead of sleeping the machine, which is
+ * how the deferred-suspend flow gets exercised on a dev box.
+ */
+export function runHostSuspendToRam({
+  platform = process.platform,
+  spawnImpl = spawn,
+  dryRun = /^(1|true|yes|on)$/i.test(String(process.env.OAR_HOST_SUSPEND_DRY_RUN || '')),
+  logger = console,
+} = {}) {
+  if (platform !== 'win32') {
+    return { ok: false, statusCode: 501, error: 'Host suspend is only supported on Windows' };
+  }
+  const command = 'rundll32.exe powrprof.dll,SetSuspendState 0,0,0';
+  if (dryRun) {
+    try { logger.log?.(`[host-suspend] DRY RUN — would run: ${command}`); } catch {}
+    return { ok: true, command, dryRun: true };
+  }
+  try {
+    const child = spawnImpl('rundll32.exe', ['powrprof.dll,SetSuspendState', '0,0,0'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref?.();
+    return { ok: true, command };
+  } catch (error) {
+    return { ok: false, statusCode: 500, error: error?.message || 'Failed to launch host suspend command' };
+  }
+}