elanous 0.2.9 → 0.2.11

package/src/nexus/api/setup-codex-login.ts

@@ -0,0 +1,160 @@
+import { debug } from '../../debug/log.js';
+import { loginWithCodexBrowser } from '../../oauth/codex-browser-login.js';
+import {
+  CODEX_DEVICE_LOGIN_URL,
+  exchangeDeviceAuthCode,
+  pollDeviceCode,
+  requestDeviceCode,
+} from '../../oauth/codex.js';
+import { expiresAtFromSeconds, saveTokens } from '../../oauth/store.js';
+import { getUserConfig, reloadUserConfig, saveUserConfig } from '../../user-config.js';
+
+type Mode = 'browser' | 'device';
+type CodexLoginStatus =
+  | { state: 'idle' }
+  | { state: 'pending'; mode: Mode; authorizeUrl?: string; userCode?: string; verificationUrl?: string }
+  | { state: 'ok'; mode: Mode }
+  | { state: 'error'; mode: Mode; error: string };
+
+const TIMEOUT_MS = 5 * 60_000;
+const SAFE_ERRORS = [
+  'timeout', 'authorization-denied', 'browser-unavailable', 'port-unavailable',
+  'token-exchange', 'device-code-failed', 'device-poll-failed', 'config-save-failed',
+] as const;
+
+type Failure = typeof SAFE_ERRORS[number];
+function reason(error: unknown, mode: Mode): Failure {
+  const message = error instanceof Error ? error.message : '';
+  for (const value of SAFE_ERRORS) if (message === value || message === `codex browser login failed: ${value}`) return value;
+  return mode === 'browser' ? 'browser-unavailable' : 'device-poll-failed';
+}
+
+interface LoginDeps {
+  browser: (openBrowser: (url: string) => boolean) => Promise<unknown>;
+  device: (ready: (userCode: string, verificationUrl: string) => void) => Promise<unknown>;
+  saveProvider: () => void;
+  observe: (event: 'started' | 'ok' | 'error', mode: Mode) => void;
+}
+
+async function deviceLogin(ready: (userCode: string, verificationUrl: string) => void): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  const fetchImpl = ((input, init) => fetch(input, { ...init, signal: controller.signal })) as typeof fetch;
+  try {
+    let code: Awaited<ReturnType<typeof requestDeviceCode>>;
+    try { code = await requestDeviceCode({ fetchImpl }); }
+    catch { throw new Error('device-code-failed'); }
+    if (controller.signal.aborted) throw new Error('timeout');
+    ready(code.user_code, code.verification_uri || CODEX_DEVICE_LOGIN_URL);
+    const interval = Math.max(3000, (code.interval ?? 0) * 1000);
+    const deadline = Date.now() + TIMEOUT_MS;
+    while (!controller.signal.aborted && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+      if (controller.signal.aborted || Date.now() >= deadline) break;
+      let result: Awaited<ReturnType<typeof pollDeviceCode>>;
+      try { result = await pollDeviceCode(code.device_auth_id, code.user_code, { fetchImpl }); }
+      catch { throw new Error('device-poll-failed'); }
+      if (!result) continue;
+      let token: Awaited<ReturnType<typeof exchangeDeviceAuthCode>>;
+      try { token = await exchangeDeviceAuthCode(result.authorization_code, result.code_verifier, { fetchImpl }); }
+      catch { throw new Error('token-exchange'); }
+      if (controller.signal.aborted) break;
+      saveTokens('openai-codex', {
+        accessToken: token.access_token,
+        refreshToken: token.refresh_token,
+        ...(token.id_token ? { idToken: token.id_token } : {}),
+        expiresAt: expiresAtFromSeconds(token.expires_in),
+        scope: token.scope,
+        tokenType: token.token_type ?? 'Bearer',
+      }, { authMode: 'chatgpt' });
+      return;
+    }
+    throw new Error('timeout');
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error('timeout');
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function saveCodexProvider(): void {
+  const cur = getUserConfig();
+  saveUserConfig({ ...cur, llm: { ...cur.llm, provider: 'openai-codex', apiKey: undefined, baseUrl: undefined, model: undefined } });
+  reloadUserConfig();
+}
+
+const defaultDeps: LoginDeps = {
+  browser: (openBrowser) => loginWithCodexBrowser({ openBrowser, timeoutMs: TIMEOUT_MS }),
+  device: deviceLogin,
+  saveProvider: saveCodexProvider,
+  observe: (event, mode) => { debug.log('setup.codex-login', event, { mode }); },
+};
+
+function json(body: CodexLoginStatus | { error: string }, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status, headers: { 'content-type': 'application/json; charset=utf-8', 'access-control-allow-origin': '*' },
+  });
+}
+
+/** One in-process login survives leaving or reloading the setup page. */
+export function createCodexLoginHandlers(deps: LoginDeps = defaultDeps) {
+  let status: CodexLoginStatus = { state: 'idle' };
+  let preparing: Promise<void> | undefined;
+  let generation = 0;
+
+  const get = (): Response => json(status);
+
+  const post = async (req: Request): Promise<Response> => {
+    let body: unknown;
+    try { body = await req.json(); } catch { return json({ error: 'invalid-json' }, 400); }
+    const mode = body && typeof body === 'object' && 'mode' in body ? body.mode : undefined;
+    if (mode !== 'browser' && mode !== 'device') return json({ error: 'invalid-mode' }, 400);
+    // Same method again → the login already in flight. A different method → start over; the older
+    // attempt's result is ignored (generation). Browser → device is the recovery path when a popup
+    // was blocked; device needs no local port, so it never collides with the browser's callback server.
+    if (status.state === 'pending' && status.mode === mode) {
+      if (preparing) await preparing;
+      return json(status);
+    }
+
+    status = { state: 'pending', mode };
+    const attempt = ++generation;
+    deps.observe('started', mode);
+    let resolveReady!: () => void;
+    preparing = new Promise<void>((resolve) => { resolveReady = resolve; });
+    const ready = (fields: Pick<Extract<CodexLoginStatus, { state: 'pending' }>, 'authorizeUrl' | 'userCode' | 'verificationUrl'>) => {
+      if (generation === attempt && status.state === 'pending' && status.mode === mode) {
+        status = { ...status, ...fields };
+        resolveReady();
+      }
+    };
+    void (async () => {
+      try {
+        if (mode === 'browser') {
+          await deps.browser((url) => { ready({ authorizeUrl: url }); return true; });
+        } else {
+          await deps.device((userCode, verificationUrl) => ready({ userCode, verificationUrl }));
+        }
+        if (generation !== attempt) return;
+        try { deps.saveProvider(); } catch { throw new Error('config-save-failed'); }
+        status = { state: 'ok', mode };
+        deps.observe('ok', mode);
+      } catch (error) {
+        if (generation !== attempt) return;
+        status = { state: 'error', mode, error: reason(error, mode) };
+        deps.observe('error', mode);
+      } finally {
+        resolveReady();
+        if (generation === attempt) preparing = undefined;
+      }
+    })();
+    await preparing;
+    return json(status);
+  };
+  return { get, post };
+}
+
+const login = createCodexLoginHandlers();
+export const handleSetupCodexLoginGet = login.get;
+export const handleSetupCodexLoginPost = login.post;

