elanous 0.2.6 → 0.2.8

package/src/nexus/api/graph-approvals.ts

@@ -3,7 +3,9 @@ import { join } from 'node:path';
 import { debug } from '../../debug/log.js';
 import { decideGraphApproval, lastJsonObject, type GraphRunState } from '../../graph-runner/runner.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { getElanousConfigDir } from '../../elanous-config-dir.js';
 import { jsonResponse } from './json-response.js';
+import { applyFeedEdit, feedFolderFor, isFeedPreviewMessage, mediaContentType, readFeedDraft, resolveFeedMedia, writeFeedDraft, type FeedDraft } from './graph-approvals-feed.js';
 
 export const GRAPH_APPROVALS_PATH = '/v1/graph-approvals';
 const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -16,6 +18,8 @@ interface GraphApprovalItem {
   since: string;
   path: string[];
   recent: Array<{ nodeId: string; ok: boolean; outcome?: string; summary?: string }>;
+  /** EV10d — present only for a `{"kind":"feed-preview"}` approval whose run folder holds a valid draft. */
+  feed?: Omit<FeedDraft, 'folder'>;
 }
 
 /** One decision this daemon applied through `POST /v1/graph-approvals/:graphId/:runId`. */
@@ -72,6 +76,8 @@ interface GraphApprovalsDeps {
    * `tailscale serve` every tailnet peer (Pod included) arrives from loopback. */
   authReason?: (request: Request) => string | undefined;
   root?: string;
+  /** Config dir whose `field/<slug>` folders may hold feed drafts (EV10d). */
+  configDir?: string;
 }
 
 const DECISION_AUTH_REASONS = new Set(['bearer-match', 'temp-token', 'noauth']);
@@ -96,7 +102,16 @@ function undecided(state: GraphRunState, root: string): boolean {
     && Array.isArray(state.path) && !existsSync(join(root, 'graph-runs', state.graphId, `${state.runId}.json.${state.path.length}.decision.json`));
 }
 
-function list(root: string): GraphApprovalItem[] {
+function feedFor(state: GraphRunState, configDir: string): Omit<FeedDraft, 'folder'> | undefined {
+  if (!isFeedPreviewMessage(state.pending?.message ?? '')) return undefined;
+  const folder = feedFolderFor(state, configDir);
+  const draft = folder ? readFeedDraft(folder) : null;
+  if (!draft) return undefined;
+  const { folder: _folder, ...rest } = draft;
+  return rest;
+}
+
+function list(root: string, configDir: string): GraphApprovalItem[] {
   const dir = join(root, 'graph-runs');
   let graphs: Dirent[];
   try { graphs = readdirSync(dir, { withFileTypes: true }); }
@@ -113,6 +128,7 @@ function list(root: string): GraphApprovalItem[] {
       const state = readRun(root, graph.name, runId);
       if (!state || !undecided(state, root) || !Array.isArray(state.nodes)) continue;
       const pending = state.pending!;
+      const feed = feedFor(state, configDir);
       items.push({
         graphId: state.graphId, runId: state.runId, nodeId: pending.nodeId, message: pending.message,
         since: pending.since, path: state.path,
@@ -124,6 +140,7 @@ function list(root: string): GraphApprovalItem[] {
             ...(typeof output?.summary === 'string' ? { summary: output.summary } : {}),
           };
         }),
+        ...(feed ? { feed } : {}),
       });
     }
   }
