elanous 0.2.0 → 0.2.5

package/src/nexus/api/setup-obsidian-skills.ts

@@ -0,0 +1,93 @@
+import { statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { SKILL_PRESETS } from '../../onboarding.js';
+import { debug } from '../../debug/log.js';
+import { resolveObsidianRoot } from '../../acp/fs-roots.js';
+import { getUserConfig, saveUserConfig, type SkillSetName } from '../../user-config.js';
+
+export interface ObsidianSkillsState {
+  obsidian: { vault: string; exists: boolean; looksLikeVault: boolean };
+  skills: {
+    activeSet: SkillSetName;
+    dirs: string[];
+    presets: Array<{ key: SkillSetName; label: string; dir: string | null; exists: boolean }>;
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: {
+    'content-type': 'application/json; charset=utf-8',
+    'access-control-allow-origin': '*',
+  } });
+}
+
+function directoryExists(dir: string): boolean {
+  try { return statSync(dir).isDirectory(); } catch { return false; }
+}
+
+function pathError(dir: unknown): string | null {
+  if (typeof dir !== 'string' || !isAbsolute(dir)) return 'absolute-directory-path-required';
+  if (!directoryExists(dir)) return 'directory-does-not-exist';
+  return null;
+}
+
+async function parseBody(req: Request): Promise<Record<string, unknown> | null> {
+  try {
+    const value: unknown = await req.json();
+    return value && typeof value === 'object' && !Array.isArray(value)
+      ? value as Record<string, unknown> : null;
+  } catch { return null; }
+}
+
+/** GET /v1/setup/obsidian-skills */
+export function handleObsidianSkillsGet(): Response {
+  const cfg = getUserConfig();
+  const vault = cfg.obsidian.vault;
+  const state: ObsidianSkillsState = {
+    obsidian: { vault, exists: directoryExists(vault), looksLikeVault: directoryExists(vault) && directoryExists(join(vault, '.obsidian')) },
+    skills: {
+      activeSet: cfg.skills.activeSet,
+      dirs: cfg.skills.dirs,
+      presets: SKILL_PRESETS.map(({ key, label, dir }) => ({ key, label, dir, exists: dir !== null && directoryExists(dir) })),
+    },
+  };
+  return json(state);
+}
+
+/** POST /v1/setup/obsidian */
+export async function handleObsidianSet(req: Request): Promise<Response> {
+  const body = await parseBody(req);
+  if (!body) return json({ error: 'invalid-json' }, 400);
+  const error = pathError(body.vault);
+  if (error) return json({ error, reason: 'vault must be an existing absolute directory' }, 400);
+  const vault = body.vault as string;
+  const warning = directoryExists(join(vault, '.obsidian')) ? undefined : 'No .obsidian directory found in this vault.';
+  const cfg = getUserConfig();
+  saveUserConfig({ ...cfg, obsidian: { ...cfg.obsidian, vault } });
+  // 볼트 해석은 프로세스에 캐시된다 — 다시 풀지 않으면 도는 데몬이 재시작 전까지 «옛 볼트»에 읽고 쓴다(🅞 2026-09-26 격리 데몬 실측).
+  const now = resolveObsidianRoot({ forceRefresh: true });
+  debug.log('pwa.settings', 'obsidian-set', { vault, resolvedRoot: now.root, source: now.source });
+  return json({ ok: true, obsidian: { vault }, ...(warning ? { warning } : {}) });
+}
+
+/** POST /v1/setup/skills — either one preset or explicitly selected directories. */
+export async function handleSkillsSet(req: Request): Promise<Response> {
+  const body = await parseBody(req);
+  if (!body) return json({ error: 'invalid-json' }, 400);
+  const preset = typeof body.activeSet === 'string' && !('dirs' in body)
+    ? SKILL_PRESETS.find((item) => item.key === body.activeSet)
+    : undefined;
+  if (!preset && (!Array.isArray(body.dirs) || 'activeSet' in body)) {
+    return json({ error: 'invalid-skills-selection', reason: 'choose a known activeSet or a dirs array' }, 400);
+  }
+  const dirs: string[] = preset ? (preset.dir ? [preset.dir] : []) : body.dirs as string[];
+  for (const dir of dirs) {
+    const error = pathError(dir);
+    if (error) return json({ error, reason: 'each skill path must be an existing absolute directory', path: dir }, 400);
+  }
+  const cfg = getUserConfig();
+  const skills = { ...cfg.skills, activeSet: preset?.key ?? 'custom' as SkillSetName, dirs };
+  saveUserConfig({ ...cfg, skills });
+  debug.log('pwa.settings', 'skills-set', { dirs });
+  return json({ ok: true, skills: { activeSet: skills.activeSet, dirs: skills.dirs } });
+}

