elanous 0.2.34 → 0.2.36

package/src/cli/tasks-read-cli.ts

@@ -0,0 +1,197 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { readNexusRuntime } from '../nexus/runtime.js';
+import { TASK_CARD_PREFIX } from '../task-agent/task-card-prefix.js';
+import type { Task } from '../task-orchestrator/types.js';
+import type { TasksCliDeps } from './tasks-cli.js';
+
+/**
+ * CLI-ENTRY-LAZY — `tasks list`·`tasks show` 의 등록과 넥서스 조회 보조.
+ * ⛔ 이 파일은 task-agent 의 board·shadow·mission 클러스터(·dashboard)를 «정적으로» 싣지 않는다 — 가벼운 진입(`light-cli.ts`)이
+ * `tasks-cli.ts` 전체 대신 이것만 등록한다. 과제 카드(`ta-…`) 상세는 `tasks-card-show.ts` 를 그때 싣는다.
+ * 같은 등록 함수를 `tasks-cli.ts` 가 부르므로 전체 진입과 출력 계약이 한 코드다.
+ */
+
+type TaskRow = Pick<Task, 'id' | 'title' | 'priority' | 'status' | 'createdAt' | 'approval' | 'generatedBy'>;
+
+/** `tasks hand`·`show` 가 남기는 `task-agent` 관측의 logs.db surface 라벨. */
+export const TASK_AGENT_SINK_SURFACE = 'task-agent';
+
+/**
+ * 독립 CLI 프로세스는 데몬의 logs.db 싱크를 상속하지 않는다 — 등록하지 않으면 `debug.log('task-agent', …)` 가
+ * 파일 트레일에만 남고 `elanous logs --category task-agent` 에 0건으로 보인다(10-06 실측: 카드 3장 · 이벤트 0).
+ * fail-open — 등록 실패가 과제 넘기기를 막지 않는다.
+ */
+export async function registerTaskAgentSink(register?: (surface: string) => Promise<unknown>): Promise<void> {
+  try {
+    const fn = register ?? (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink;
+    await fn(TASK_AGENT_SINK_SURFACE);
+  } catch { /* fail-open — 파일 트레일이 진실원 */ }
+}
+
+const PRIORITY_RANK: Record<Task['priority'], number> = { urgent: 0, high: 1, medium: 2, low: 3 };
+export const NEXUS_DOWN = '넥서스가 안 떠 있다 — `elanous nexus run`';
+
+function taskOrder(a: TaskRow, b: TaskRow): number {
+  return PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority]
+    || a.createdAt - b.createdAt || a.id.localeCompare(b.id);
+}
+
+function taskSource(task: TaskRow): string {
+  return task.generatedBy?.kind === 'external'
+    ? `${task.generatedBy.provider}:${task.generatedBy.ref}` : '-';
+}
+
+function taskLine(task: TaskRow): string {
+  return [task.id, task.priority, task.status, task.approval?.state ?? '-', taskSource(task), task.title].join('\t');
+}
+
+export function credentials(deps: TasksCliDeps): { baseUrl: string; token?: string } | null {
+  const port = deps.baseUrl !== undefined ? undefined : readNexusRuntime()?.httpPort;
+  const baseUrl = deps.baseUrl ?? (port ? `http://127.0.0.1:${port}` : undefined);
+  if (!baseUrl) return null;
+  // Same as `connector linear sync`: an isolated (--test) universe has no acp-token and its
+  // daemon accepts loopback callers without one — send the bearer only when there is one.
+  let token = deps.bearerToken;
+  if (token === undefined) {
+    try { token = readFileSync(join(getElanousConfigDir(), 'acp-token'), 'utf8').trim() || undefined; }
+    catch { token = undefined; }
+  }
+  return { baseUrl, ...(token ? { token } : {}) };
+}
+
+export class NexusUnavailable extends Error {}
+
+export async function request(deps: TasksCliDeps, auth: { baseUrl: string; token?: string }, path: string, method = 'GET'): Promise<Response> {
+  try {
+    return await (deps.fetch ?? fetch)(`${auth.baseUrl}${path}`, {
+      method,
+      headers: auth.token ? { Authorization: `Bearer ${auth.token}` } : {},
+    });
+  } catch {
+    // Fetch exceptions can include the URL or credentials; never forward their text.
+    throw new NexusUnavailable();
+  }
+}
+
+export async function responseJson(response: Response): Promise<unknown> {
+  try { return await response.json(); }
+  catch { throw new Error('넥서스 응답 JSON이 유효하지 않다'); }
+}
+
+function httpError(response: Response): Error {
+  // Do not echo server-supplied error bodies: they may contain credentials.
+  return new Error(`HTTP ${response.status}`);
+}
+
+export function handleError(error: unknown, out: (line: string) => void): void {
+  if (error instanceof NexusUnavailable) {
+    out(NEXUS_DOWN);
+    process.exitCode = 2;
+  } else {
+    out(error instanceof Error ? error.message : '태스크 요청 실패');
+    process.exitCode = 1;
+  }
+}
+
+/** `tasks` 하위 명령들이 함께 쓰는 출력·인증 문맥 — 응답 출력에서 쓰인 토큰을 가린다. */
+export interface TasksCliContext {
+  deps: TasksCliDeps;
+  out: (line: string) => void;
+  authenticate: () => { baseUrl: string; token?: string };
+  clearToken: () => void;
+}
+
+export function createTasksCliContext(deps: TasksCliDeps): TasksCliContext {
+  let activeToken: string | undefined;
+  const output = deps.output ?? console.log;
+  return {
+    deps,
+    out: (line: string) => output(activeToken ? line.replaceAll(activeToken, '[redacted]') : line),
+    authenticate: () => {
+      const auth = credentials(deps);
+      activeToken = auth?.token;
+      if (!auth) throw new NexusUnavailable();
+      return auth;
+    },
+    clearToken: () => { activeToken = undefined; },
+  };
+}
+
+/** `tasks` 뿌리 명령(별칭 `task`) — 전체·가벼운 등록이 같은 뿌리를 쓴다. */
+export function registerTasksRoot(program: Command): Command {
+  return program.command('tasks').alias('task').description('TOX 태스크 조회 및 승인 · TASK-AGENT 과제 넘기기(hand)');
+}
+
+export function registerTaskListCommand(tasks: Command, ctx: TasksCliContext): void {
+  const { deps, out, authenticate } = ctx;
+  tasks.command('list')
+    .description('우선순위와 생성 시각 순으로 태스크 보기')
+    .option('--status <s>', '상태로 필터')
+    .option('--provider <p>', '외부 출처로 필터')
+    .option('--json', 'JSON 출력')
+    .action(async (opts: { status?: string; provider?: string; json?: boolean }) => {
+      try {
+        ctx.clearToken();
+        const auth = authenticate();
+        const response = await request(deps, auth, '/v1/tasks');
+        if (!response.ok) throw httpError(response);
+        const body = await responseJson(response) as { tasks?: Array<Pick<TaskRow, 'id' | 'status'>> };
+        if (!Array.isArray(body?.tasks)) throw new Error('넥서스 태스크 목록 형식이 유효하지 않다');
+        const cards = body.tasks.filter((task) => !opts.status || task.status === opts.status);
+        // The list endpoint returns board cards without approval or provenance.
+        // Obtain those fields from the detail endpoint rather than displaying guesses.
+        const rows: TaskRow[] = [];
+        for (const card of cards) {
+          const detail = await request(deps, auth, `/v1/tasks/${encodeURIComponent(card.id)}`);
+          if (!detail.ok) throw httpError(detail);
+          const data = await responseJson(detail) as { task?: TaskRow };
+          if (!data?.task || data.task.id !== card.id) throw new Error('넥서스 태스크 상세 형식이 유효하지 않다');
+          if (!opts.provider || (data.task.generatedBy?.kind === 'external' && data.task.generatedBy.provider === opts.provider)) rows.push(data.task);
+        }
+        rows.sort(taskOrder);
+        if (opts.json) out(JSON.stringify(rows));
+        else {
+          out('id\t우선순위\t상태\t승인\t출처\t제목');
+          for (const row of rows) out(taskLine(row));
+        }
+      } catch (error) { handleError(error, out); }
+    });
+}
+
+export function registerTaskShowCommand(tasks: Command, ctx: TasksCliContext): void {
+  const { deps, out, authenticate } = ctx;
+  tasks.command('show <id>')
+    .description(`태스크 상세 보기 (id 가 \`${TASK_CARD_PREFIX}\` 로 시작하면 TASK-AGENT 과제 카드 ⊕ 다음 수)`)
+    .option('--json', 'JSON 출력')
+    .action(async (id: string, opts: { json?: boolean }) => {
+      if (id.startsWith(TASK_CARD_PREFIX)) {
+        const { showTaskCard } = await import('./tasks-card-show.js');
+        await showTaskCard(id, opts, deps, out);
+        return;
+      }
+      try {
+        ctx.clearToken();
+        const auth = authenticate();
+        const response = await request(deps, auth, `/v1/tasks/${encodeURIComponent(id)}`);
+        if (!response.ok) throw httpError(response);
+        const data = await responseJson(response) as { task?: TaskRow };
+        if (!data?.task) throw new Error('넥서스 태스크 상세 형식이 유효하지 않다');
+        if (opts.json) out(JSON.stringify(data));
+        else {
+          out(taskLine(data.task));
+          out(JSON.stringify(data, null, 2));
+        }
+      } catch (error) { handleError(error, out); }
+    });
+}
+
+/** 가벼운 진입 전용 — `tasks list`·`tasks show` 만 등록한다(전체 레지스트리 `registerTasksCommands` 를 싣지 않는다). */
+export function registerTaskReadCommands(program: Command, deps: TasksCliDeps = {}): void {
+  const ctx = createTasksCliContext(deps);
+  const tasks = registerTasksRoot(program);
+  registerTaskListCommand(tasks, ctx);
+  registerTaskShowCommand(tasks, ctx);
+}