package/src/nexus/api/sub-seat-charters.ts

@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../debug/log.js';
+
+export interface SubSeatCharter { id: string; seat: string; sub: string; title: string }
+
+export function listSubSeatCharters(root = join(import.meta.dir, '..', '..', '..', 'docs', 'roles'), onUnreadable?: () => void): SubSeatCharter[] {
+  try {
+    readdirSync(root);
+    const charters: SubSeatCharter[] = [];
+    for (const seat of ['OP', 'MK', 'TC', 'UX']) {
+      let entries;
+      try { entries = readdirSync(join(root, seat), { withFileTypes: true }); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile() || !/^[a-z][a-z0-9-]{0,31}\.md$/.test(entry.name)) continue;
+        const sub = entry.name.slice(0, -3);
+        const id = `${seat}/${sub}`;
+        const content = readFileSync(join(root, seat, entry.name), 'utf8');
+        const heading = content.split(/\r?\n/).find((line) => line.startsWith('# '));
+        const title = heading?.slice(2).startsWith(`${id} — `) ? heading.slice(2 + id.length + 3).trim() || id : id;
+        charters.push({ id, seat, sub, title });
+      }
+    }
+    return charters.sort((a, b) => a.id.localeCompare(b.id));
+  } catch (error) {
+    debug.log('ops.seats', 'charters-unreadable', { root, error: error instanceof Error ? error.message : String(error) });
+    onUnreadable?.();
+    return [];
+  }
+}