package/src/nexus/api/task-cards-api.ts

@@ -0,0 +1,34 @@
+import { CardStore } from '../../task-cards/card-store.js';
+import { jsonResponse } from './json-response.js';
+
+/** Read-only card API; route registration and authorization belong to the HTTP server. */
+export function handleTaskCardsGet(pathname: string, root?: string): Response {
+  if (pathname !== '/v1/task-cards' && !/^\/v1\/task-cards\/[^/]+$/.test(pathname)) {
+    return jsonResponse({ error: 'not_found' }, 404);
+  }
+
+  if (pathname === '/v1/task-cards') {
+    const store = new CardStore(root);
+    try {
+      return jsonResponse({ cards: store.listCards() });
+    } finally {
+      store.close();
+    }
+  }
+
+  let id: string;
+  try {
+    id = decodeURIComponent(pathname.slice('/v1/task-cards/'.length));
+  } catch {
+    return jsonResponse({ error: 'not_found' }, 404);
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) return jsonResponse({ error: 'not_found' }, 404);
+
+  const store = new CardStore(root);
+  try {
+    const card = store.getCard(id);
+    return card ? jsonResponse({ card }) : jsonResponse({ error: 'not_found' }, 404);
+  } finally {
+    store.close();
+  }
+}

package/src/nexus/api/tasks-create.ts