package/src/cli/usage-cli.ts

@@ -75,10 +75,11 @@ function configuredUsageHosts(): { local: string; remote: string[] } {
   return { local, remote: [...new Set(entries.map((entry) => entry.host?.trim()).filter((host): host is string => !!host && host !== local))] };
 }
 
-type UsageAxis = 'stage' | 'model' | 'account';
+type UsageAxis = 'stage' | 'phase' | 'model' | 'account';
 type ExtendedRunUsageInput = RunUsageInput & { stage?: string | null; account?: string | null; origin?: string; podJob?: string; job?: string; measured?: boolean };
 type AxisUsageRow = {
   stage?: string;
+  phase?: string;
   model?: string;
   account?: string;
   hostIds: string[];
@@ -97,7 +98,7 @@ type AxisUsageRow = {
 };
 
 type FederatedUsageRow = {
-  runId?: string; role?: string; site?: string; stage?: string; model?: string; account?: string;
+  runId?: string; role?: string; site?: string; stage?: string; phase?: string; model?: string; account?: string;
   billingProvider?: string; billing?: string; hostIds: string[]; rankUsd?: number;
   calls: number; inputTokens: number; outputTokens: number; cacheReadInputTokens: number;
   cacheCreationInputTokens: number; reasoningOutputTokens: number; usdKnown: number;
@@ -122,7 +123,7 @@ function validUsageRows(value: unknown, axis: 'run' | 'role' | UsageAxis): value
         const number = row[field];
         return typeof number === 'number' && Number.isFinite(number) && number >= 0;
       })