package/src/nexus/api/tabs-mutations.ts

@@ -78,6 +78,8 @@ interface CreateTabBody {
   kind?: string;
   id?: string;
   label?: string;
+  /** Conversation owning a newly created webterm. */
+  sessionId?: string;
   /** Kind-specific factory opts (passed through to the factory). */
   kindOpts?: Record<string, unknown>;
   /** When true (default), supervisor.startTab is called immediately
@@ -95,7 +97,7 @@ function buildTabSpec(body: CreateTabBody, id: string): { spec: TabSpec; reason?
     case 'chat':
       return { spec: createChatTabSpec(opts as Parameters<typeof createChatTabSpec>[0]) };
     case 'webterm':
-      return { spec: createWebtermTabSpec(opts as Parameters<typeof createWebtermTabSpec>[0]) };
+      return { spec: createWebtermTabSpec({ ...opts, sessionId: body.sessionId ?? opts.sessionId } as Parameters<typeof createWebtermTabSpec>[0]) };
     case 'daemon':
       return { spec: createDaemonTabSpec(opts as Parameters<typeof createDaemonTabSpec>[0]) };
     case 'pwa-host':

package/src/nexus/api/trace.ts

@@ -9,6 +9,7 @@ import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './json-response.js';
 import { runLedgerDir, runLedgerPath } from '../../self-implement/run-ledger.js';
 import { scanStoresForRun } from './trace-run-scan.js';
+import { listSessions } from '../../session/index.js';
 
 export type TraceLevel = 'L0' | 'L1' | 'L2' | 'L3';
 export interface TraceEvent {
@@ -17,6 +18,7 @@ export interface TraceEvent {
   universe: string;
   machine?: string;
   runId?: string;
+  projectId?: string;
   parentRunId?: string;
   phase?: string;
   shard?: string;
@@ -83,6 +85,7 @@ function eventFor(row: LogStoreRow): TraceEvent {
     id: evidenceRef(universe, row.id), ts: row.ts, universe,
     ...(machine ? { machine } : {}),
     ...(runId ? { runId } : {}),
+    ...(text(data.projectId) ? { projectId: text(data.projectId) } : {}),
     ...(text(data.parentRunId) ? { parentRunId: text(data.parentRunId) } : {}),
     ...(text(data.phase) ? { phase: text(data.phase) } : {}),
     ...(text(data.shard) ? { shard: text(data.shard) } : {}),
@@ -259,11 +262,15 @@ function options(url: URL): { level: TraceLevel; limit: number; from?: number; t
   if (from === null || to === null || (from !== undefined && to !== undefined && from > to)) return { level, limit: n, error: 'invalid time range' };
   return { level, limit: Math.min(n, TRACE_LIMIT), ...(from !== undefined ? { from } : {}), ...(to !== undefined ? { to } : {}) };
 }
-function matches(row: LogStoreRow, url: URL): boolean {
+function matches(row: LogStoreRow, url: URL, projectSessions?: ReadonlySet<string>): boolean {
   const data = dataFor(row);
   const runId = url.searchParams.get('runId');
   const universe = url.searchParams.get('universe');
   const kind = url.searchParams.get('kind');
+  const projectId = url.searchParams.get('projectId');
+  if (projectId !== null && (Object.hasOwn(data, 'projectId')
+    ? data.projectId !== projectId
+    : !projectSessions?.has(row.session_id ?? '') && !projectSessions?.has(text(data.sessionId) ?? ''))) return false;
   const q = url.searchParams.get('q')?.toLowerCase();
   if (runId && data.runId !== runId && data.run_id !== runId) return false;
   if (universe && row.instance !== universe) return false;
@@ -295,6 +302,8 @@ function findRunUniverse(runId: string, selected: readonly string[], deps: Trace
 export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {}): Response {
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
   const url = new URL(req.url);
+  const projectId = url.searchParams.get('projectId');
+  const projectSessions = projectId === null ? undefined : new Set(listSessions({ projectId }).map(session => session.id));
   const parsed = options(url);
   if (parsed.error) return jsonResponse({ ok: false, error: 'bad_request', reason: parsed.error }, 400);
   const names = storeNames(url, deps);
@@ -315,7 +324,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       for (const entry of stores) {
         if (!entry.store) { failures.push({ name: entry.name, reason: entry.error ?? 'log-store-unavailable' }); continue; }
         try {
-          const page = entry.store.aggregateRuns({ sinceMs: parsed.from, untilMs: parsed.to }, RUN_LIMIT);
+          const page = entry.store.aggregateRuns({ sinceMs: parsed.from, untilMs: parsed.to,
+            ...(projectId !== null ? { projectId, projectSessionIds: [...projectSessions!] } : {}) }, RUN_LIMIT);
           if (page.length >= RUN_LIMIT) runLimitReached = true;
           runs.push(...page.map((run) => ({ ...run, universe: entry.name })));
           opened++;
@@ -334,7 +344,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
     for (const entry of stores) {
       if (!entry.store) { failures.push({ name: entry.name, reason: entry.error ?? 'log-store-unavailable' }); continue; }
       try {
-        const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1 };
+        const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1,
+          ...(projectId !== null ? { projectId, projectSessionIds: [...projectSessions!] } : {}) };
         const search = url.searchParams.get('q');
         if (search) query.grep = search;
         // Restrict a run before paging; other JSON-only filters still apply to the bounded window.
@@ -349,7 +360,7 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
     const runId = url.searchParams.get('runId');
     let resolution: { universe?: string; checked: number; truncated?: boolean; unresolved?: boolean } | undefined;
     let resolvedFrom: 'ledger' | 'log-scan' | undefined;
-    if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url)) && !requestedUniverse) {
+    if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url, projectSessions)) && !requestedUniverse) {
       // A store with no log db at all («has no log store yet» — e.g. the daemon's own tree-derived universe) cannot
       // hold the run, so it must not block the ledger lookup. A store that exists but failed to open/read still does:
       // «could not read» is never answered as «not there». The reply keeps `failedStores` either way.
@@ -379,7 +390,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
         if (!entry?.store) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: [{ name, reason: entry?.error ?? 'log-store-unavailable' }] }, 503);
         stores.push(entry);
         try {
-          const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1 };
+          const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1,
+            ...(projectId !== null ? { projectId, projectSessionIds: [...projectSessions!] } : {}) };
           const search = url.searchParams.get('q');
           if (search) query.grep = search;
           const page = entry.store.queryTraceRun(runId, query);
@@ -388,7 +400,7 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
         } catch (e) { return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: [{ name, reason: e instanceof Error ? e.message : String(e) }] }, 503); }
       }
     }
-    const filtered = rows.filter((row) => matches(row, url)).sort(sortRows);
+    const filtered = rows.filter((row) => matches(row, url, projectSessions)).sort(sortRows);
     const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0 || resolution?.truncated === true);
     try { (deps.queryLog ?? ((details) => debug.log('logs.trace', 'query', details)))({ stores: names, level: parsed.level, count: trace.events.length, truncated: trace.truncated, mode: 'rows', runs: trace.nodes.filter((node) => node.level === 'L1' && node.count > 0).length }); } catch { /* query logging must not block reads */ }
     return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom, runUniverse: resolution.universe, ...(resolvedFrom === 'log-scan' ? { checked: resolution.checked } : {}) } : { runUniverse: resolution.truncated || resolution.unresolved ? 'unresolved' as const : 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);