@@ -0,0 +1,136 @@
+import { randomUUID } from 'node:crypto';
+import { debug } from '../../debug/log.js';
+import { dispatchTaskCreate } from '../../task-orchestrator/runtimes/create.js';
+import { getToxRuntimeDeps } from '../../task-orchestrator/runtime-deps.js';
+import { TaskStore } from '../../task-orchestrator/store.js';
+import { isExternalProvider } from '../../task-orchestrator/external-policy.js';
+import { externalTaskFingerprint } from '../../task-orchestrator/external-fingerprint.js';
+import { isTaskSurface, TASK_DEFAULTS, type TaskPriority } from '../../task-orchestrator/types.js';
+import { jsonResponse } from './http-server.js';
+import { checkAuth, type MetaApiOpts } from './meta-api.js';
+import { matchIngestAuthorization } from './ingest-token.js';
+
+function trace(req: Request): string {
+  return req.headers.get('x-elanous-trace-id')?.trim() || randomUUID();
+}
+
+function badRequest(reason: string, traceId: string): Response {
+  debug.log('tox.external', 'rejected', { traceId, reason });
+  return jsonResponse({ error: 'bad_request', reason }, 400);
+}
+
+export async function handleTaskCreatePost(req: Request, opts: MetaApiOpts): Promise<Response> {
+  if (!checkAuth(req, opts)
+    && !(req.method === 'POST' && new URL(req.url).pathname === '/v1/tasks' && matchIngestAuthorization(req) !== null)) {
+    return jsonResponse({ error: 'unauthorized' }, 401);
+  }
+  const traceId = trace(req);
+  let raw: unknown;
+  try { raw = await req.json(); }
+  catch { return badRequest('invalid JSON body', traceId); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return badRequest('body must be an object', traceId);
+  const body = raw as Record<string, unknown>;
+  if (typeof body.title !== 'string' || !body.title.trim() || body.title.length > TASK_DEFAULTS.titleMaxLen) {
+    return badRequest(`title must be a non-empty string of at most ${TASK_DEFAULTS.titleMaxLen} chars`, traceId);
+  }
+  if (body.description !== undefined && (typeof body.description !== 'string' || body.description.length > TASK_DEFAULTS.descriptionMaxLen)) {
+    return badRequest(`description must be a string of at most ${TASK_DEFAULTS.descriptionMaxLen} chars`, traceId);
+  }
+  if (body.priority !== undefined && !['low', 'medium', 'high', 'urgent'].includes(body.priority as string)) {
+    return badRequest('priority must be low | medium | high | urgent', traceId);
+  }
+  if (body.priority === 'urgent') return badRequest('urgent requires acceptance checks or criteria', traceId);
+  if (body.eventId !== undefined && typeof body.eventId !== 'string') return badRequest('eventId must be a string', traceId);
+  // This entrance is the external one (RFC A2 · 🅢 M1·S2): everything that comes in here
+  // is someone else's input and waits for approval. Owner-made tasks use TaskCreate in-process.
+  if (body.external === undefined) return badRequest('external is required on this entrance', traceId);
+  let external: Parameters<typeof dispatchTaskCreate>[0]['external'];
+  if (body.external !== undefined) {
+    if (!body.external || typeof body.external !== 'object' || Array.isArray(body.external)) return badRequest('external must be an object', traceId);
+    const value = body.external as Record<string, unknown>;
+    if (!isExternalProvider(value.provider)) return badRequest('external.provider is invalid', traceId);
+    if (typeof value.ref !== 'string' || !value.ref.trim()) return badRequest('external.ref is required', traceId);
+    for (const field of ['url', 'project', 'team', 'assignee']) {
+      if (value[field] !== undefined && typeof value[field] !== 'string') return badRequest(`external.${field} must be a string`, traceId);
+    }
+    external = {
+      provider: value.provider,
+      ref: value.ref,
+      ...(typeof value.url === 'string' ? { url: value.url } : {}),
+      ...(typeof value.project === 'string' ? { project: value.project } : {}),
+      ...(typeof value.team === 'string' ? { team: value.team } : {}),
+      ...(typeof value.assignee === 'string' ? { assignee: value.assignee } : {}),
+    };
+  }
+  if (body.surface !== undefined && !isTaskSurface(body.surface)) return badRequest('surface must be a valid TaskSurface', traceId);
+  if (external && body.surface !== undefined) {
+    const requestedSurface = body.surface as Record<string, unknown>;
+    if (requestedSurface.kind !== 'llm-direct') return badRequest('external tasks require llm-direct surface', traceId);
+    if (requestedSurface.model !== undefined || requestedSurface.systemPrompt !== undefined) {
+      return badRequest('external tasks cannot set model or systemPrompt', traceId);
+    }
+  }
+  const surface = body.surface ?? { kind: 'llm-direct', prompt: `${body.title}${body.description ? `\n${body.description}` : ''}` };
+  try {
+    const result = await dispatchTaskCreate({
+      title: body.title,
+      ...(typeof body.description === 'string' ? { description: body.description } : {}),
+      priority: body.priority as TaskPriority | undefined,
+      surface,
+      external,
+      externalSurfaceDefaulted: body.surface === undefined,
+      traceId,
+      ...(typeof body.eventId === 'string' ? { eventId: body.eventId } : {}),
+    });
+    if (!result.taskId) {
+      if (result.output.startsWith('TaskCreate:')) return badRequest(result.output, traceId);
+      return jsonResponse({ error: 'task_create_failed', reason: result.output }, 503);
+    }
+    return jsonResponse({ taskId: result.taskId, deduplicated: result.deduplicated ?? false }, result.deduplicated ? 200 : 201);
+  } catch (err) {
+    return badRequest(err instanceof Error ? err.message : String(err), traceId);
+  }
+}
+
+export function handleTaskApprovePost(req: Request, taskId: string, opts: MetaApiOpts): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  const traceId = trace(req);
+  const graph = getToxRuntimeDeps().getGraph();
+  if (!graph) return jsonResponse({ error: 'tox-not-initialized' }, 503);
+  const store = getToxRuntimeDeps().getStore?.() as TaskStore | null | undefined;
+  let ownedStore: TaskStore | null = null;
+  try {
+    ownedStore = store ? null : new TaskStore();
+    const db = (store ?? ownedStore)!;
+    const task = graph.getTask(taskId) ?? db.getTask(taskId);
+    if (!task) return jsonResponse({ error: 'not_found' }, 404);
+    if (task.generatedBy?.kind !== 'external' || task.status !== 'backlog' || task.approval?.state !== 'pending') {
+      debug.log('tox.external', 'rejected', { traceId, taskId, reason: 'not_pending_approval', provider: task.generatedBy?.kind === 'external' ? task.generatedBy.provider : undefined, ref: task.generatedBy?.kind === 'external' ? task.generatedBy.ref : undefined, approval: task.approval });
+      return jsonResponse({ error: 'conflict', reason: 'task is not pending external approval' }, 409);
+    }
+    const now = Date.now();
+    const updated = { ...task, status: 'ready' as const,
+      approval: { state: 'approved' as const, approvedBy: 'manual' as const, approvedAt: now,
+        fingerprint: externalTaskFingerprint(task) }, updatedAt: now };
+    const graphPrevious = graph.getTask(taskId);
+    let changedTask: typeof task | undefined;
+    try {
+      db.transaction(() => {
+        db.saveTask(updated);
+        if (graphPrevious) changedTask = graph.updateTask(taskId, { status: updated.status, approval: updated.approval });
+        else { graph.addTask(updated); changedTask = updated; }
+      });
+    } catch (err) {
+      if (graph.getTask(taskId) !== graphPrevious
+        && (!changedTask || graph.getTask(taskId) === changedTask)) graph.restoreTask(taskId, graphPrevious);
+      throw err;
+    }
+    debug.log('tox.external', 'approved', { traceId, provider: task.generatedBy.provider, ref: task.generatedBy.ref, taskId, approval: updated.approval });
+    return jsonResponse({ taskId, status: updated.status, approval: updated.approval }, 200);
+  } catch (err) {
+    debug.log('tox.external', 'rejected', { traceId, taskId, reason: err instanceof Error ? err.message : String(err) });
+    return jsonResponse({ error: 'approval_failed' }, 503);
+  } finally {
+    ownedStore?.close();
+  }
+}