-      && (axis !== 'stage' && axis !== 'model' && axis !== 'account'
+      && (axis !== 'stage' && axis !== 'phase' && axis !== 'model' && axis !== 'account'
         || typeof row.rankUsd === 'number' && Number.isFinite(row.rankUsd));
   });
 }
@@ -137,7 +138,7 @@ function mergeUsageRows(groups: readonly FederatedUsageRow[][], axis: 'run' | 'r
     if (!previous) { merged.set(key, { ...row, hostIds: [...row.hostIds] }); continue; }
     for (const field of SUM_FIELDS) previous[field] += row[field];
     previous.hostIds = [...new Set([...previous.hostIds, ...row.hostIds])];
-    if (axis === 'stage' || axis === 'model' || axis === 'account') previous.rankUsd = previous.usdKnown + previous.apiEquivalentUsd;
+    if (axis === 'stage' || axis === 'phase' || axis === 'model' || axis === 'account') previous.rankUsd = previous.usdKnown + previous.apiEquivalentUsd;
   }
   return [...merged.values()];
 }
@@ -186,6 +187,7 @@ function rollupByAxis(inputs: readonly ExtendedRunUsageInput[], axis: UsageAxis)
   const groups = new Map<string, ExtendedRunUsageInput[]>();
   for (const data of inputs) {
     const value = axis === 'stage' ? stageForUsage(data)
+      : axis === 'phase' ? (typeof data.phase === 'string' && data.phase.length > 0 ? data.phase : '(none)')
       : axis === 'model' ? (data.model || '(none)')
         : (data.account || '(none)');
     const group = groups.get(value) ?? [];
@@ -216,7 +218,7 @@ function rollupByAxis(inputs: readonly ExtendedRunUsageInput[], axis: UsageAxis)
 }
 
 function isUsageAxis(value: string): value is 'run' | 'role' | UsageAxis {
-  return value === 'run' || value === 'role' || value === 'stage' || value === 'model' || value === 'account';
+  return value === 'run' || value === 'role' || value === 'stage' || value === 'phase' || value === 'model' || value === 'account';
 }
 
 function formatAxisUsage(row: AxisUsageRow, axis: UsageAxis): string {
@@ -249,9 +251,9 @@ export function registerUsageCommand(program: Command, deps: UsageCliDeps = {}):
 
   usage
     .command('runs')
-    .description('저장된 llm-usage 로그를 런·역할·단계·모델·계정별로 집계한다')
+    .description('저장된 llm-usage 로그를 런·역할·단계·phase·모델·계정별로 집계한다')
     .option('--run <runId>', '런 ID 정확 일치')
-    .option('--by <axis>', '집계 축 (run | role | stage | model | account)', 'run')
+    .option('--by <axis>', '집계 축 (run | role | stage | phase | model | account)', 'run')
     .option(...LOGS_SINCE_OPTION)
     .option('--hosts <scope>', '호스트 연합 (all: 이 호스트 + 설정된 taskAgent.parentHost)')
     .option('--json', '집계 행 JSON 출력')
@@ -298,14 +300,14 @@ export function registerUsageCommand(program: Command, deps: UsageCliDeps = {}):
         const complete = !rosterReason && hosts.every((host) => host.status === 'ok');
         const rows = mergeUsageRows(parts, opts.by as 'run' | 'role' | UsageAxis);
         if (opts.by === 'role') rows.sort((a, b) => b.calls - a.calls);
-        if (opts.by === 'stage' || opts.by === 'model' || opts.by === 'account') rows.sort((a, b) => (b.rankUsd ?? 0) - (a.rankUsd ?? 0) || b.calls - a.calls);
+        if (opts.by === 'stage' || opts.by === 'phase' || opts.by === 'model' || opts.by === 'account') rows.sort((a, b) => (b.rankUsd ?? 0) - (a.rankUsd ?? 0) || b.calls - a.calls);
         if (json) { out.log(JSON.stringify({ rows, hosts, complete, ...(rosterReason ? { reason: rosterReason } : {}) }, null, 2)); return; }
         out.log(`호스트 ${hosts.filter((host) => host.status === 'ok').length}/${hosts.length} 측정 · ${complete ? '완결' : '부분 합계'}`);
         if (rosterReason) out.log(`호스트 목록: 못 잼 (${rosterReason})`);
         for (const host of hosts) if (host.status === 'unmeasured') out.log(`${host.host}: 못 잼 (${host.reason})`);
         if (rows.length === 0) { out.log('(일치하는 런 사용량 없음)'); return; }
         for (const row of rows) {
-          if (opts.by === 'stage' || opts.by === 'model' || opts.by === 'account') out.log(formatAxisUsage(row as AxisUsageRow, opts.by));
+          if (opts.by === 'stage' || opts.by === 'phase' || opts.by === 'model' || opts.by === 'account') out.log(formatAxisUsage(row as AxisUsageRow, opts.by));
           else if (opts.by === 'role') out.log(`${row.role}  ${row.site}  ${row.model}  ${row.billingProvider}/${row.billing}  calls=${row.calls}  input=${row.inputTokens}  output=${row.outputTokens}  usdKnown=${row.usdKnown}  unknownCostCalls=${row.unknownCostCalls}  includedCalls=${row.includedCalls}  apiEquivalentUsd=${row.apiEquivalentUsd}`);
           else out.log(`${row.runId}  ${row.model}  ${row.billingProvider}/${row.billing}  hosts=${row.hostIds.join(',') || '(none)'}  calls=${row.calls}  input=${row.inputTokens}  output=${row.outputTokens}  cacheRead=${row.cacheReadInputTokens}  cacheCreation=${row.cacheCreationInputTokens}  reasoning=${row.reasoningOutputTokens}  usdKnown=${row.usdKnown}  unknownCostCalls=${row.unknownCostCalls}  includedCalls=${row.includedCalls}  apiEquivalentUsd=${row.apiEquivalentUsd}`);
         }
@@ -323,14 +325,14 @@ export function registerUsageCommand(program: Command, deps: UsageCliDeps = {}):
           localFailure = '로컬 logs.db 조회 실패';
         }
       }