package/src/nexus/api/usage-api.ts

@@ -0,0 +1,102 @@
+import { collectUnifiedUsage } from '../../budget/unified-usage.js';
+import type { UnifiedUsageReport } from '../../budget/types.js';
+import { jsonResponse } from './json-response.js';
+
+const CACHE_MS = 30_000;
+
+// TC 조건(10-03 01:21): 계정 이름·이메일·토큰은 응답에 «하나도» 싣지 않는다 — 공급자·사용률·리셋만.
+// 계정이 여럿이면 공급자 안 순번(«계정 1»)으로만 가른다(이름에서 비밀을 걸러 내는 방식은 쓰지 않는다).
+function accountLabel(index: number, count: number): string {
+  return count > 1 ? `계정 ${index + 1}` : '계정';
+}
+
+const SAFE_REASONS = new Set(['query-does-not-supply', 'not-a-subscription']);
+function safeReason(reason: unknown): string {
+  return typeof reason === 'string' && SAFE_REASONS.has(reason) ? reason : 'unknown';
+}
+
+function periodType(value: string | null): string | null {
+  return value && /^(?:session|weekly|monthly|daily|prepaid-usd|USAGE_PERIOD_TYPE_(?:SESSION|WEEKLY|MONTHLY|DAILY))$/.test(value) ? value : null;
+}
+
+function isoDate(value: string | null): string | null {
+  if (!value) return null;
+  const epoch = Date.parse(value);
+  return Number.isFinite(epoch) && epoch > 0 ? new Date(epoch).toISOString() : null;
+}
+
+function resetsInMs(resetsAt: number, nowMs: number): number | null {
+  return Number.isFinite(resetsAt) && resetsAt > 0 ? Math.max(0, resetsAt - nowMs) : null;
+}
+
+function projectUsage(report: UnifiedUsageReport, nowMs: number) {
+  return {
+    ok: true as const,
+    accountCounts: {
+      codex: report.accountCounts.codex,
+      grok: report.accountCounts.grok,
+      openrouter: report.accountCounts.openrouter,
+    },
+    rows: report.rows.map((row, _i, rows) => ({
+      provider: row.provider,
+      account: accountLabel(rows.filter((r) => r.provider === row.provider).indexOf(row), rows.filter((r) => r.provider === row.provider).length),
+      accountCount: row.accountCount,
+      soleAccount: row.soleAccount,
+      credits: row.credits.status === 'ok' ? {
+        status: 'ok' as const,
+        usedPercent: row.credits.usedPercent,
+        periodType: periodType(row.credits.periodType),
+        periodStart: isoDate(row.credits.periodStart),
+        periodEnd: isoDate(row.credits.periodEnd),
+        resetsInMs: resetsInMs(row.credits.periodEnd ? Date.parse(row.credits.periodEnd) : 0, nowMs),
+        monthlyLimit: row.credits.monthlyLimit,
+        used: row.credits.used,
+        onDemandCap: row.credits.onDemandCap,
+        onDemandUsed: row.credits.onDemandUsed,
+        prepaidBalance: row.credits.prepaidBalance,
+        balance: row.credits.balance,
+        hasCredits: row.credits.hasCredits,
+        unlimited: row.credits.unlimited,
+      } : { status: row.credits.status },
+      subscription: row.subscription.status === 'available' ? {
+        status: 'available' as const,
+        remainingPercent: row.subscription.remainingPercent,
+        resetsAt: row.subscription.resetsAt,
+        resetsInMs: resetsInMs(row.subscription.resetsAt, nowMs),
+        windowKind: row.subscription.windowKind,
+      } : { status: 'unavailable' as const, reason: safeReason(row.subscription.reason) },
+      resetCredits: row.resetCredits.status === 'available' || row.resetCredits.status === 'expiring-soon' || row.resetCredits.status === 'expired' ? {
+        status: row.resetCredits.status,
+        expiresAt: isoDate(row.resetCredits.expiresAt),
+        hasUnknownExpiry: row.resetCredits.hasUnknownExpiry,
+      } : { status: row.resetCredits.status },
+    })),
+  };
+}
+
+/** A per-daemon 30-second snapshot; concurrent requests share the same collection. */
+export function createUsageHandler(
+  collect: () => Promise<UnifiedUsageReport> = collectUnifiedUsage,
+  now: () => number = Date.now,
+): () => Promise<Response> {
+  let cached: ReturnType<typeof projectUsage> | undefined;
+  let cachedAt = 0;
+  let pending: Promise<ReturnType<typeof projectUsage>> | undefined;
+  return async () => {
+    if (cached && now() - cachedAt < CACHE_MS) return jsonResponse(cached);
+    pending ??= Promise.resolve().then(collect).then((report) => {
+      const value = projectUsage(report, now());
+      cached = value;
+      cachedAt = now();
+      return value;
+    }).finally(() => { pending = undefined; });
+    try {
+      return jsonResponse(await pending);
+    } catch {
+      // Upstream exceptions can contain credentials; never echo their messages.
+      return jsonResponse({ ok: false, reason: 'usage-collection-failed' });
+    }
+  };
+}
+
+export const handleUsageGet = createUsageHandler();