@@ -131,14 +148,17 @@ function list(root: string): GraphApprovalItem[] {
 }
 
 export async function handleGraphApprovals(req: Request, deps: GraphApprovalsDeps = {}): Promise<Response> {
-  const pathname = new URL(req.url).pathname;
+  const url = new URL(req.url);
+  const pathname = url.pathname;
+  const sub = /^\/v1\/graph-approvals\/([^/]+)\/([^/]+)\/(feed-draft|media)$/.exec(pathname);
   const match = /^\/v1\/graph-approvals\/([^/]+)\/([^/]+)$/.exec(pathname);
-  if (pathname !== GRAPH_APPROVALS_PATH && !match) return jsonResponse({ error: 'not-found' }, 404);
+  if (pathname !== GRAPH_APPROVALS_PATH && !match && !sub) return jsonResponse({ error: 'not-found' }, 404);
   if (!deps.authorize?.(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (sub) return handleFeed(req, url, sub[1]!, sub[2]!, sub[3] as 'feed-draft' | 'media', deps);
   if (pathname === GRAPH_APPROVALS_PATH) {
     if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
     // ⭐ `items` is unchanged; `decided` is additive (newest first) for other devices' cards.
-    return jsonResponse({ items: list(deps.root ?? effectiveInstanceRoot()), decided: (deps.decisions ?? defaultDecisionRing).list() });
+    return jsonResponse({ items: list(deps.root ?? effectiveInstanceRoot(), deps.configDir ?? getElanousConfigDir()), decided: (deps.decisions ?? defaultDecisionRing).list() });
   }
   if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
   const authReason = deps.authReason?.(req);
@@ -172,3 +192,50 @@ export async function handleGraphApprovals(req: Request, deps: GraphApprovalsDep
   debug.log('approvals.graph', 'decided', { graphId, runId, nodeId, decision, by: `pwa:${authReason}` });
   return jsonResponse({ graphId, runId, decision });
 }
+
+/** EV10d — `PUT …/:graphId/:runId/feed-draft` (사람 수정 저장) · `GET …/:graphId/:runId/media?path=` (초안 미디어). */
+async function handleFeed(req: Request, url: URL, rawGraphId: string, rawRunId: string, kind: 'feed-draft' | 'media', deps: GraphApprovalsDeps): Promise<Response> {
+  let graphId: string;
+  let runId: string;
+  try { graphId = decodeURIComponent(rawGraphId); runId = decodeURIComponent(rawRunId); }
+  catch { return jsonResponse({ error: 'not-found' }, 404); }
+  if (!validSegment(graphId) || !validSegment(runId)) return jsonResponse({ error: 'not-found' }, 404);
+  const root = deps.root ?? effectiveInstanceRoot();
+  const state = readRun(root, graphId, runId);
+  const folder = state && isFeedPreviewMessage(state.pending?.message ?? '') ? feedFolderFor(state, deps.configDir ?? getElanousConfigDir()) : null;
+  if (!state || !folder) {
+    debug.log('approvals.feed', 'refused', { graphId, reason: 'not-feed' });
+    return jsonResponse({ error: 'not-found' }, 404);
+  }
+  if (kind === 'media') {
+    if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+    const file = resolveFeedMedia(folder, url.searchParams.get('path') ?? '');
+    if (!file) {
+      debug.log('approvals.feed', 'refused', { graphId, reason: 'media-path' });
+      return jsonResponse({ error: 'not-found' }, 404);
+    }
+    debug.log('approvals.feed', 'media-served', { graphId });
+    return new Response(Bun.file(file), { headers: { 'content-type': mediaContentType(file), 'cache-control': 'private, max-age=60' } });
+  }
+  if (req.method !== 'PUT') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  const authReason = deps.authReason?.(req);
+  if (!authReason || !DECISION_AUTH_REASONS.has(authReason)) {
+    debug.log('approvals.feed', 'refused', { graphId, reason: 'pairing-required' });
+    return jsonResponse({ error: 'pairing-required' }, 403);
+  }
+  if (!undecided(state, root)) return jsonResponse({ error: 'already-decided' }, 409);
+  const current = readFeedDraft(folder);
+  if (!current) return jsonResponse({ error: 'not-found' }, 404);
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const result = applyFeedEdit(current, body);
+  if (!result.ok) {
+    debug.log('approvals.feed', 'refused', { graphId, reason: result.error });
+    return jsonResponse({ error: result.error }, 400);
+  }
+  writeFeedDraft(folder, result.draft);
+  debug.log('approvals.feed', 'draft-saved', { graphId, revision: result.draft.revision });
+  const { folder: _folder, ...feed } = result.draft;
+  return jsonResponse({ graphId, runId, feed });
+}

package/src/nexus/api/http-server.ts

@@ -15,6 +15,8 @@
 // Port policy (N1-2 decision): auto-pick from 31415 upward. Actual port
 // is recorded in runtime.json + printed in boot banner.
 
+import { setInProcessOutbound } from '../../domains/outbound-alert.js';
+import { getUserConfig } from '../../user-config.js';
 import type { TelegramEvent } from '../../workflow-runtime/triggers/telegram-source.js';
 import { spawnSync } from 'node:child_process';
 import { compareTokenConstTime } from '../../acp/transport/auth.js';
@@ -198,7 +200,11 @@ import { handleMcpResourceGet, MCP_RESOURCE_ROUTE_PATH } from './mcp-resource-ro
 import { APPROVALS_MERGES_PATH, DESIGN_DIRECTION_PATH, DESIGN_PREVIEW_PATH_PREFIX, DESIGN_PREVIEWS_PATH, DESIGN_SYSTEM_PATH, IPA_PATH_PREFIX, MANIFEST_PATH } from './rest-route-paths.js';
 import { handleMergeApprovals } from './merge-approvals.js';
 import { GRAPH_APPROVALS_PATH, handleGraphApprovals } from './graph-approvals.js';
-import { FIELD_SERVER_MAX_BODY_BYTES, FIELD_UPLOADS_PATH, handleFieldUploads } from './field-uploads.js';
+import { handleExecRequests } from './exec-requests.js';
+import { handleSeatRequests, SEAT_REQUESTS_PATH, type SeatRequestsDeps } from './seat-requests.js';
+import { handleConsultRequests, CONSULT_REQUESTS_PATH, type ConsultRequestsDeps } from './consult-requests.js';
+import { ExecRequestRunner } from '../../exec-requests/runner.js';
+import { FIELD_SERVER_MAX_BODY_BYTES, FIELD_UPLOADS_PATH, FIELD_REEL_PATH, FIELD_REEL_FILE_PATH, handleFieldUploads } from './field-uploads.js';
 import { handleLiveDetail, LIVE_DETAIL_PATH } from './live-detail.js';
 import { handleLiveShipped, LIVE_SHIPPED_PATH } from './live-shipped.js';
 import { handleMcpWidgetCall, MCP_WIDGET_CALL_ROUTE_PATH, persistWidgetTurnToSessionStore } from './mcp-widget-call-route.js';
@@ -236,6 +242,7 @@ import {
   parseErrorsPath,
 } from './errors.js';
 import { handleChatBackendDetection } from './chat-backend-detection.js';
+import { handleChatFastPathConfig } from './chat-fast-path-config.js';
 import { connectInfoTokenAllowed, handleConnectInfoGet, handleConnectTokenMint, type ConnectInfoCtx } from './connect-info.js';
 import { handleStaticAppRequest, pathMatchesStaticPrefix } from './static-app.js';
 import {
@@ -379,6 +386,8 @@ import {
 import { handleSessionTurnControl, SESSION_TURN_CONTROL_PATH } from '../../session/session-turn-control.js';
 import { authenticatePodCredential, handlePodGrokCredential, handlePodGithubCredential, POD_CREDENTIAL_GROK_PATH, POD_CREDENTIAL_GITHUB_PATH } from './pod-credential-api.js';
 import { handleOutboundReport } from './outbound-report.js';
+import { handleErrorReportIngest } from './error-reports.js';
+import { routeOutboundInProcess } from './outbound-report.js';
 import { handleSelfEvent } from './self-event.js';
 /** 매매 «실행»은 애드온이다(대표 09-20 결정 ③ · 별도 상용 저장소 · release/trading-export.yaml) — 공개 코어엔 없다.
  *  있으면 그 경로를 켜고, 없으면 501. 경로를 변수로 둬 공개본 타입 검사가 «모듈 없음»으로 막히지 않게 한다. */
@@ -446,6 +455,9 @@ export type NexusWsBridgeInit = Omit<WsBridgeOpts, 'hostname' | 'port'>;
 export interface NexusHttpServerOpts {
   /** Optional installer state root for isolated API consumers and tests. */
   pluginStateRoot?: string;
+  execRequests?: ExecRequestRunner;
+  seatRequests?: SeatRequestsDeps;
+  consultRequests?: ConsultRequestsDeps;
   state: NexusState;
   registry: TabRegistry;
   eventBus: NexusEventBus;
@@ -748,6 +760,10 @@ export function startNexusHttpServer(opts: NexusHttpServerOpts): NexusHttpServer
         ...(websocketHandler ? { websocket: websocketHandler } : {}),
       } as unknown as Parameters<typeof Bun.serve>[0];
       server = Bun.serve(fetchOpts);
+      // OB8 — this process now answers /v1/outbound itself; its own sendOutbound calls must not curl it.
+      setInProcessOutbound(routeOutboundInProcess);
+      // 데몬이 «실제로» 떴을 때만 재시작 복구(맡긴 일) — 주입된 러너(시험)는 건드리지 않는다.
+      if (!opts.execRequests) { try { execRequestRunner().reconcileInterrupted(); } catch { /* 복구 실패가 서버 기동을 막지 않는다 */ } }
       resolvedPort = port;
       break;
     } catch (err) {
@@ -770,6 +786,7 @@ export function startNexusHttpServer(opts: NexusHttpServerOpts): NexusHttpServer
     url,
     stop() {
       try { server!.stop(true); } catch { /* idempotent */ }
+      setInProcessOutbound(null);
     },
   };
 }
@@ -786,6 +803,13 @@ function isPortBusy(err: unknown): boolean {
   return /EADDRINUSE|address already in use/i.test(msg);
 }
 
+let execRequestRunnerInstance: ExecRequestRunner | undefined;
+/** 게으른 한 벌 — import 만으로는 만들지 않는다(재시작 복구가 import 에 묶이지 않게). */
+function execRequestRunner(): ExecRequestRunner {
+  execRequestRunnerInstance ??= new ExecRequestRunner();
+  return execRequestRunnerInstance;
+}
+
 export async function routeRequest(
   req: Request,
   opts: NexusHttpServerOpts,
@@ -834,21 +858,31 @@ export async function routeRequest(
   // Per-route checkAuth calls below stay in place.
   // OPTIONS is a CORS preflight and cannot carry Authorization; existing
   // handlers answer it themselves, so the gate does not swallow it.
-  // A runtime-less tab mutation still needs authentication before the
-  // dispatcher can return its 503. Do not enable this fallback for other paths.
-  const runtimeLessTabMutation = !opts.metaApi && method !== 'GET' && method !== 'OPTIONS'
-    && (pathname === '/v1/nexus/tabs' || pathname.startsWith('/v1/nexus/tabs/'));
+  // Without metaApi, only the owner bearer may reach these runtime-less
+  // meta-API stubs. All other private paths remain default-denied.
+  const runtimeLessMetaRoute = !opts.metaApi && (
+    (method !== 'GET' && method !== 'OPTIONS'
+      && (pathname === '/v1/nexus/tabs' || pathname.startsWith('/v1/nexus/tabs/')))
+    || (method === 'GET' && (
+      ['/v1/simulations', '/v1/tools', '/v1/intake', '/v1/sessions', '/v1/control-signals', '/v1/turns/last/screenshot'].includes(pathname)
+      || pathname.startsWith('/v1/recordings/')
+    ))
+    || (method === 'POST' && (
+      ['/v1/intake', '/v1/sessions/external', '/v1/control-signals', '/v1/prompt'].includes(pathname)
+      || pathname.startsWith('/v1/hitl/callback/')
+    ))
+  );
   if (
     method !== 'OPTIONS'
     && pathname.startsWith('/v1/')
     && !isPublicRoute(method, pathname, { setupMode: false })
   ) {
-    const fallbackToken = runtimeLessTabMutation ? ensureAuthToken().token : undefined;
+    const fallbackToken = runtimeLessMetaRoute ? ensureAuthToken().token : undefined;
     const offered = req.headers.get('authorization');
     const fallbackAuthorized = fallbackToken !== undefined && offered?.startsWith('Bearer ') === true
       && compareTokenConstTime(offered.slice('Bearer '.length).trim(), fallbackToken);
     if (!(opts.metaApi ? checkAuth(req, opts.metaApi) : fallbackAuthorized)) {
-      const name = method === 'POST' && pathname === '/v1/tasks' && opts.metaApi
+      const name = method === 'POST' && (pathname === '/v1/tasks' || pathname === '/v1/reports/ingest') && opts.metaApi
         ? matchIngestAuthorization(req)?.name
         : undefined;
       if (name === undefined) {
@@ -919,6 +953,25 @@ export async function routeRequest(
     });
   }
 
+  if (pathname === SEAT_REQUESTS_PATH) {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleSeatRequests(req, opts.seatRequests);
+  }
+
+  if (pathname === CONSULT_REQUESTS_PATH) {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleConsultRequests(req, opts.consultRequests);
+  }
+
+  if (pathname === '/v1/exec-requests' || pathname.startsWith('/v1/exec-requests/')) {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    if (/^\/v1\/exec-requests\/[^/]+\/files\//.test(pathname)) {
+      const credential = bearerCredential(req, opts.metaApi);
+      if (credential !== 'bearer-match' && credential !== 'temp-token') return jsonResponse({ error: 'unauthorized' }, 401);
+    }
+    return handleExecRequests(req, opts.execRequests ?? execRequestRunner());
+  }
+
   if (pathname === GRAPH_APPROVALS_PATH || pathname.startsWith(`${GRAPH_APPROVALS_PATH}/`)) {
     return handleGraphApprovals(req, {
       authorize: (request) => !!opts.metaApi && checkAuth(request, opts.metaApi),
@@ -926,9 +979,11 @@ export async function routeRequest(
     });
   }
   // 현장 업로드(owner 전용) — GET 목록 · POST 저장. 저장 규칙 정본 = src/field/field-media.ts.
-  if (pathname === FIELD_UPLOADS_PATH && (method === 'GET' || method === 'POST')) {
+  if ((pathname === FIELD_UPLOADS_PATH && (method === 'GET' || method === 'POST'))
+    || ((pathname === FIELD_REEL_PATH || pathname === FIELD_REEL_FILE_PATH) && method === 'GET')) {
     return handleFieldUploads(req, {
       authorize: (request) => !!opts.metaApi && checkAuth(request, opts.metaApi),
+      configuredEvent: () => { try { return getUserConfig().telegram?.fieldDefaultEvent; } catch { return undefined; } },
     });
   }
   if (pathname === APPROVALS_MERGES_PATH || pathname.startsWith(`${APPROVALS_MERGES_PATH}/`)) {
@@ -1217,6 +1272,11 @@ export async function routeRequest(
     return handleGraphsValidatePost(req, opts.metaApi);
   }
 
+  if (pathname === '/v1/config/chat-fast-path' && (method === 'GET' || method === 'PUT')) {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleChatFastPathConfig(req);
+  }
+
   // Mutation routes (PR ι) — POST/PATCH/DELETE on /v1/nexus/tabs[/:id[/action]].
   // Templates POST handled here too (PR κ).
   // Config / secrets PUT/POST/DELETE here too (PR μ).
@@ -1250,6 +1310,8 @@ export async function routeRequest(
       if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
       return handleTaskCreatePost(req, opts.metaApi);
     }
+    // ER2 — error reports forwarded by the bot VM (ingest token · same as /v1/tasks).
+    if (method === 'POST' && pathname === '/v1/reports/ingest') return handleErrorReportIngest(req);
     if (method === 'POST' && pathname.startsWith('/v1/tasks/') && pathname.endsWith('/approve')) {
       if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
       let taskId: string;
@@ -1915,6 +1977,18 @@ export async function routeRequest(
     }
     // HANDOFF §4.2 follow-up — skill-side mirror of the workflow
     // router. Same regex → LLM cascade, applied to the skill index.
+    // SK2 (PWA) — skills the index could not read: list ⊕ confirmed repair.
+    if (pathname === '/v1/skills/problems' || pathname === '/v1/skills/problems/repair') {
+      if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+      const { handleSkillProblems } = await import('./skill-problems.js');
+      return handleSkillProblems(req, opts.metaApi);
+    }
+    // SC1 (PWA · beta) — «공유용 캡처»: masked screen PNG in, metadata chunks stripped, stored under <configDir>/captures.
+    if (pathname === '/v1/captures' || pathname.startsWith('/v1/captures/')) {
+      if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+      const { handleShareCaptures } = await import('./share-captures.js');
+      return handleShareCaptures(req, opts.metaApi);
+    }
     if (pathname === '/v1/skills/route' && method === 'POST') {
       if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
       return handleSkillRoute(req, opts.metaApi);

package/src/nexus/api/outbound-report.ts

@@ -44,6 +44,13 @@ function json(body: unknown, status: number): Response {
   });
 }
 
+/** The daemon's own sendOutbound path (OB8) — what POST /v1/outbound does, without the HTTP self-call. */
+export async function routeOutboundInProcess(text: string, kind: string): Promise<boolean> {
+  const result = await routeOutbound(getUserConfig(), { text, markdown: false, kind });
+  if (result.delivered) recordOutboundEvent(text, kind);
+  return result.delivered;
+}
+
 /** POST /v1/outbound — fan one message out to the routed channels. */
 export async function handleOutboundReport(req: Request, metaApi: MetaApiOpts): Promise<Response> {
   if (!checkAuth(req, metaApi)) return json({ error: 'unauthorized' }, 401);

package/src/nexus/api/running-runs-background.ts

@@ -0,0 +1,68 @@
+// The terminals list must answer at once and must never share the event loop with a ledger scan: the running-runs query
+// reads every run ledger synchronously (~5k files · 0.9–1.8 s on 10-02), which froze typing in the web terminal while the
+// PWA polled the list. This keeps the last result as a snapshot and refreshes it in a separate bun process, on demand.
+import { join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import type { RunningRunsResult } from '../../self-implement/running-runs.js';
+
+export const RUNNING_RUNS_REFRESH_MS = 15_000;
+/** A refresh that has not answered by then is abandoned; the next request starts another. */
+export const RUNNING_RUNS_REFRESH_TIMEOUT_MS = 60_000;
+
+export interface RunningRunsSnapshot {
+  /** Last result, or null before the first refresh finished (subjects then keep unknown assessments). */
+  readonly result: RunningRunsResult | null;
+  /** Milliseconds since `result` was computed; null when there is none. */
+  readonly ageMs: number | null;
+}
+
+/** Runs the query somewhere other than this event loop and resolves with its JSON output. */
+export type RunningRunsRunner = (includeTest: boolean) => Promise<RunningRunsResult>;
+
+export const RUNNING_RUNS_CHILD_SCRIPT = join(import.meta.dir, 'running-runs-child.ts');
+
+/** Default runner: `bun running-runs-child.ts [--include-test]` — the child does the ledger I/O, we only parse its stdout. */
+export const childProcessRunner: RunningRunsRunner = async (includeTest) => {
+  const proc = Bun.spawn([process.execPath, RUNNING_RUNS_CHILD_SCRIPT, ...(includeTest ? ['--include-test'] : [])], {
+    stdout: 'pipe', stderr: 'ignore', stdin: 'ignore', env: process.env,
+  });
+  const timer = setTimeout(() => proc.kill(), RUNNING_RUNS_REFRESH_TIMEOUT_MS);
+  try {
+    const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    if (code !== 0) throw new Error(`running-runs child exit ${code}`);
+    return JSON.parse(out) as RunningRunsResult;
+  } finally { clearTimeout(timer); }
+};
+
+export interface RunningRunsBackground {
+  /** Never blocks: returns the last snapshot and starts a refresh when it is stale and none is in flight. */
+  snapshot(options: { includeTest?: boolean }): RunningRunsSnapshot;
+}
+
+export function createRunningRunsBackground(runner: RunningRunsRunner = childProcessRunner, now: () => number = Date.now, refreshMs = RUNNING_RUNS_REFRESH_MS): RunningRunsBackground {
+  const slots = new Map<boolean, { at: number; result: RunningRunsResult }>();
+  const flights = new Set<boolean>();
+  const refresh = (includeTest: boolean): void => {
+    if (flights.has(includeTest)) return;
+    flights.add(includeTest);
+    const started = now();
+    void runner(includeTest)
+      .then((result) => {
+        slots.set(includeTest, { at: now(), result });
+        debug.log('nexus.terminals', 'running-runs-refreshed', { includeTest, ms: now() - started });
+      })
+      .catch((error: unknown) => {
+        debug.log('nexus.terminals', 'running-runs-refresh-failed', { includeTest, reason: error instanceof Error ? error.message.slice(0, 80) : 'unknown' }, { level: 'warn' });
+      })
+      .finally(() => { flights.delete(includeTest); });
+  };
+  return {
+    snapshot(options) {
+      const includeTest = options.includeTest === true;
+      const slot = slots.get(includeTest);
+      const t = now();
+      if (!slot || t - slot.at >= refreshMs) refresh(includeTest);
+      return slot ? { result: slot.result, ageMs: t - slot.at } : { result: null, ageMs: null };
+    },
+  };
+}

package/src/nexus/api/running-runs-child.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+// Child of running-runs-background.ts: runs the running-runs query (all the ledger I/O) and prints the result as JSON.
+import { queryRunningRuns } from '../../self-implement/running-runs.js';
+
+const result = queryRunningRuns({ includeTest: process.argv.includes('--include-test'), caller: 'nexus.terminals' });
+process.stdout.write(JSON.stringify(result));