package/src/nexus/api/telegram-trigger-bot.ts

@@ -16,7 +16,7 @@
 //
 // Distinct from HITL Telegram bot (`hitl-telegram-channel.ts`):
 //   • HITL bot    = ELANOUS_TELEGRAM_HITL_BOT_TOKEN · interaction-only
-//   • Trigger bot = cfg.telegram.botToken          · message tap
+//   • Trigger bot = resolved channel token        · message tap
 // Production typically uses two separate Telegram bots so the
 // allowlists / chat scopes don't bleed.
 
@@ -39,8 +39,7 @@ import { formatTablesAndRules } from '../../discord-markdown.js';
 
 export interface NexusTelegramTriggerBotOpts {
   /** Bot token (without `Bot ` prefix). Production reads
-   *  `cfg.telegram.botToken` (env-bridge populates from
-   *  `ELANOUS_TELEGRAM_BOT_TOKEN` when set). */
+   *  the channel token resolved by the NEXUS caller. */
   token: string;
   /** Allowlist of Telegram user ids — empty array refuses everyone
    *  (see `src/telegram.ts` allowedUsers gate). */
@@ -174,6 +173,7 @@ export function createNexusTelegramTriggerBot(
         log,
         ...(opts.runTurnImpl ? { runTurnImpl: opts.runTurnImpl } : {}),
         telegramBotOpts: {
+          token: opts.token,
           onTriggerTap,
           ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
         },

package/src/nexus/api/terminals.ts

@@ -21,7 +21,7 @@
 
 import { jsonResponse } from './http-server.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
-import { getPty, listPty, type PtyHandle } from '../../pty-shell/registry.js';
+import { getPty, listPty, onPtyEvent, type PtyEvent, type PtyHandle } from '../../pty-shell/registry.js';
 import { listAllPreviewTerminals } from '../../web-terminal/preview-tap-registry.js';
 import { debug } from '../../debug/log.js';
 export { terminalTreeLabel, terminalTreeNames } from '../../pty-shell/terminal-tree.js';
@@ -33,6 +33,7 @@ import { readPtyEventsAfter } from '../../pty-shell/pty-event-log.js';
 import { classifyPtyOwnerRunUsage, joinPtyLineage, resolveRunTermination, type PtyOwnerRunUsage, type RunTermination } from '../../cli/pty-takeover-cli.js';
 import { loadRunLedger, resolveFederatedRunLedgerDirectories, runLedgerDir } from '../../self-implement/run-ledger.js';
 import { requestRemotePtyControl, type PtyControlAction, type PtyControlPayload, type PtyControlRequestOptions, type PtyControlResult } from '../../pty-shell/pty-control-ipc.js';
+import { encodeSgrMouse, type PtyMouseInput } from '../../pty-shell/pty-mouse.js';
 import { queryRunningRuns, type RunningRunAssessment, type RunningRunPresence, type RunningRunStatus, type RunningRunsResult } from '../../self-implement/running-runs.js';
 // ⭐P4 §4-1 — 표시 폭(wide-char/CJK/emoji 인지) SSOT. PNG 캔버스 cols 파생용.
 import { cellWidth } from '../../ui/printer.js';
@@ -457,6 +458,8 @@ interface TerminalsListDeps extends TerminalManifestScopeDeps {
   /** 원격 logs.db 는 읽기 전용으로만 열어 연합한다. */
   openLogStoreReadOnly?(dbPath: string): Pick<LogStore, 'query' | 'close'>;
   queryRunningRuns?(options: { includeTest?: boolean }): RunningRunsResult;
+  /** Clock for the running-runs cache. Tests advance this instead of waiting out the TTL. */
+  now?(): number;
   runTerminated?(runId: string, options: { includeTest: boolean }): RunTermination;
 }
 
@@ -464,6 +467,33 @@ const SUB_AGENT_COUNT_WINDOW_MS = 24 * 60 * 60 * 1_000;
 const TERMINALS_SCOPE_DOMAIN = '이 표면의 terminals 목록은 실체 PTY만 봅니다. 로그에서 수집한 PTY 없는 Agent 서브 에이전트는 subjects와 scope 집계에만 반영됩니다.';
 const TERMINALS_SCOPE_SUB_AGENT_COUNT = '최근 24시간 현재 범위의 로그 스토어에서 센 PTY 없이 실행된 서브 에이전트';
 
+/**
+ * Process-wide single-flight cache. Two GET /v1/terminals calls with the same
+ * includeTest inside the TTL share one queryRunningRuns result. A different
+ * injector (tests) gets its own cache so one suite cannot poison another.
+ */
+interface RunningRunsCacheBinding {
+  cache: (options: { includeTest?: boolean }) => CachedRunningRuns;
+  now: () => number;
+}
+
+const runningRunsCaches = new WeakMap<object, RunningRunsCacheBinding>();
+
+function runningRunsCacheFor(
+  injector: (options: { includeTest?: boolean }) => RunningRunsResult,
+  now: () => number,
+): (options: { includeTest?: boolean }) => CachedRunningRuns {
+  const existing = runningRunsCaches.get(injector);
+  if (existing) {
+    existing.now = now;
+    return existing.cache;
+  }
+  const binding: RunningRunsCacheBinding = { cache: () => { throw new Error('uninitialized'); }, now };
+  binding.cache = createRunningRunsCache({ now: () => binding.now(), queryRunningRuns: injector });
+  runningRunsCaches.set(injector, binding);
+  return binding.cache;
+}
+
 const liveTerminalsListDeps: TerminalsListDeps = {
   ptyManifestTargets,
   listPtyManifestRows,
@@ -566,6 +596,67 @@ export type SubjectRunningRunsSummary = Pick<Record<RunningRunStatus, number>, '
   countedStatuses: readonly ['running', 'probable-running'];
 };
 
+/** Short TTL so a polling terminal list does not re-read every ledger on every request. */
+export const RUNNING_RUNS_CACHE_TTL_MS = 15_000;
+
+export interface CachedRunningRuns {
+  readonly result: RunningRunsResult;
+  /** Milliseconds since this result was computed. 0 on a fresh computation. */
+  readonly ageMs: number;
+}
+
+export interface RunningRunsCacheDeps {
+  now(): number;
+  queryRunningRuns(options: { includeTest?: boolean; caller?: string }): RunningRunsResult;
+}
+
+/**
+ * One computation at a time per includeTest.
+ *
+ * The list handler is synchronous, so two requests overlap only when the
+ * second enters while the injector is still on the stack. That re-entrant
+ * call shares the in-flight result and does not call the injector again.
+ * A later call inside the TTL returns the stored result and its age.
+ * A failed computation is not stored. Which runs are running is unchanged.
+ */
+export function createRunningRunsCache(
+  deps: RunningRunsCacheDeps,
+  ttlMs: number = RUNNING_RUNS_CACHE_TTL_MS,
+): (options: { includeTest?: boolean }) => CachedRunningRuns {
+  const slots = new Map<boolean, { at: number; result: RunningRunsResult }>();
+  const flights = new Set<boolean>();
+  return (options) => {
+    const includeTest = options.includeTest === true;
+    const now = deps.now();
+    const cached = slots.get(includeTest);
+    if (flights.has(includeTest)) {
+      // Same includeTest is already on this stack. Return the one result
+      // the owner publishes into the slot; never call the injector again.
+      if (cached) return { result: cached.result, ageMs: 0 };
+      const shared = {} as RunningRunsResult;
+      slots.set(includeTest, { at: now, result: shared });
+      return { result: shared, ageMs: 0 };
+    }
+    if (cached && now - cached.at < ttlMs) {
+      return { result: cached.result, ageMs: now - cached.at };
+    }
+    flights.add(includeTest);
+    try {
+      const computed = deps.queryRunningRuns({ includeTest, caller: 'nexus.terminals' });
+      const slot = slots.get(includeTest);
+      const result = slot?.result ?? computed;
+      if (slot) Object.assign(slot.result, computed);
+      else slots.set(includeTest, { at: now, result });
+      return { result, ageMs: 0 };
+    } catch (error) {
+      slots.delete(includeTest);
+      throw error;
+    } finally {
+      flights.delete(includeTest);
+    }
+  };
+}
+
 export function summarizeSubjectRunningRuns(subjects: readonly SubjectSummary[]): SubjectRunningRunsSummary {
   const counts: SubjectRunningRunsSummary = { running: 0, 'probable-running': 0, countedStatuses: ['running', 'probable-running'] };
   for (const subject of subjects) {
@@ -805,20 +896,14 @@ function terminalKey(terminal: Pick<TerminalSummary, 'id' | 'sourceRoot'>): stri
   return `${terminal.sourceRoot?.dbPath ?? ptyManifestDbPath()}\u0000${terminal.id}`;
 }
 
-function webTerminalKey(sessionId: string, terminalId: string): string {
-  return `${sessionId}\u0000${terminalId}`;
-}
-
 function mergeWebPreviewTerminals(ptyTerminals: TerminalSummary[]): TerminalSummary[] {
+  // Registry enumeration is shell-unique even when multiple ACP sessions
+  // have output taps on the same PreviewTerminal.
   const webTerminals = listAllPreviewTerminals();
   const liveWebTerminals = webTerminals.filter((terminal) => terminal.isAlive);
-  const seenWebTerminals = new Set<string>();
   const merged = [...ptyTerminals];
   let added = 0;
   for (const terminal of liveWebTerminals) {
-    const key = webTerminalKey(terminal.sessionId, terminal.terminalId);
-    if (seenWebTerminals.has(key)) continue;
-    seenWebTerminals.add(key);
     merged.push({
       id: terminal.terminalId,
       cmd: 'web-terminal',
@@ -969,8 +1054,18 @@ export function handleTerminalsList(req: Request, opts: MetaApiOpts, deps: Termi
   const resolveRunTerminationForRow = (runId: string): RunTermination => deps.runTerminated
     ? deps.runTerminated(runId, { includeTest })
     : 'ledger-indeterminate';
+  const runningRunsCache = runningRunsCacheFor(getRunningRuns, deps.now ?? Date.now);
   let runningRuns: RunningRunsResult | null = null;
-  try { runningRuns = getRunningRuns({ includeTest }); } catch { /* fail-soft: preserve terminal inspection */ }
+  let runningRunsAgeMs = 0;
+  let runningRunsQueryFailed = false;
+  try {
+    const cached = runningRunsCache({ includeTest });
+    runningRuns = cached.result;
+    runningRunsAgeMs = cached.ageMs;
+  } catch {
+    // Fail-soft and do not cache: subjects keep unknown assessments.
+    runningRunsQueryFailed = true;
+  }
   const ptyLessSubAgentCollection = collectPtyLessSubAgents(
     getLogStore,
     federated,
@@ -1013,7 +1108,7 @@ export function handleTerminalsList(req: Request, opts: MetaApiOpts, deps: Termi
     // 웹 터미널은 목록에만 합치며, 동명 ID가 PTY 가시성·scope 집계를 바꾸면 안 된다.
     const visibleIds = new Set(ptyTerminals.map((terminal) => terminal.id));
     const hiddenDead = manifestBeforeCleanup.filter((row) => !visibleIds.has(row.id)).length;
-    return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), scope: terminalsScope(1, false, hiddenDead, hiddenSubAgentRuns) }, 200);
+    return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), runningRunsAgeMs: runningRunsQueryFailed ? null : runningRunsAgeMs, scope: terminalsScope(1, false, hiddenDead, hiddenSubAgentRuns) }, 200);
   }
 
   const { currentDbPath, targets } = scope;
@@ -1044,7 +1139,7 @@ export function handleTerminalsList(req: Request, opts: MetaApiOpts, deps: Termi
   // log-derived agent summaries continue to feed subjects and scope independently.
   const terminals = mergeWebPreviewTerminals(ptyTerminals);
   const subjects = enrichSubjectRunAssessments(deriveSubjectSummaries(ptyTerminals, ptyLessSubAgents), runningRuns);
-  return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), scope: terminalsScope(targets.length, true, hiddenDead, hiddenSubAgentRuns) }, 200);
+  return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), runningRunsAgeMs: runningRunsQueryFailed ? null : runningRunsAgeMs, scope: terminalsScope(targets.length, true, hiddenDead, hiddenSubAgentRuns) }, 200);
 }
 
 export interface TerminalPruneDeps extends TerminalManifestScopeDeps {
@@ -1207,6 +1302,85 @@ export function parseTerminalRenamePath(pathname: string): string | null {
   return m && m[1] ? safeDecodeSegment(m[1]) : null;
 }
 
+/** Path matcher: `/v1/terminals/:id/stream`. */
+export function parseTerminalStreamPath(pathname: string): string | null {
+  const m = /^\/v1\/terminals\/([^/]+)\/stream$/.exec(pathname);
+  return m && m[1] ? safeDecodeSegment(m[1]) : null;
+}
+
+export interface TerminalStreamDeps {
+  getPty?: (id: string) => Pick<PtyHandle, 'renderScreen'> | undefined;
+  onPtyEvent?: (cb: (ev: PtyEvent) => void) => () => void;
+  requestRemotePtyControl?: TerminalControlDeps['requestRemotePtyControl'];
+  isAllowedSourceRoot?: (dbPath: string) => boolean;
+  /** 남의 PTY 화면을 다시 묻는 간격(ms). */
+  pollMs?: number;
+  /** 바이트 묶음 간격(ms). */
+  flushMs?: number;
+}
+
+/** GET /v1/terminals/:id/stream — PWA 웹 터미널 실시간(드라이브 RFC ⑥ · 800ms 폴링 대체 · SSE).
+ *  - 이 데몬이 가진 PTY: 처음 `reset`(현재 화면) → `onPtyEvent` 출력 바이트를 `data` 로 흘린다(flushMs 로 묶음) · 끝나면 `end`.
+ *  - 남의 PTY(다른 프로세스·연합 뿌리): 서버 쪽에서 pollMs 마다 스냅숏 → 화면이 «바뀐 때만» `screen`.
+ *    ⛔ 교차 프로세스 바이트 버스는 아직 없다 — owner 의 제어 처리기가 직렬이라 pollMs 는 150ms 아래로 내리지 않는다.
+ *  - 입력은 그대로 `POST /control`. 연결이 끊기면 구독·루프를 멈춘다(평소 부하 0). */
+export function handleTerminalStream(req: Request, opts: MetaApiOpts, id: string, deps: TerminalStreamDeps = {}): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!id) return jsonResponse({ error: 'missing-id' }, 400);
+  const sourceRoot = new URL(req.url).searchParams.get('sourceRoot');
+  if (sourceRoot !== null && !(deps.isAllowedSourceRoot ?? isAllowedSourceRoot)(sourceRoot)) return jsonResponse({ error: 'not-found', sourceRoot }, 404);
+  const local = sourceRoot === null ? (deps.getPty ?? getPty)(id) : undefined;
+  const pollMs = Math.max(150, deps.pollMs ?? 200);
+  const flushMs = deps.flushMs ?? 25;
+  const encoder = new TextEncoder();
+  let stop: () => void = () => {};
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      let closed = false;
+      const send = (event: string, data: unknown) => {
+        if (closed) return;
+        try { controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)); } catch { closed = true; }
+      };
+      const close = () => { if (closed) return; closed = true; try { controller.close(); } catch { /* already closed */ } };
+      const heartbeat = setInterval(() => { if (!closed) { try { controller.enqueue(encoder.encode(': hb\n\n')); } catch { closed = true; } } }, 15_000);
+      if (local) {
+        send('mode', { mode: 'bytes' });
+        let pending = '';
+        let timer: ReturnType<typeof setTimeout> | null = null;
+        const flush = () => { timer = null; if (pending) { send('data', pending); pending = ''; } };
+        void local.renderScreen({ ansi: true }).then((screen) => send('reset', { screen })).catch(() => send('reset', { screen: '' }));
+        const off = (deps.onPtyEvent ?? onPtyEvent)((ev) => {
+          if (ev.id !== id) return;
+          if (ev.type === 'output') { pending += ev.chunk; if (!timer) timer = setTimeout(flush, flushMs); }
+          else if (ev.type === 'exit' || ev.type === 'unregistered') { flush(); send('end', { reason: ev.type }); cleanup(); }
+        });
+        const cleanup = () => { off(); if (timer) clearTimeout(timer); clearInterval(heartbeat); close(); };
+        stop = cleanup;
+        return;
+      }
+      send('mode', { mode: 'screen', pollMs });
+      let last = '';
+      let loop: ReturnType<typeof setTimeout> | null = null;
+      const control = deps.requestRemotePtyControl ?? requestRemotePtyControl;
+      const tick = async () => {
+        if (closed) return;
+        try {
+          const r = await control(id, 'snapshot', { ansi: true }, { timeoutMs: TERMINAL_CONTROL_TIMEOUT_MS, ...(sourceRoot ? { manifestDbPath: sourceRoot } : {}) });
+          if (r.status === 'unknown-pty') { send('end', { reason: 'unknown-pty' }); cleanup(); return; }
+          if (r.status === 'success' && typeof r.screen === 'string' && r.screen !== last) { last = r.screen; send('screen', { screen: r.screen }); }
+          else if (r.status !== 'success') send('status', { status: r.status });
+        } catch { send('status', { status: 'control-failed' }); }
+        if (!closed) loop = setTimeout(() => { void tick(); }, pollMs);
+      };
+      const cleanup = () => { if (loop) clearTimeout(loop); clearInterval(heartbeat); close(); };
+      stop = cleanup;
+      void tick();
+    },
+    cancel() { stop(); },
+  });
+  return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive', 'x-accel-buffering': 'no' } });
+}
+
 /** Path matcher: `/v1/terminals/:id/terminate`. */
 export function parseTerminalTerminatePath(pathname: string): string | null {
   const m = /^\/v1\/terminals\/([^/]+)\/terminate$/.exec(pathname);
@@ -1215,6 +1389,7 @@ export function parseTerminalTerminatePath(pathname: string): string | null {
 
 interface TerminalControlDeps {
   requestRemotePtyControl(id: string, action: PtyControlAction, payload?: PtyControlPayload, options?: PtyControlRequestOptions): Promise<PtyControlResult>;
+  isAllowedSourceRoot?: (dbPath: string) => boolean;
 }
 
 const liveTerminalControlDeps: TerminalControlDeps = { requestRemotePtyControl };
@@ -1233,20 +1408,31 @@ export async function handleTerminalControl(
   if (!id) return jsonResponse({ error: 'missing-id' }, 400);
   let body: unknown;
   try { body = await req.json(); } catch { return jsonResponse({ error: 'invalid-json', reason: 'JSON body required' }, 400); }
-  const request = body !== null && typeof body === 'object' ? body as { action?: unknown; chars?: unknown; ansi?: unknown } : {};
+  const request = body !== null && typeof body === 'object' && !Array.isArray(body) ? body as { action?: unknown; chars?: unknown; ansi?: unknown; x?: unknown; y?: unknown; kind?: unknown; button?: unknown } : {};
   const action = request.action;
-  if (action !== 'takeover' && action !== 'release' && action !== 'input-text' && action !== 'input-key' && action !== 'snapshot') {
-    return jsonResponse({ error: 'invalid-action', reason: 'action must be takeover, release, input-text, input-key, or snapshot' }, 400);
+  if (action !== 'takeover' && action !== 'release' && action !== 'input-text' && action !== 'input-key' && action !== 'input-mouse' && action !== 'snapshot') {
+    return jsonResponse({ error: 'invalid-action', reason: 'action must be takeover, release, input-text, input-key, input-mouse, or snapshot' }, 400);
   }
   const isInput = action === 'input-text' || action === 'input-key';
   if (isInput && (typeof request.chars !== 'string' || request.chars.length === 0)) {
     return jsonResponse({ error: 'invalid-payload', reason: 'chars must be a non-empty string' }, 400);
   }
+  let mouse: PtyMouseInput | undefined;
+  if (action === 'input-mouse') {
+    if (typeof request.x !== 'number' || typeof request.y !== 'number' || (request.kind !== 'click' && request.kind !== 'scroll-up' && request.kind !== 'scroll-down') || (request.button !== undefined && request.button !== 'left' && request.button !== 'middle' && request.button !== 'right')) {
+      return jsonResponse({ error: 'invalid-payload', reason: 'mouse requires 1-based x,y, kind and optional button' }, 400);
+    }
+    mouse = { x: request.x, y: request.y, kind: request.kind, ...(request.button ? { button: request.button } : {}) };
+    try { encodeSgrMouse(mouse); } catch (error) { return jsonResponse({ error: 'invalid-payload', reason: (error as Error).message }, 400); }
+  }
   const payload = isInput ? { chars: request.chars as string }
-    : action === 'snapshot' && request.ansi === true ? { ansi: true }
-      : undefined;
+    : mouse ?? (action === 'snapshot' && request.ansi === true ? { ansi: true } : undefined);
+  // 연합 PTY(다른 매니페스트 뿌리)는 그 DB 에 요청을 남겨야 그 행의 owner 가 처리한다 — PWA 가 `?sourceRoot=` 를 보내는데
+  // 이 자리가 무시해 연합 PTY 제어·스냅숏이 `unknown-pty` 로 떨어졌다(09-28 탐색). frame 핸들러와 같은 규칙으로 받는다.
+  const sourceRoot = new URL(req.url).searchParams.get('sourceRoot');
+  if (sourceRoot !== null && !(deps.isAllowedSourceRoot ?? isAllowedSourceRoot)(sourceRoot)) return jsonResponse({ error: 'not-found', sourceRoot }, 404);
   try {
-    const result = await deps.requestRemotePtyControl(id, action, payload, { timeoutMs: TERMINAL_CONTROL_TIMEOUT_MS });
+    const result = await deps.requestRemotePtyControl(id, action, payload, { timeoutMs: TERMINAL_CONTROL_TIMEOUT_MS, ...(sourceRoot ? { manifestDbPath: sourceRoot } : {}) });
     const status = result.status === 'unknown-pty' ? 404
       : result.status === 'owner-unreachable' ? 504
       : result.status === 'failed' || result.status === 'write-failed' ? 502