-      const unwrapPod = opts.by === 'stage' || opts.by === 'model' || opts.by === 'account';
+      const unwrapPod = opts.by === 'stage' || opts.by === 'phase' || opts.by === 'model' || opts.by === 'account';
       // ⭐ METER-POD-ROLLUP-GAP-2 — Pod 사용량 재방출 행(podRollupKey)은 «더 완전한 한 행»만 센다(키 없는 행은 그대로).
       const selected = rows.map((row) => usageData(row, unwrapPod))
         .filter((data): data is ExtendedRunUsageInput => data !== null)
         .filter((data) => opts.run === undefined || data.runId === opts.run);
       // A returned Pod raw row and its host rollup describe the same usage. Keep raw rows when no measured rollup exists.
       const inputs = dedupePodRollupRows(unwrapPod ? excludeCoveredPodRawRows(selected) : selected);
-      if (opts.by === 'stage' || opts.by === 'model' || opts.by === 'account') {
+      if (opts.by === 'stage' || opts.by === 'phase' || opts.by === 'model' || opts.by === 'account') {
         const report = rollupByAxis(inputs, opts.by);
         if (opts.hosts === 'all') { emitFederated(report, localFailure); return; }
         if (json) {

package/src/clipboard/history.ts

@@ -8,15 +8,19 @@
 //
 // Why polling vs an OS event hook: macOS doesn't expose a clipboard-
 // changed notification to userland binaries without entitlements.
-// pbpaste at 1.5s cadence is cheap (sub-millisecond per call on a
-// recent Mac) and the small lag is fine for "look back at what I
-// copied 30s ago" use cases.
+// Keep a short active cadence, then back off while the TUI is idle so
+// an open terminal does not spawn pbpaste every 1.5s indefinitely.
+// CLASSIC-IDLE-CLIPBOARD (2026-10-21): callers that only show the history
+// inside a panel start with `active: false` and flip `setActive(true)` while
+// the panel is visible — a closed panel spawns zero pbpaste processes
+// (5-minute idle classic TUI measured 88 reads before this change).
 //
 // Image entries: we already track a separate path-based registry for
 // pasted screenshots (context.ts). This module is text-only by
 // design — image previews live in the main scratchpad already.
 
 import { readClipboardText, isClipboardSupported } from './index.js';
+import { debug } from '../debug/log.js';
 
 export interface ClipboardEntry {
   /** UTF-8 text. Trimmed of a single trailing newline so visually
@@ -29,6 +33,19 @@ export interface ClipboardEntry {
 export interface ClipboardHistoryOpts {
   /** Polling interval in ms. Defaults to 1500. */
   intervalMs?: number;
+  /** Start slowing clipboard reads after this much user inactivity. Defaults to 2 minutes. */
+  idleAfterMs?: number;
+  /** Poll interval multiplier after idleAfterMs. Defaults to 10 (15s with the default cadence). */
+  idleIntervalMultiplier?: number;
+  /** Start the deepest backoff after this much user inactivity. Defaults to 10 minutes. */
+  longIdleAfterMs?: number;
+  /** Poll interval multiplier after longIdleAfterMs. Defaults to 60 (90s with the default cadence). */
+  longIdleIntervalMultiplier?: number;
+  /** Start polling immediately. Defaults to true. `false` keeps the poller
+   *  dormant (no reads, no timer) until `setActive(true)`. */
+  active?: boolean;
+  /** Busy streams keep the active cadence and restart the idle grace period when they finish. */
+  isBusy?: () => boolean;
   /** Cap on stored entries; oldest fall off when exceeded. Defaults
    *  to 50 — enough for a typical session, not so big the list
    *  becomes unscrollable. */
@@ -40,6 +57,17 @@ export interface ClipboardHistoryOpts {
   maxBytes?: number;
 }
 
+/** Dependencies are injectable so tests can exercise the real poller without
+ * process-wide `mock.module()` state. Production callers use the defaults. */
+export interface ClipboardHistoryDependencies {
+  readClipboardText(): Promise<string | null>;
+  isClipboardSupported(): boolean;
+  /** Observation sink for poll-state transitions. Defaults to
+   *  `debug.log('clipboard.history', …)`; tests inject a recorder because
+   *  the debug sink arms its own flush timer. */
+  observe?(event: 'poll-state', data: { active: boolean; reason: string }): void;
+}
+
 export interface ClipboardHistory {
   /** Snapshot list, newest first. Caller may read but should not
    *  mutate — use `clear` to reset. */
@@ -54,12 +82,27 @@ export interface ClipboardHistory {
    *  history reflects the just-promoted entry without waiting for
    *  the next tick. */
   pokeNow(): Promise<void>;
+  /** Mark TUI input. Wakes the poller immediately if it had slowed down. */
+  noteActivity(): void;
+  /** Notify the poller immediately when its busy source changes state. */
+  noteBusyChange(): void;
+  /** Start/stop background polling (e.g. history panel opened/closed).
+   *  Activating reads once immediately; deactivating clears the timer.
+   *  Repeating the current state is a no-op. */
+  setActive(active: boolean, reason?: string): void;
 }
 
 /** Start polling. No-op on non-clipboard platforms — returns a stub
  *  with empty entries so callers don't need to guard every call. */
-export function startClipboardHistory(opts: ClipboardHistoryOpts = {}): ClipboardHistory {
+export function startClipboardHistory(
+  opts: ClipboardHistoryOpts = {},
+  dependencies: ClipboardHistoryDependencies = { readClipboardText, isClipboardSupported },
+): ClipboardHistory {
   const intervalMs = opts.intervalMs ?? 1500;
+  const idleAfterMs = opts.idleAfterMs ?? 2 * 60_000;
+  const idleIntervalMultiplier = opts.idleIntervalMultiplier ?? 10;
+  const longIdleAfterMs = opts.longIdleAfterMs ?? 10 * 60_000;
+  const longIdleIntervalMultiplier = opts.longIdleIntervalMultiplier ?? 60;
   const maxEntries = opts.maxEntries ?? 50;
   const maxBytes = opts.maxBytes ?? 8 * 1024;
 
@@ -67,15 +110,51 @@ export function startClipboardHistory(opts: ClipboardHistoryOpts = {}): Clipboar
   const subs = new Set<() => void>();
   let stopped = false;
   let lastSeenText: string | null = null;
-  let timer: ReturnType<typeof setInterval> | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<void> | null = null;
+  let immediatePollAfterInFlight = false;
+  let queuedActivityPoll: Promise<void> | null = null;
+  let lastActivityAt = Date.now();
+  let wasBusy = readBusy();
+  let active = opts.active ?? true;
+
+  function readBusy(): boolean {
+    try { return opts.isBusy?.() ?? false; } catch { return false; }
+  }
+
+  const idleMs = (): number => {
+    const busy = readBusy();
+    if (wasBusy && !busy) lastActivityAt = Date.now();
+    wasBusy = busy;
+    return busy ? 0 : Math.max(0, Date.now() - lastActivityAt);
+  };
+
+  const nextDelayMs = (): number => {
+    const idle = idleMs();
+    if (idle >= longIdleAfterMs) return intervalMs * longIdleIntervalMultiplier;
+    if (idle >= idleAfterMs) return intervalMs * idleIntervalMultiplier;
+    return intervalMs;
+  };
+
+  const scheduleNext = (): void => {
+    if (stopped || !active) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void poll();
+    }, nextDelayMs());
+  };
 
-  if (!isClipboardSupported()) {
+  if (!dependencies.isClipboardSupported()) {
     return {
       entries,
       onChange: (fn) => { subs.add(fn); return () => subs.delete(fn); },
       stop: () => { stopped = true; },
       clear: () => { entries.length = 0; },
       pokeNow: async () => { /* no-op */ },
+      noteActivity: () => {},
+      noteBusyChange: () => {},
+      setActive: () => {},
     };
   }
 
@@ -97,25 +176,112 @@ export function startClipboardHistory(opts: ClipboardHistoryOpts = {}): Clipboar
     for (const fn of subs) { try { fn(); } catch { /* ignore */ } }
   };
 
-  const poll = async (): Promise<void> => {
-    if (stopped) return;
-    try { ingest(await readClipboardText()); } catch { /* swallow */ }
+  const poll = (): Promise<void> => {
+    if (stopped) return Promise.resolve();
+    if (inFlight) return inFlight;
+    const run = Promise.resolve().then(async (): Promise<void> => {
+      try { ingest(await dependencies.readClipboardText()); } catch { /* swallow */ }
+      finally {
+        inFlight = null;
+        if (immediatePollAfterInFlight && !stopped) {
+          immediatePollAfterInFlight = false;
+          queuedActivityPoll = poll();
+          void queuedActivityPoll;
+        } else {
+          immediatePollAfterInFlight = false;
+          scheduleNext();
+        }
+      }
+    });
+    inFlight = run;
+    return run;
+  };
+
+  const pollImmediately = (): void => {
+    if (inFlight) {
+      immediatePollAfterInFlight = true;
+      return;
+    }
+    void poll();
+  };
+
+  const noteActivity = (): void => {
+    const wokeFromIdle = idleMs() >= idleAfterMs;
+    lastActivityAt = Date.now();
+    wasBusy = readBusy();
+    if (wokeFromIdle && active) {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      pollImmediately();
+    }
+  };
+
+  const noteBusyChange = (): void => {
+    const busy = readBusy();
+    if (busy === wasBusy) return;
+    wasBusy = busy;
+    lastActivityAt = Date.now();
+    if (!active) return;
+    if (timer) clearTimeout(timer);
+    timer = null;
+    pollImmediately();
+  };
+
+  const setActive = (next: boolean, reason = 'unspecified'): void => {
+    if (stopped || next === active) return;
+    active = next;
+    const observe = dependencies.observe
+      ?? ((event: string, data: unknown) => { debug.log('clipboard.history', event, data); });
+    try { observe('poll-state', { active, reason }); } catch { /* observation must not break polling */ }
+    if (timer) clearTimeout(timer);
+    timer = null;
+    if (!active) {
+      immediatePollAfterInFlight = false;
+      return;
+    }
+    lastActivityAt = Date.now();
+    wasBusy = readBusy();
+    pollImmediately();
   };
 
   // Kick off immediately so the very first frame already has at
   // least one entry (whatever's currently on the clipboard).
-  void poll();
-  timer = setInterval(() => { void poll(); }, intervalMs);
+  // A dormant poller (active:false) reads on its first setActive(true).
+  if (active) void poll();
 
   return {
     entries,
     onChange: (fn) => { subs.add(fn); return () => subs.delete(fn); },
     stop: () => {
       stopped = true;
-      if (timer) clearInterval(timer);
+      if (timer) clearTimeout(timer);
       timer = null;
     },
     clear: () => { entries.length = 0; lastSeenText = null; },
-    pokeNow: async () => { await poll(); },
+    pokeNow: async () => {
+      // Keep this request independent from noteActivity. If a wake poll is
+      // already queued behind the current read, it will satisfy this poke.
+      lastActivityAt = Date.now();
+      wasBusy = readBusy();
+      const currentRead = inFlight;
+      const canUseQueuedWake = Boolean(currentRead && immediatePollAfterInFlight);
+      if (timer) clearTimeout(timer);
+      timer = null;
+      if (currentRead) {
+        await currentRead;
+        if (canUseQueuedWake && queuedActivityPoll) {
+          await queuedActivityPoll;
+          return;
+        }
+        if (timer) clearTimeout(timer);
+        timer = null;
+      }
+      // Reads already in progress may have captured the clipboard before
+      // this promotion, so take a fresh snapshot after they finish.
+      await poll();
+    },
+    noteActivity,
+    noteBusyChange,
+    setActive,
   };
 }

package/src/config.ts

@@ -6,6 +6,7 @@ import { lookupLlmTierSpec } from './model-tier/llm-tier-map.js';
 import { listSshHosts } from './ssh/ssh-hosts.js';
 import { isInstalledPackagePath } from './instance/installed-package.js';
 import { defaultObsidianVault } from './obsidian/default-vault.js';
+import { OPENGATEWAY_DEFAULT_MODEL } from './llm/opengateway-models.js';
 
 // ── User config ──
 export const REMOTE_HOME = homedir();
@@ -191,7 +192,7 @@ export function refreshKeyFromCache(envName: string): boolean {
  * 자식 프로세스도 이 env 를 물려받는다. 반환 = 캐시로 채운 이름(값은 절대 안 싣는다).
  */
 export const DAEMON_KEY_ENV_NAMES = [
-  'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'XAI_API_KEY', 'OPENROUTER_API_KEY',
+  'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'XAI_API_KEY', 'OPENROUTER_API_KEY', 'OPENGATEWAY_API_KEY',
   'ELANOUS_OPENAI_RELAY_SHARED_SECRET',
 ] as const;
 
@@ -239,6 +240,12 @@ export const OPENROUTER_API_URL = 'https://openrouter.ai/api/v1/chat/completions
 // 기본 = 사다리 `balanced`(`llm-tier-map.ts` OPENROUTER). 카탈로그 id 는 `openrouter/<vendor>/<model>`,
 //   wire 로는 `openrouter/` 를 떼고 보낸다(`makeOpenRouterProvider`).
 export const OPENROUTER_MODEL = process.env.OPENROUTER_MODEL || 'openrouter/z-ai/glm-5.3';
+/** Optional OpenAI-compatible gateway. Cache wins over inherited env, as for other API keys. */
+export function getOpenGatewayApiKey(): string | undefined {
+  return keyFromCacheOrEnv('OPENGATEWAY_API_KEY');
+}
+export const OPENGATEWAY_API_URL = 'https://apis.opengateway.ai/v1/chat/completions';
+export const OPENGATEWAY_MODEL = process.env.OPENGATEWAY_MODEL || OPENGATEWAY_DEFAULT_MODEL;
 export function getLocalLLMUrl(): string | undefined {
   return process.env.LOCAL_LLM_URL; // e.g. http://localhost:11434/v1 (ollama)
 }

package/src/core-turn/run-core-turn.ts

@@ -256,7 +256,7 @@ export async function runCoreTurn(
       mode: deferredEnabled ? 'always' : 'off',
     });
   }
-  debug.log('capability.resolve', 'tier-split', {
+  debug.log('capability.resolve', 'tool-tier-split', {
     sessionId: ctx.sessionId,
     surfaceId: surface.id,
     surfaceSelectionReason: surface.selectionReason,
@@ -285,7 +285,9 @@ export async function runCoreTurn(
         signal: ctx.signal,
         ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}),
         ...(ctx.maxToolTurns !== undefined ? { maxTurns: ctx.maxToolTurns } : {}),
-        ...(ctx.modelOverride !== undefined ? { model: ctx.modelOverride } : {}),
+        ...(ctx.initialProvider !== undefined
+          ? { initialProvider: ctx.initialProvider, ...(ctx.skipProviders ? { skipProviders: ctx.skipProviders } : {}) }
+          : ctx.modelOverride !== undefined ? { model: ctx.modelOverride } : {}),
         ...(ctx.callbacks?.onResolvedProvider !== undefined ? { onResolvedProvider: ctx.callbacks.onResolvedProvider } : {}),
         ...(ctx.budgetGrant !== undefined ? { budgetGrant: ctx.budgetGrant } : {}),
         ...(ctx.terminalToolNames !== undefined ? { terminalToolNames: ctx.terminalToolNames } : {}),