package/src/nexus/api/workflow-run-event-bridge.ts

@@ -73,6 +73,7 @@ export function publishWorkflowRunEvent(
   const detail: Record<string, unknown> = {
     runId: ctx.runId,
     workflowName: ctx.workflowName,
+    ...(evt.mode !== undefined ? { mode: evt.mode } : {}),
   };
   if (evt.type === 'node_start' || evt.type === 'node_skipped' || evt.type === 'node_done') {
     detail.nodeId = evt.nodeId;

package/src/nexus/api/workflows.ts

@@ -40,8 +40,12 @@ import {
   parseWorkflowYaml,
   runWorkflow,
   saveWorkflow,
+  topoSort,
   type WorkflowDeps,
   type WorkflowEvent,
+  type WorkflowRunMode,
+  type NodeOutput,
+  type RunWorkflowOpts,
 } from '../../workflow-runtime/index.js';
 import { buildRunCft, buildRunSkill } from '../../workflow-runtime/deps-bridge.js';
 import {
@@ -59,6 +63,7 @@ import { runApprovalAcrossChannels } from './workflow-approval-multi-channel.js'
 interface RunRecord {
   runId: string;
   workflowName: string;
+  mode: WorkflowRunMode;
   startedAt: number;
   events: WorkflowEvent[];
   /** Settled state: undefined while running, true on workflow_done,
@@ -384,10 +389,51 @@ export async function handleWorkflowRunStart(
   // so the PWA "▶ Run now" button runs the dependent chain straight
   // through. Default false preserves the production wire.
   const dryRun: boolean = Boolean(body && typeof body === 'object' && (body as { dryRun?: unknown }).dryRun === true);
+  const input = body && typeof body === 'object' ? body as Record<string, unknown> : {};
+  const { onlyNode, fromNode, fromRunId } = input;
+  if ('usePins' in input || (onlyNode !== undefined && (fromNode !== undefined || fromRunId !== undefined))
+    || (onlyNode !== undefined && (typeof onlyNode !== 'string' || !onlyNode.trim()))
+    || (fromNode !== undefined && (typeof fromNode !== 'string' || !fromNode.trim()))
+    || (fromRunId !== undefined && (typeof fromRunId !== 'string' || !fromRunId.trim()))
+    || (fromNode === undefined) !== (fromRunId === undefined)
+    || (input.mode !== undefined && input.mode !== 'test')) {
+    return jsonResponse({ error: 'bad_request', reason: 'invalid run selection' }, 400);
+  }
+  if ((onlyNode && !entry.definition.nodes.some(n => n.id === onlyNode))
+    || (fromNode && !entry.definition.nodes.some(n => n.id === fromNode))) {
+    return jsonResponse({ error: 'bad_request', reason: 'unknown selected node' }, 400);
+  }
+  let previousOutputs: Record<string, NodeOutput> | undefined;
+  if (typeof fromRunId === 'string') {
+    const previous = RUN_REGISTRY.get(fromRunId);
+    if (previous) {
+      if (previous.workflowName !== name || previous.ok === undefined) {
+        return jsonResponse({ error: 'bad_request', reason: 'source run must be settled for this workflow' }, 400);
+      }
+      const terminal = previous.events.find(e => e.type === 'workflow_done' || e.type === 'workflow_failed');
+      previousOutputs = terminal?.type === 'workflow_done' ? terminal.outputs
+        : terminal?.type === 'workflow_failed' ? terminal.partial : {};
+    } else {
+      const disk = readRunOutputSnapshot(fromRunId);
+      if (!disk || disk.workflowName !== name || (disk.status !== 'done' && disk.status !== 'failed')) {
+        return jsonResponse({ error: 'bad_request', reason: 'source run must be settled for this workflow' }, 400);
+      }
+      previousOutputs = disk.outputs;
+    }
+    let order: string[];
+    try { order = topoSort(entry.definition.nodes); }
+    catch { return jsonResponse({ error: 'bad_request', reason: 'invalid workflow topology' }, 400); }
+    const upstream = order.slice(0, order.indexOf(fromNode as string));
+    if (upstream.some(id => previousOutputs?.[id] === undefined)) {
+      return jsonResponse({ error: 'bad_request', reason: 'source run missing upstream outputs' }, 400);
+    }
+  }
+  const mode: WorkflowRunMode = input.mode === 'test' ? 'test' : onlyNode ? 'only' : fromNode ? 'from' : 'full';
   const runId = `wf-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   const record: RunRecord = {
     runId,
     workflowName: name,
+    mode,
     startedAt: Date.now(),
     events: [],
     ok: undefined,
@@ -400,10 +446,14 @@ export async function handleWorkflowRunStart(
   void (async () => {
     const deps = buildDefaultWorkflowDeps({ runId });
     try {
-      for await (const evt of runWorkflow(
-        { workflow: entry.definition, arguments: args, runId, dryRun },
-        deps,
-      )) {
+      const runOpts: RunWorkflowOpts = {
+        workflow: entry.definition, arguments: args, runId, dryRun, mode,
+        ...(typeof onlyNode === 'string' ? { onlyNode } : {}),
+        ...(typeof fromNode === 'string' ? { fromNode } : {}),
+        ...(previousOutputs ? { previousOutputs } : {}),
+      };
+      for await (const runtimeEvent of runWorkflow(runOpts, deps)) {
+        const evt = { ...runtimeEvent, mode };
         record.events.push(evt);
         // §15.8(b) — fan into NexusEventBus → PWA invalidates queries
         // on push instead of polling. No-op when bus is unwired
@@ -423,13 +473,14 @@ export async function handleWorkflowRunStart(
         type: 'workflow_failed' as const,
         error: err instanceof Error ? err.message : String(err),
         partial: {},
+        mode,
       };
       record.events.push(failEvt);
       publishWorkflowRunEvent({ runId, workflowName: name }, failEvt);
     }
   })();
 
-  return jsonResponse({ ok: true, runId }, 202);
+  return jsonResponse({ ok: true, runId, mode }, 202);
 }
 
 export function handleWorkflowRunGet(
@@ -444,6 +495,7 @@ export function handleWorkflowRunGet(
       {
         runId: rec.runId,
         workflowName: rec.workflowName,
+        mode: rec.mode,
         startedAt: rec.startedAt,
         ok: rec.ok,
         events: rec.events,
@@ -597,6 +649,21 @@ interface DiskRunSummary {
  *  enough that abandoned runs don't pollute the list across sessions. */
 const STALE_RUNNING_AFTER_MS = 30 * 60 * 1000;
 
+function readRunOutputSnapshot(runId: string): {
+  workflowName: string;
+  status: string;
+  outputs: Record<string, NodeOutput>;
+} | null {
+  if (!/^wf-[A-Za-z0-9-]+$/.test(runId) || runId.includes('..')) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(join(workflowsRunsRoot(), runId, 'run.json'), 'utf-8')) as {
+      workflowName?: string; status?: string; outputs?: Record<string, NodeOutput>;
+    };
+    if (!parsed.workflowName || !parsed.status || !parsed.outputs || typeof parsed.outputs !== 'object') return null;
+    return { workflowName: parsed.workflowName, status: parsed.status, outputs: parsed.outputs };
+  } catch { return null; }
+}
+
 /** Read `<root>/<runId>/run.json` and translate into the same shape as
  *  GET /runs/<id> serves from memory. Returns null when the file is
  *  missing or unreadable. Events are reconstructed minimally from the
@@ -608,6 +675,7 @@ function loadRunFromDisk(runId: string): {
   ok: boolean | undefined;
   events: WorkflowEvent[];
   outputs: Record<string, unknown>;
+  mode?: WorkflowRunMode;
 } | null {
   if (!runId || runId.includes('/') || runId.includes('..')) return null;
   const root = workflowsRunsRoot();
@@ -623,6 +691,7 @@ function loadRunFromDisk(runId: string): {
       completedAt?: number;
       ok?: boolean;
       status?: string;
+      mode?: WorkflowRunMode;
       outputs?: Record<string, { output?: unknown }>;
     };
     if (!parsed.runId || !parsed.workflowName) return null;
@@ -634,7 +703,8 @@ function loadRunFromDisk(runId: string): {
     // so a polling client still sees the node_done sequence even
     // though the live run.json doesn't store events.
     const events: WorkflowEvent[] = [];
-    events.push({ type: 'workflow_start', workflow: parsed.workflowName, runId: parsed.runId });
+    events.push({ type: 'workflow_start', workflow: parsed.workflowName, runId: parsed.runId,
+      ...(parsed.mode !== undefined ? { mode: parsed.mode } : {}) });
     const nodesDir = join(runDir, 'nodes');
     // Iterate `parsed.outputs` keys instead of `readdirSync(nodesDir)`
     // so the reconstructed node_done sequence is in execution order
@@ -673,6 +743,7 @@ function loadRunFromDisk(runId: string): {
       events.push({
         type: 'node_done',
         nodeId,
+        ...(parsed.mode !== undefined ? { mode: parsed.mode } : {}),
         result: {
           ok: nodeData.ok,
           output: nodeData.output ?? '',
@@ -684,6 +755,7 @@ function loadRunFromDisk(runId: string): {
     if (parsed.status === 'done') {
       events.push({
         type: 'workflow_done',
+        ...(parsed.mode !== undefined ? { mode: parsed.mode } : {}),
         outputs: Object.fromEntries(
           Object.entries(parsed.outputs ?? {}).map(([k, v]) => [
             k,
@@ -694,6 +766,7 @@ function loadRunFromDisk(runId: string): {
     } else if (parsed.status === 'failed') {
       events.push({
         type: 'workflow_failed',
+        ...(parsed.mode !== undefined ? { mode: parsed.mode } : {}),
         error: 'failed (see node events)',
         partial: Object.fromEntries(
           Object.entries(parsed.outputs ?? {}).map(([k, v]) => [
@@ -706,6 +779,7 @@ function loadRunFromDisk(runId: string): {
     return {
       runId: parsed.runId,
       workflowName: parsed.workflowName,
+      ...(parsed.mode !== undefined ? { mode: parsed.mode } : {}),
       startedAt: parsed.startedAt ?? 0,
       ok: parsed.status === 'done' ? true : parsed.status === 'failed' ? false : undefined,
       events,