@triflux/remote 10.1.0 → 10.25.1

package/hub/team/conductor.mjs

@@ -1,671 +1,1379 @@
-// hub/team/conductor.mjs — 세션 오케스트레이션 Conductor
-// native-supervisor.mjs의 spawn/kill을 래핑하되, 상태 머신 + health probe +
-// auto-restart + event log를 추가하여 "조용한 실패"를 구조적으로 불가능하게 만든다.
-//
-// 기존 native-supervisor와의 차이:
-// 1. 상태 머신 (alive/dead → 7 states + 2 terminal)
-// 2. Health probe 4단계 (+ INPUT_WAIT 감지)
-// 3. Auto-restart (maxRestarts=3)
-// 4. JSONL event log (블랙박스 리코더)
-
-import { spawn, execFile } from 'node:child_process';
-import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
-import { mkdirSync, createWriteStream, readFileSync, copyFileSync } from 'node:fs';
-import { EventEmitter } from 'node:events';
-
-import { killProcess, } from '@triflux/core/hub/platform.mjs';
-import { createEventLog } from './event-log.mjs';
-import { createHealthProbe } from './health-probe.mjs';
-import { createRemoteProbe } from './remote-probe.mjs';
-import { buildLauncher } from './launcher-template.mjs';
-import { broker } from '@triflux/core/hub/account-broker.mjs';
-
-/** 세션 상태 */
-export const STATES = Object.freeze({
-  INIT: 'init',
-  STARTING: 'starting',
-  HEALTHY: 'healthy',
-  STALLED: 'stalled',
-  INPUT_WAIT: 'input_wait',
-  FAILED: 'failed',
-  RESTARTING: 'restarting',
-  DEAD: 'dead',
-  COMPLETED: 'completed',
-});
-
-/** 유효한 상태 전이 테이블 */
-const TRANSITIONS = Object.freeze({
-  [STATES.INIT]:       [STATES.STARTING],
-  [STATES.STARTING]:   [STATES.HEALTHY, STATES.FAILED],
-  [STATES.HEALTHY]:    [STATES.STALLED, STATES.INPUT_WAIT, STATES.FAILED, STATES.COMPLETED],
-  [STATES.STALLED]:    [STATES.HEALTHY, STATES.FAILED],
-  [STATES.INPUT_WAIT]: [STATES.HEALTHY, STATES.FAILED],
-  [STATES.FAILED]:     [STATES.RESTARTING, STATES.DEAD],
-  [STATES.RESTARTING]: [STATES.STARTING],
-  [STATES.DEAD]:       [],
-  [STATES.COMPLETED]:  [],
-});
-
-const TERMINAL_STATES = new Set([STATES.DEAD, STATES.COMPLETED]);
-const DEFAULT_MAX_RESTARTS = 3;
-const DEFAULT_GRACE_MS = 10_000;
-
-/**
- * Conductor 팩토리.
- * @param {object} opts
- * @param {string} opts.logsDir — 이벤트 로그 디렉토리
- * @param {number} [opts.maxRestarts=3]
- * @param {number} [opts.graceMs=10000] — shutdown grace period
- * @param {object} [opts.probeOpts] — health-probe 옵션 오버라이드
- * @returns {Conductor}
- */
-export function createConductor(opts = {}) {
-  const {
-    logsDir,
-    maxRestarts = DEFAULT_MAX_RESTARTS,
-    graceMs = DEFAULT_GRACE_MS,
-    probeOpts = {},
-  } = opts;
-
-  if (!logsDir) throw new Error('logsDir is required');
-  mkdirSync(logsDir, { recursive: true });
-
-  const emitter = new EventEmitter();
-  const sessions = new Map();
-  let shuttingDown = false;
-
-  // 공유 event log (모든 세션 이벤트를 하나의 JSONL에)
-  const eventLog = createEventLog(join(logsDir, 'conductor-events.jsonl'));
-
-  /**
-   * 세션 상태 전이.
-   * @param {object} session
-   * @param {string} nextState
-   * @param {string} [reason]
-   */
-  function transition(session, nextState, reason = '') {
-    const valid = TRANSITIONS[session.state] || [];
-    if (!valid.includes(nextState)) {
-      eventLog.append('invalid_transition', {
-        session: session.id,
-        from: session.state,
-        to: nextState,
-        reason,
-      });
-      return false;
-    }
-
-    const prev = session.state;
-    session.state = nextState;
-
-    eventLog.append('stateChange', {
-      session: session.id,
-      from: prev,
-      to: nextState,
-      reason,
-      restarts: session.restarts,
-    });
-
-    emitter.emit('stateChange', { sessionId: session.id, from: prev, to: nextState, reason });
-
-    // Terminal state cleanup
-    if (TERMINAL_STATES.has(nextState)) {
-      session.probe?.stop();
-    }
-
-    return true;
-  }
-
-  /**
-   * 프로세스를 강제 종료.
-   * Windows: taskkill /T /F /PID (프로세스 트리). POSIX: SIGKILL.
-   */
-  function forceKill(pid) {
-    if (!pid || pid <= 0) return;
-    killProcess(pid, { signal: 'SIGKILL', tree: true, force: true, timeout: 5000 });
-  }
-
-  /**
-   * 원격 세션의 psmux 세션을 SSH 경유로 kill.
-   * fire-and-forget: 실패해도 에러 전파 안 함.
-   */
-  function killRemoteSession(session) {
-    const host = session.config.host;
-    if (!host) return;
-    let sshUser = session.config.sshUser;
-    let sshIp = host;
-    // hosts.json에서 ssh_user/IP 해결
-    try {
-      const hostsPath = join(opts.repoRoot || process.cwd(), 'references', 'hosts.json');
-      const hosts = JSON.parse(readFileSync(hostsPath, 'utf8'));
-      const hostCfg = hosts.hosts?.[host];
-      if (hostCfg) {
-        sshUser = sshUser || hostCfg.ssh_user;
-        sshIp = hostCfg.tailscale?.ip || host;
-      }
-    } catch { /* hosts.json 없으면 fallback */ }
-    if (!sshUser) return;
-    const execFn = opts.deps?.execFile || execFile;
-    execFn('ssh', [`${sshUser}@${sshIp}`, 'psmux', 'kill-session', '-t', session.id],
-      { timeout: 10_000 }, () => {});
-    eventLog.append('remote_kill', { session: session.id, host, sshUser, sshIp });
-  }
-
-  /**
-   * 단일 세션의 child process를 정리.
-   * 원격 세션은 SSH 경유 psmux kill-session으로 정리.
-   */
-  async function cleanupChild(session) {
-    session.probe?.stop();
-
-    // 원격 세션 — SSH 경유 psmux kill-session
-    if (session.config.remote) {
-      killRemoteSession(session);
-      return;
-    }
-
-    const child = session.child;
-    if (!child) return;
-
-    const pid = child.pid;
-    if (!pid) return;
-
-    // SIGTERM 먼저
-    try { child.kill('SIGTERM'); } catch { /* already dead */ }
-
-    // Grace period 대기
-    await new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        forceKill(pid);
-        resolve();
-      }, graceMs);
-      timer.unref?.();
-      child.once('exit', () => {
-        clearTimeout(timer);
-        resolve();
-      });
-    });
-  }
-
-  /**
-   * Health probe 콜백 — probe 결과에 따라 상태 전이 판단.
-   */
-  function handleProbeResult(session, result) {
-    if (TERMINAL_STATES.has(session.state)) return;
-    if (session.state === STATES.INIT || session.state === STATES.RESTARTING) return;
-
-    eventLog.append('health', {
-      session: session.id,
-      ...result,
-    });
-
-    // L0 실패 — 로컬: exit handler에서 처리. 원격: probe가 유일한 감지 수단.
-    if (result.l0 === 'fail') {
-      if (session.config.remote) {
-        handleFailure(session, 'remote_L0_fail');
-      }
-      return;
-    }
-
-    // L3 completed (원격 완료 토큰 감지)
-    if (result.l3 === 'completed' && session.config.remote) {
-      transition(session, STATES.COMPLETED, 'remote_completion_token');
-      emitter.emit('completed', { sessionId: session.id });
-      if (typeof session.config.onCompleted === 'function') {
-        session.config.onCompleted({ sessionId: session.id });
-      }
-      maybeAutoShutdown();
-      return;
-    }
-
-    // L1 INPUT_WAIT 감지
-    if (result.l1 === 'input_wait' && session.state === STATES.HEALTHY) {
-      transition(session, STATES.INPUT_WAIT, `input_wait:${result.inputWaitPattern}`);
-      emitter.emit('inputWait', {
-        sessionId: session.id,
-        pattern: result.inputWaitPattern,
-      });
-      return;
-    }
-
-    // INPUT_WAIT → output 재개 시 HEALTHY 복귀
-    if (session.state === STATES.INPUT_WAIT && result.l1 === 'ok') {
-      transition(session, STATES.HEALTHY, 'output_resumed');
-      return;
-    }
-
-    // L1 stall
-    if (result.l1 === 'stall' && session.state === STATES.HEALTHY) {
-      transition(session, STATES.STALLED, 'L1_stall');
-      return;
-    }
-
-    // STALLED → output 재개 시 HEALTHY 복귀
-    if (session.state === STATES.STALLED && result.l1 === 'ok') {
-      transition(session, STATES.HEALTHY, 'output_resumed');
-      return;
-    }
-
-    // L3 timeout (아직 STARTING 상태)
-    if (result.l3 === 'timeout' && session.state === STATES.STARTING) {
-      handleFailure(session, 'L3_timeout');
-      return;
-    }
-
-    // STARTING → L0 ok + L3 ok → HEALTHY
-    if (session.state === STATES.STARTING && result.l0 === 'ok' && result.l3 === 'ok') {
-      transition(session, STATES.HEALTHY, 'probe_healthy');
-      return;
-    }
-
-    // STARTING → L0 ok (L3 아직 미판정) → STARTING 유지 (대기)
-  }
-
-  /**
-   * 실패 처리 — restart 또는 DEAD.
-   */
-  function handleFailure(session, reason) {
-    if (TERMINAL_STATES.has(session.state)) return;
-
-    transition(session, STATES.FAILED, reason);
-
-    if (session.restarts < maxRestarts) {
-      transition(session, STATES.RESTARTING, `restart_${session.restarts + 1}/${maxRestarts}`);
-      session.restarts += 1;
-      void respawnSession(session);
-    } else {
-      transition(session, STATES.DEAD, `maxRestarts(${maxRestarts})_exceeded`);
-      emitter.emit('dead', { sessionId: session.id, reason });
-
-      // broker release on final death
-      if (broker && session.config.accountId) {
-        broker.release(session.config.accountId, { ok: false, failureMode: session.lastFailureMode });
-        if (session.lastFailureMode === 'rate_limited') {
-          broker.markRateLimited(session.config.accountId, 5 * 60 * 1000);
-        }
-      }
-    }
-  }
-
-  /**
-   * 세션의 child process를 (재)시작.
-   */
-  async function respawnSession(session) {
-    // 기존 child 정리
-    await cleanupChild(session);
-
-    transition(session, STATES.STARTING, session.restarts > 0 ? 'respawn' : 'initial');
-
-    const launcher = session.launcher;
-    const outPath = join(logsDir, `${session.id}.out.log`);
-    const errPath = join(logsDir, `${session.id}.err.log`);
-    mkdirSync(logsDir, { recursive: true });
-
-    const outWs = createWriteStream(outPath, { flags: 'a' });
-    const errWs = createWriteStream(errPath, { flags: 'a' });
-
-    let outputBytes = 0;
-    let recentOutput = '';
-
-    let child;
-    try {
-      child = spawn(launcher.command, {
-        shell: true,
-        env: { ...process.env, ...launcher.env, ...(session.config.env || {}) },
-        stdio: ['pipe', 'pipe', 'pipe'],
-        windowsHide: true,
-      });
-    } catch (err) {
-      eventLog.append('spawn_error', { session: session.id, error: err.message });
-      handleFailure(session, `spawn_error:${err.message}`);
-      return;
-    }
-
-    session.child = child;
-    session.outPath = outPath;
-    session.errPath = errPath;
-
-    eventLog.append('spawn', {
-      session: session.id,
-      agent: session.config.agent,
-      pid: child.pid,
-      command: launcher.command,
-      restart: session.restarts,
-    });
-
-    // stdout+stderr 통합 추적 (F3 해결: stderr만 출력되는 경우도 advancing 판정)
-    const trackOutput = (buf) => {
-      outputBytes += buf.length;
-      const txt = String(buf);
-      // 최근 2KB만 유지 (INPUT_WAIT 패턴 감지용)
-      recentOutput += txt;
-      if (recentOutput.length > 2048) {
-        recentOutput = recentOutput.slice(-2048);
-      }
-    };
-
-    child.stdout?.on('data', (buf) => { outWs.write(buf); trackOutput(buf); });
-    child.stderr?.on('data', (buf) => { errWs.write(buf); trackOutput(buf); });
-
-    child.on('exit', (code, signal) => {
-      session.alive = false;
-      try { outWs.end(); } catch { /* ignore */ }
-      try { errWs.end(); } catch { /* ignore */ }
-
-      eventLog.append('exit', {
-        session: session.id,
-        code,
-        signal,
-        restart: session.restarts,
-      });
-
-      if (TERMINAL_STATES.has(session.state)) return;
-
-      if (code === 0 && !signal) {
-        transition(session, STATES.COMPLETED, 'exit_0');
-        emitter.emit('completed', { sessionId: session.id });
-        if (typeof session.config.onCompleted === 'function') {
-          session.config.onCompleted({ sessionId: session.id });
-        }
-        if (broker && session.config.accountId) {
-          broker.release(session.config.accountId, { ok: true });
-        }
-      } else {
-        // detect rate_limited from recent output before handleFailure
-        if (/(rate.?limit|quota|throttl|too.many.requests|429|usage.limit)/ui.test(recentOutput)) {
-          session.lastFailureMode = 'rate_limited';
-        }
-        handleFailure(session, `exit_code:${code},signal:${signal}`);
-      }
-
-      maybeAutoShutdown();
-    });
-
-    child.on('error', (err) => {
-      session.alive = false;
-      eventLog.append('child_error', { session: session.id, error: err.message });
-      if (!TERMINAL_STATES.has(session.state)) {
-        handleFailure(session, `child_error:${err.message}`);
-      }
-    });
-
-    session.alive = true;
-
-    // Health probe 설정
-    session.probe?.stop();
-    const probe = createHealthProbe(
-      {
-        get pid() { return child.pid; },
-        get alive() { return session.alive; },
-        getOutputBytes: () => outputBytes,
-        getRecentOutput: () => recentOutput,
-      },
-      {
-        ...probeOpts,
-        onProbe: (result) => handleProbeResult(session, result),
-      },
-    );
-    session.probe = probe;
-    probe.start();
-  }
-
-  /**
-   * 원격 세션 시작 — child process 대신 SSH capture-pane 폴링.
-   * 원격 세션은 remote-spawn.mjs가 이미 psmux 세션을 생성한 상태를 가정.
-   */
-  function startRemoteSession(session) {
-    transition(session, STATES.STARTING, 'remote_initial');
-
-    const { host, paneTarget, sessionName } = session.config;
-    const resolvedPane = paneTarget || `${sessionName || session.id}:0.0`;
-    const resolvedSessionName = sessionName || session.id;
-
-    eventLog.append('remote_start', {
-      session: session.id,
-      host,
-      paneTarget: resolvedPane,
-      sessionName: resolvedSessionName,
-    });
-
-    session.alive = true;
-
-    // Remote health probe 설정
-    session.probe?.stop();
-    const probe = createRemoteProbe(
-      {
-        host,
-        paneTarget: resolvedPane,
-        sessionName: resolvedSessionName,
-      },
-      {
-        ...probeOpts,
-        onProbe: (result) => handleProbeResult(session, result),
-      },
-    );
-    session.probe = probe;
-    probe.start();
-  }
-
-  /**
-   * 모든 세션이 terminal이면 auto-shutdown.
-   */
-  function maybeAutoShutdown() {
-    if (shuttingDown) return;
-    const allTerminal = [...sessions.values()].every(
-      (s) => TERMINAL_STATES.has(s.state),
-    );
-    if (allTerminal && sessions.size > 0) {
-      emitter.emit('allCompleted');
-    }
-  }
-
-  // ── Public API ──────────────────────────────────────────────
-
-  /**
-   * 새 세션 spawn.
-   * @param {object} config
-   * @param {string} config.id — 세션 ID (unique)
-   * @param {'codex'|'gemini'|'claude'} config.agent
-   * @param {string} config.prompt
-   * @param {string} [config.profile]
-   * @param {string} [config.workdir]
-   * @param {string} [config.model]
-   * @param {boolean} [config.remote=false] — 원격 세션 여부
-   * @param {string} [config.host] — SSH 호스트 (remote=true 필수)
-   * @param {string} [config.paneTarget] — psmux pane target (remote용)
-   * @param {string} [config.sessionName] — psmux 세션 이름 (remote용)
-   * @param {function} [config.onCompleted] — 세션 완료 시 콜백 ({sessionId}) => void
-   * @returns {string} session ID
-   */
-  function spawnSession(config) {
-    if (shuttingDown) throw new Error('Conductor is shutting down');
-    if (!config.id) throw new Error('session id is required');
-    if (sessions.has(config.id)) throw new Error(`Session "${config.id}" already exists`);
-    if (config.remote && !config.host) throw new Error('host is required for remote sessions');
-
-    // broker lease (graceful — broker null if accounts.json absent)
-    let lease = null;
-    if (broker && config.agent && !config.remote) {
-      lease = broker.lease({ provider: config.agent });
-      if (lease === null) {
-        const eta = broker.nextAvailableEta(config.agent);
-        eventLog.append('broker_no_lease', {
-          session: config.id,
-          agent: config.agent,
-          eta: eta ? new Date(eta).toISOString() : 'unknown',
-        });
-        // 계정이 모두 cooldown이어도 세션 생성 자체는 유지한다.
-        // 로컬 테스트/단일 계정 없는 환경에서도 상태 머신이 일관되게 동작해야 한다.
-      }
-    }
-
-    // apply lease profile/env/auth to config (immutable — new object)
-    const resolvedConfig = lease
-      ? {
-          ...config,
-          profile: lease.profile ?? config.profile,
-          env: { ...(config.env || {}), ...(lease.env || {}) },
-          accountId: lease.id,
-        }
-      : config;
-
-    // auth file copy — broker resolved absolute path, conductor does the actual copy
-    if (lease?.mode === 'auth' && lease.authFile) {
-      const dests = config.agent === 'codex'
-        ? [join(homedir(), '.codex', 'auth.json')]
-        : [
-            join(homedir(), '.gemini', 'oauth_creds.json'),
-            join(homedir(), '.gemini', 'gemini-credentials.json'),
-          ];
-      for (const dest of dests) {
-        try {
-          mkdirSync(dirname(dest), { recursive: true });
-          copyFileSync(lease.authFile, dest);
-          eventLog.append('auth_copy', { session: config.id, agent: config.agent, dest });
-        } catch (err) {
-          eventLog.append('auth_copy_error', { session: config.id, dest, error: err.message });
-        }
-      }
-    }
-
-    // 원격 세션은 launcher 불필요 (이미 원격에서 실행 중)
-    const launcher = resolvedConfig.remote
-      ? null
-      : buildLauncher({
-          agent: resolvedConfig.agent,
-          profile: resolvedConfig.profile,
-          prompt: resolvedConfig.prompt,
-          workdir: resolvedConfig.workdir,
-          model: resolvedConfig.model,
-        });
-
-    const session = {
-      id: resolvedConfig.id,
-      config: resolvedConfig,
-      launcher,
-      state: STATES.INIT,
-      child: null,
-      probe: null,
-      alive: false,
-      restarts: 0,
-      outPath: null,
-      errPath: null,
-      createdAt: Date.now(),
-    };
-
-    sessions.set(resolvedConfig.id, session);
-
-    if (resolvedConfig.remote) {
-      startRemoteSession(session);
-    } else {
-      void respawnSession(session);
-    }
-    return resolvedConfig.id;
-  }
-
-  /**
-   * 세션 kill.
-   * @param {string} id
-   * @param {string} [reason]
-   */
-  async function killSession(id, reason = 'user_kill') {
-    const session = sessions.get(id);
-    if (!session) return;
-    if (TERMINAL_STATES.has(session.state)) return;
-
-    eventLog.append('kill', { session: id, reason });
-    await cleanupChild(session);
-    transition(session, STATES.FAILED, reason);
-    transition(session, STATES.DEAD, reason);
-  }
-
-  /**
-   * 세션에 stdin 입력 전송 (INPUT_WAIT 해소용).
-   * @param {string} id
-   * @param {string} text
-   */
-  function sendInput(id, text) {
-    const session = sessions.get(id);
-    if (!session) return false;
-
-    // 원격 세션 — stdin 미지원 (psmux send-keys는 별도 경로)
-    if (session.config.remote) {
-      eventLog.append('stdin_remote_unsupported', { session: id });
-      return false;
-    }
-
-    if (!session.child) return false;
-    try {
-      session.child.stdin.write(`${text}\n`);
-      eventLog.append('stdin', { session: id, text: text.slice(0, 100) });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * 전체 세션 스냅샷.
-   * @returns {object[]}
-   */
-  function getSnapshot() {
-    return [...sessions.values()].map((s) => ({
-      id: s.id,
-      agent: s.config.agent,
-      state: s.state,
-      pid: s.child?.pid || null,
-      remote: s.config.remote || false,
-      host: s.config.host || null,
-      restarts: s.restarts,
-      health: s.probe?.getStatus() || null,
-      outPath: s.outPath,
-      errPath: s.errPath,
-      createdAt: s.createdAt,
-    }));
-  }
-
-  /**
-   * Graceful shutdown — 전체 세션 종료.
-   */
-  async function shutdown(reason = 'shutdown') {
-    if (shuttingDown) return;
-    shuttingDown = true;
-
-    eventLog.append('shutdown', { reason, sessions: sessions.size });
-
-    const cleanups = [...sessions.values()]
-      .filter((s) => !TERMINAL_STATES.has(s.state))
-      .map(async (s) => {
-        s.probe?.stop();
-        await cleanupChild(s);
-        if (!TERMINAL_STATES.has(s.state)) {
-          transition(s, STATES.FAILED, reason);
-          transition(s, STATES.DEAD, reason);
-        }
-      });
-
-    await Promise.allSettled(cleanups);
-    await eventLog.flush();
-    await eventLog.close();
-    emitter.emit('shutdown');
-  }
-
-  // Shutdown traps
-  const onSignal = () => { void shutdown('signal'); };
-  process.on('SIGINT', onSignal);
-  process.on('SIGTERM', onSignal);
-
-  return Object.freeze({
-    spawnSession,
-    killSession,
-    sendInput,
-    getSnapshot,
-    shutdown,
-    on: emitter.on.bind(emitter),
-    off: emitter.off.bind(emitter),
-    get sessionCount() { return sessions.size; },
-    get isShuttingDown() { return shuttingDown; },
-    get eventLogPath() { return eventLog.filePath; },
-  });
-}
+// hub/team/conductor.mjs — 세션 오케스트레이션 Conductor
+// native-supervisor.mjs의 spawn/kill을 래핑하되, 상태 머신 + health probe +
+// auto-restart + event log를 추가하여 "조용한 실패"를 구조적으로 불가능하게 만든다.
+//
+// 기존 native-supervisor와의 차이:
+// 1. 상태 머신 (alive/dead → 7 states + 2 terminal)
+// 2. Health probe 4단계 (+ INPUT_WAIT 감지)
+// 3. Auto-restart (maxRestarts=3)
+// 4. JSONL event log (블랙박스 리코더)
+
+import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import {
+  copyFileSync,
+  createWriteStream,
+  mkdirSync,
+  readFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createRegistry } from "@triflux/core/mesh/mesh-registry.mjs";
+import { broker } from "@triflux/core/hub/account-broker.mjs";
+import {
+  __internal__ as dynamicRoutingInternal,
+  evaluateDynamicRoute,
+  isDynamicRoutingEnabled,
+} from "@triflux/core/hub/dynamic-routing-engine.mjs";
+import {
+  findProcessTree,
+  killProcessTree,
+  killProcessTreeSnapshot,
+} from "@triflux/core/hub/lib/process-utils.mjs";
+import { execFile, spawn } from "@triflux/core/hub/lib/spawn-trace.mjs";
+import { killProcess } from "@triflux/core/hub/platform.mjs";
+import { tryGetCachedSnapshot } from "@triflux/core/hub/routing-snapshot.mjs";
+import { createHubHealthChecker } from "./check-mcp-hub.mjs";
+import { createConductorMeshBridge } from "./conductor-mesh-bridge.mjs";
+import {
+  ensureConductorRegistry,
+  getConductorRegistry,
+} from "./conductor-registry.mjs";
+import { createEventLog } from "./event-log.mjs";
+import { buildSpawnSpecForMode, MODES } from "./execution-mode.mjs";
+import { extractCompletionPayload } from "./extract-completion-payload.mjs";
+import { createHealthProbe } from "./health-probe.mjs";
+import { buildLauncher } from "./launcher-template.mjs";
+import { createSentinelCapture } from "./sentinel-capture.mjs";
+import {
+  buildSynapseTaskSummary,
+  heartbeatSynapseSession,
+  registerSynapseSession,
+  unregisterSynapseSession,
+} from "./synapse-http.mjs";
+import { buildWorkerSandboxEnv } from "./worker-sandbox.mjs";
+
+/** 세션 상태 */
+export const STATES = Object.freeze({
+  INIT: "init",
+  STARTING: "starting",
+  HEALTHY: "healthy",
+  STALLED: "stalled",
+  INPUT_WAIT: "input_wait",
+  FAILED: "failed",
+  RESTARTING: "restarting",
+  DEAD: "dead",
+  COMPLETED: "completed",
+});
+
+/** 유효한 상태 전이 테이블 */
+const TRANSITIONS = Object.freeze({
+  [STATES.INIT]: [STATES.STARTING],
+  [STATES.STARTING]: [STATES.HEALTHY, STATES.FAILED, STATES.COMPLETED],
+  [STATES.HEALTHY]: [
+    STATES.STALLED,
+    STATES.INPUT_WAIT,
+    STATES.FAILED,
+    STATES.COMPLETED,
+  ],
+  [STATES.STALLED]: [STATES.HEALTHY, STATES.FAILED],
+  [STATES.INPUT_WAIT]: [STATES.HEALTHY, STATES.FAILED],
+  [STATES.FAILED]: [STATES.RESTARTING, STATES.DEAD],
+  [STATES.RESTARTING]: [STATES.STARTING],
+  [STATES.DEAD]: [],
+  [STATES.COMPLETED]: [],
+});
+
+const TERMINAL_STATES = new Set([STATES.DEAD, STATES.COMPLETED]);
+const DEFAULT_MAX_RESTARTS = 3;
+const DEFAULT_GRACE_MS = 10_000;
+
+/**
+ * Auth 파일을 lease 소스에서 CLI 대상 경로로 복사.
+ * @param {object} lease — broker lease 객체 (mode, authFile 필수)
+ * @param {'codex'|'gemini'} agent
+ * @param {string} sessionId — 로깅용
+ * @param {object} eventLog — createEventLog 인스턴스
+ * @param {object} brokerInstance — AccountBroker 인스턴스
+ */
+function swapAuthFile(
+  lease,
+  agent,
+  sessionId,
+  eventLog,
+  brokerInstance,
+  targetEnv = {},
+) {
+  if (lease?.mode !== "auth" || !lease.authFile) return true;
+  if (
+    agent === "codex" &&
+    lease.id &&
+    brokerInstance &&
+    typeof brokerInstance.syncAuthToSource === "function"
+  ) {
+    const result = brokerInstance.syncAuthToSource(lease.id);
+    if (result?.copied || result?.reason === "up_to_date") {
+      eventLog.append("auth_copy", {
+        session: sessionId,
+        agent,
+        dest: result.sourcePath,
+        reason: result.reason,
+      });
+      return true;
+    }
+    eventLog.append("auth_copy_error", {
+      session: sessionId,
+      dest: result?.sourcePath || join(homedir(), ".codex", "auth.json"),
+      error: result?.reason || "sync_failed",
+    });
+    return false;
+  }
+  const targetHome = targetEnv.HOME || homedir();
+  const codexHome = targetEnv.CODEX_HOME || join(targetHome, ".codex");
+  const dests =
+    agent === "codex"
+      ? [join(codexHome, "auth.json")]
+      : [
+          join(targetHome, ".gemini", "oauth_creds.json"),
+          join(targetHome, ".gemini", "gemini-credentials.json"),
+        ];
+  let allOk = true;
+  for (const dest of dests) {
+    try {
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(lease.authFile, dest);
+      eventLog.append("auth_copy", { session: sessionId, agent, dest });
+    } catch (err) {
+      allOk = false;
+      eventLog.append("auth_copy_error", {
+        session: sessionId,
+        dest,
+        error: err.message,
+      });
+    }
+  }
+  return allOk;
+}
+
+/**
+ * Conductor 팩토리.
+ * @param {object} opts
+ * @param {string} opts.logsDir — 이벤트 로그 디렉토리
+ * @param {number} [opts.maxRestarts=3]
+ * @param {number} [opts.graceMs=10000] — shutdown grace period
+ * @param {object} [opts.probeOpts] — health-probe 옵션 오버라이드
+ * @param {object} [opts.broker] — AccountBroker 인스턴스 (tierFallback 구독용)
+ * @returns {Conductor}
+ */
+/**
+ * Conductor 생성.
+ * @param {object} [opts]
+ * @param {object} [opts.deps] — 의존성 주입 (테스트용 mock 지원)
+ * @param {Function} [opts.deps.execFile] — execFile 오버라이드
+ * @param {Function} [opts.deps.spawn] — spawn 오버라이드 (로컬/원격 child process 모두)
+ */
+export function createConductor(opts = {}) {
+  const spawnFn = opts.deps?.spawn || spawn;
+  const processUtils = {
+    killProcessTree: opts.deps?.killProcessTree || killProcessTree,
+    killProcessTreeSnapshot:
+      opts.deps?.killProcessTreeSnapshot || killProcessTreeSnapshot,
+    findProcessTree: opts.deps?.findProcessTree || findProcessTree,
+  };
+  const {
+    logsDir,
+    maxRestarts = DEFAULT_MAX_RESTARTS,
+    graceMs = DEFAULT_GRACE_MS,
+    probeOpts = {},
+    broker: optsBroker,
+  } = opts;
+
+  if (!logsDir) throw new Error("logsDir is required");
+  mkdirSync(logsDir, { recursive: true });
+
+  const emitter = new EventEmitter();
+  const sessions = new Map();
+  let shuttingDown = false;
+  const publicApi = null;
+  const synapseOpts = {
+    baseUrl: opts.synapseBaseUrl,
+    fetchImpl: opts.synapseFetch,
+  };
+  const getActiveBroker = () => optsBroker ?? broker;
+
+  function buildSynapseMeta(session, state = session.state, reason = "") {
+    return {
+      sessionId: session.id,
+      host:
+        typeof session.config.host === "string" &&
+        session.config.host.length > 0
+          ? session.config.host
+          : "local",
+      taskSummary: buildSynapseTaskSummary(session.config.prompt),
+      status: state,
+      reason,
+      isRemote: Boolean(session.config.remote),
+    };
+  }
+
+  // 공유 event log (모든 세션 이벤트를 하나의 JSONL에)
+  const eventLog = createEventLog(join(logsDir, "conductor-events.jsonl"));
+
+  /**
+   * 세션 상태 전이.
+   * @param {object} session
+   * @param {string} nextState
+   * @param {string} [reason]
+   */
+  function transition(session, nextState, reason = "") {
+    const valid = TRANSITIONS[session.state] || [];
+    if (!valid.includes(nextState)) {
+      eventLog.append("invalid_transition", {
+        session: session.id,
+        from: session.state,
+        to: nextState,
+        reason,
+      });
+      return false;
+    }
+
+    const prev = session.state;
+    session.state = nextState;
+
+    eventLog.append("stateChange", {
+      session: session.id,
+      from: prev,
+      to: nextState,
+      reason,
+      restarts: session.restarts,
+    });
+
+    emitter.emit("stateChange", {
+      sessionId: session.id,
+      from: prev,
+      to: nextState,
+      reason,
+    });
+
+    if (nextState === STATES.HEALTHY) {
+      registerSynapseSession(
+        buildSynapseMeta(session, nextState, reason),
+        synapseOpts,
+      );
+    }
+    heartbeatSynapseSession(
+      session.id,
+      buildSynapseMeta(session, nextState, reason),
+      synapseOpts,
+    );
+    if (nextState === STATES.COMPLETED || nextState === STATES.DEAD) {
+      unregisterSynapseSession(session.id, synapseOpts);
+    }
+
+    // Terminal state cleanup
+    if (TERMINAL_STATES.has(nextState)) {
+      session.probe?.stop();
+      getConductorRegistry()?.unregister?.(session.id, publicApi);
+    }
+
+    return true;
+  }
+
+  /**
+   * 프로세스를 강제 종료.
+   * Windows: taskkill /T /F /PID (프로세스 트리). POSIX: SIGKILL.
+   */
+  function forceKill(pid) {
+    if (!pid || pid <= 0) return;
+    killProcess(pid, {
+      signal: "SIGKILL",
+      tree: true,
+      force: true,
+      timeout: 5000,
+    });
+  }
+
+  /**
+   * 원격 세션의 psmux 세션을 SSH 경유로 kill.
+   * fire-and-forget: 실패해도 에러 전파 안 함.
+   */
+  function killRemoteSession(session) {
+    const host = session.config.host;
+    if (!host) return;
+    let sshUser = session.config.sshUser;
+    let sshIp = host;
+    // hosts.json에서 ssh_user/IP 해결
+    try {
+      const hostsPath = join(
+        opts.repoRoot || process.cwd(),
+        "references",
+        "hosts.json",
+      );
+      const hosts = JSON.parse(readFileSync(hostsPath, "utf8"));
+      const hostCfg = hosts.hosts?.[host];
+      if (hostCfg) {
+        sshUser = sshUser || hostCfg.ssh_user;
+        sshIp = hostCfg.tailscale?.ip || host;
+      }
+    } catch {
+      /* hosts.json 없으면 fallback */
+    }
+    if (!sshUser) return;
+    const execFn = opts.deps?.execFile || execFile;
+    execFn(
+      "ssh",
+      [`${sshUser}@${sshIp}`, "psmux", "kill-session", "-t", session.id],
+      { timeout: 10_000, reason: "conductor:killRemoteSession" },
+      () => {},
+    );
+    eventLog.append("remote_kill", {
+      session: session.id,
+      host,
+      sshUser,
+      sshIp,
+    });
+  }
+
+  /**
+   * 단일 세션의 child process를 정리.
+   * 원격 세션은 SSH 경유 psmux kill-session으로 정리.
+   */
+  async function cleanupChild(session) {
+    session.probe?.stop();
+
+    // 원격 세션 — SSH 경유 psmux kill-session
+    if (session.config.remote) {
+      killRemoteSession(session);
+      return;
+    }
+
+    const child = session.child;
+    if (!child) return;
+
+    const pid = child.pid;
+    if (!pid) return;
+
+    try {
+      if (session.descendantSnapshot?.length > 0) {
+        processUtils.killProcessTreeSnapshot(session.descendantSnapshot);
+      }
+    } catch {
+      /* best-effort cleanup */
+    }
+
+    if (!session.alive) return;
+
+    // SIGTERM 먼저
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      /* already dead */
+    }
+
+    // Grace period 대기
+    const exited = await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        resolve(false);
+      }, graceMs);
+      child.once("exit", () => {
+        clearTimeout(timer);
+        resolve(true);
+      });
+    });
+
+    if (!exited) {
+      try {
+        processUtils.killProcessTree(pid);
+      } catch {
+        forceKill(pid);
+      }
+      session.alive = false;
+    }
+  }
+
+  /**
+   * Health probe 콜백 — probe 결과에 따라 상태 전이 판단.
+   */
+  function handleProbeResult(session, result) {
+    if (TERMINAL_STATES.has(session.state)) return;
+    if (session.state === STATES.INIT || session.state === STATES.RESTARTING)
+      return;
+
+    eventLog.append("health", {
+      session: session.id,
+      ...result,
+    });
+
+    // L0 실패 — 로컬: exit handler에서 처리. 원격: probe가 유일한 감지 수단.
+    if (result.l0 === "fail") {
+      if (session.config.remote) {
+        handleFailure(session, "remote_L0_fail");
+      }
+      return;
+    }
+
+    // L3 completed (원격 완료 토큰 감지)
+    if (result.l3 === "completed" && session.config.remote) {
+      transition(session, STATES.COMPLETED, "remote_completion_token");
+      emitter.emit("completed", { sessionId: session.id });
+      if (typeof session.config.onCompleted === "function") {
+        session.config.onCompleted({ sessionId: session.id });
+      }
+      maybeAutoShutdown();
+      return;
+    }
+
+    // L1 INPUT_WAIT 감지
+    if (result.l1 === "input_wait" && session.state === STATES.HEALTHY) {
+      transition(
+        session,
+        STATES.INPUT_WAIT,
+        `input_wait:${result.inputWaitPattern}`,
+      );
+      emitter.emit("inputWait", {
+        sessionId: session.id,
+        pattern: result.inputWaitPattern,
+      });
+      return;
+    }
+
+    // INPUT_WAIT → output 재개 시 HEALTHY 복귀
+    if (session.state === STATES.INPUT_WAIT && result.l1 === "ok") {
+      transition(session, STATES.HEALTHY, "output_resumed");
+      return;
+    }
+
+    // L1 stall
+    if (result.l1 === "stall" && session.state === STATES.HEALTHY) {
+      transition(session, STATES.STALLED, "L1_stall");
+      return;
+    }
+
+    // STALLED → output 재개 시 HEALTHY 복귀
+    if (session.state === STATES.STALLED && result.l1 === "ok") {
+      transition(session, STATES.HEALTHY, "output_resumed");
+      return;
+    }
+
+    // L3 timeout (아직 STARTING 상태)
+    if (result.l3 === "timeout" && session.state === STATES.STARTING) {
+      handleFailure(session, "L3_timeout");
+      return;
+    }
+
+    // STARTING → L0 ok + L3 ok → HEALTHY
+    if (
+      session.state === STATES.STARTING &&
+      result.l0 === "ok" &&
+      result.l3 === "ok"
+    ) {
+      transition(session, STATES.HEALTHY, "probe_healthy");
+      return;
+    }
+
+    // STARTING → L0 ok (L3 아직 미판정) → STARTING 유지 (대기)
+  }
+
+  /**
+   * 실패 처리 — restart 또는 DEAD.
+   */
+  async function handleFailure(session, reason) {
+    if (TERMINAL_STATES.has(session.state)) return;
+
+    transition(session, STATES.FAILED, reason);
+
+    if (session.restarts < maxRestarts) {
+      transition(
+        session,
+        STATES.RESTARTING,
+        `restart_${session.restarts + 1}/${maxRestarts}`,
+      );
+      session.restarts += 1;
+      const backoffMs = Math.min(1000 * 2 ** (session.restarts - 1), 30_000);
+      session._respawnTimer = setTimeout(() => {
+        session._respawnTimer = null;
+        if (session.config.remote) {
+          startRemoteSession(session);
+        } else {
+          void respawnSession(session);
+        }
+      }, backoffMs);
+    } else {
+      await cleanupChild(session);
+      transition(session, STATES.DEAD, `maxRestarts(${maxRestarts})_exceeded`);
+      emitter.emit("dead", { sessionId: session.id, reason });
+
+      // broker release on final death
+      const activeBroker = getActiveBroker();
+      if (activeBroker && session.config.accountId) {
+        activeBroker.release(session.config.accountId, {
+          ok: false,
+          failureMode: session.lastFailureMode,
+        });
+        if (session.lastFailureMode === "rate_limited") {
+          activeBroker.markRateLimited(session.config.accountId, 5 * 60 * 1000);
+        }
+      }
+    }
+  }
+
+  /**
+   * 세션의 child process를 (재)시작.
+   */
+  async function respawnSession(session) {
+    // 기존 child 정리
+    await cleanupChild(session);
+
+    transition(
+      session,
+      STATES.STARTING,
+      session.restarts > 0 ? "respawn" : "initial",
+    );
+
+    const launcher = session.launcher;
+    const outPath = join(logsDir, `${session.id}.out.log`);
+    const errPath = join(logsDir, `${session.id}.err.log`);
+    mkdirSync(logsDir, { recursive: true });
+
+    const outWs = createWriteStream(outPath, { flags: "a" });
+    const errWs = createWriteStream(errPath, { flags: "a" });
+
+    let outputBytes = 0;
+    let recentOutput = "";
+    // #115 F7 wiring: stdout-only tail for completion payload extraction.
+    let stdoutTail = "";
+    // #125: sentinel-framed capture (preferred over the 16 KiB tail; survives
+    // payloads larger than the sliding window).
+    const sentinelCapture = createSentinelCapture();
+
+    const spawnCwd = session.config.workdir || launcher.cwd || undefined;
+    const spawnSpec = buildSpawnSpecForMode(MODES.HEADLESS, {
+      cli: session.config.agent,
+      prompt: session.config.prompt,
+      profile: session.config.profile,
+      model: session.config.model,
+      mcpServers: session.config.mcpServers,
+      resolveCommand: opts.deps?.resolveCliExecutable,
+    });
+
+    // #90 branch guard: shard spawn cwd가 main 브랜치면 즉시 abort.
+    // swarm shard는 반드시 shard 전용 worktree 브랜치에서 실행되어야 한다.
+    // cwd fallback으로 main working tree에 떨어진 경우 차단.
+    if (session.config.branchGuard && spawnCwd) {
+      try {
+        const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+          cwd: spawnCwd,
+          encoding: "utf8",
+          windowsHide: true,
+          timeout: 5_000,
+        });
+        const curBranch = String(r.stdout || "").trim();
+        if (curBranch === "main" || curBranch === "master") {
+          eventLog.append("branch_guard_refused", {
+            session: session.id,
+            cwd: spawnCwd,
+            branch: curBranch,
+          });
+          handleFailure(session, `branch_guard:${curBranch}_refused`);
+          return;
+        }
+      } catch (err) {
+        eventLog.append("branch_guard_probe_failed", {
+          session: session.id,
+          cwd: spawnCwd,
+          error: err.message,
+        });
+        // 프로브 실패는 비차단 — git 미설치/non-repo 환경 대응
+      }
+    }
+
+    const spawnEnv = {
+      ...process.env,
+      ...launcher.env,
+      ...(session.config.env || {}),
+      ...(session.config.branchGuard ? { TRIFLUX_GIT_BRANCH_GUARD: "1" } : {}),
+    };
+    if (session.config.workerSandbox?.root) {
+      eventLog.append("worker_sandbox_env", {
+        session: session.id,
+        root: session.config.workerSandbox.root,
+        codeHomePreserved: Boolean(spawnEnv.CODEX_HOME),
+      });
+    }
+
+    let child;
+    try {
+      child = spawnFn(spawnSpec.command, spawnSpec.args, {
+        shell: false,
+        cwd: spawnCwd,
+        env: spawnEnv,
+        reason: `conductor:respawnSession:${session.id}`,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (err) {
+      eventLog.append("spawn_error", {
+        session: session.id,
+        error: err.message,
+        cwd: spawnCwd || null,
+        command: spawnSpec.command,
+      });
+      handleFailure(session, `spawn_error:${err.message}`);
+      return;
+    }
+
+    session.child = child;
+    session.outPath = outPath;
+    session.errPath = errPath;
+    session.descendantSnapshot = [];
+
+    // #116-C: spawnSpec.stdinPrompt 가 true 면 codex 의 oh-my-codex hook
+    // (macOS) 가 매우 긴 argv-inline prompt 에서 SessionStart Failed → exit 1
+    // 회귀를 유발하므로 prompt 를 stdin write 로 분리해서 전달한다.
+    // stdinPrompt 없으면 기존 흐름 — codex "Reading additional input..." 대기
+    // 방지를 위해 stdin 즉시 닫기.
+    if (child.stdin) {
+      if (spawnSpec.stdinPrompt && typeof spawnSpec.prompt === "string") {
+        try {
+          child.stdin.write(spawnSpec.prompt);
+        } catch (err) {
+          eventLog.append("spawn_stdin_write_error", {
+            session: session.id,
+            error: err.message,
+          });
+        }
+      }
+      child.stdin.end();
+    }
+
+    eventLog.append("spawn", {
+      session: session.id,
+      agent: session.config.agent,
+      pid: child.pid,
+      command: spawnSpec.command,
+      args: spawnSpec.args,
+      legacyCommand: launcher.command,
+      restart: session.restarts,
+    });
+
+    if (session._descendantSnapshotTimer) {
+      clearTimeout(session._descendantSnapshotTimer);
+    }
+    session._descendantSnapshotTimer = setTimeout(() => {
+      session._descendantSnapshotTimer = null;
+      if (session.child !== child) return;
+      try {
+        session.descendantSnapshot = processUtils.findProcessTree(child.pid);
+      } catch {
+        /* best-effort snapshot */
+      }
+    }, 200);
+
+    // stdout+stderr 통합 추적 (F3 해결: stderr만 출력되는 경우도 advancing 판정)
+    const trackOutput = (buf) => {
+      outputBytes += buf.length;
+      const txt = String(buf);
+      // 최근 2KB만 유지 (INPUT_WAIT 패턴 감지용)
+      recentOutput += txt;
+      if (recentOutput.length > 2048) {
+        recentOutput = recentOutput.slice(-2048);
+      }
+    };
+
+    child.stdout?.on("data", (buf) => {
+      outWs.write(buf);
+      trackOutput(buf);
+      const text = buf.toString("utf8");
+      stdoutTail = (stdoutTail + text).slice(-16384);
+      sentinelCapture.push(text);
+    });
+    child.stderr?.on("data", (buf) => {
+      errWs.write(buf);
+      trackOutput(buf);
+    });
+
+    child.on("exit", (code, signal) => {
+      session.alive = false;
+      if (session._descendantSnapshotTimer) {
+        clearTimeout(session._descendantSnapshotTimer);
+        session._descendantSnapshotTimer = null;
+      }
+      try {
+        outWs.end();
+      } catch {
+        /* ignore */
+      }
+      try {
+        errWs.end();
+      } catch {
+        /* ignore */
+      }
+
+      eventLog.append("exit", {
+        session: session.id,
+        code,
+        signal,
+        restart: session.restarts,
+      });
+
+      if (TERMINAL_STATES.has(session.state)) return;
+      if (shuttingDown) return;
+
+      if (code === 0 && !signal) {
+        transition(session, STATES.COMPLETED, "exit_0");
+        // #125 Codex R1 MEDIUM: if sentinel capture overflowed past maxBytes
+        // and lost its BEGIN marker, do NOT fall back to stdoutTail/brace-scan
+        // — the worker tried sentinel protocol and the payload was clearly
+        // unbounded. Surface as "no payload" rather than silent partial.
+        let extracted;
+        if (sentinelCapture.isOverflow()) {
+          extracted = null;
+        } else {
+          const sentinelSnapshot = sentinelCapture.snapshot();
+          extracted = extractCompletionPayload(sentinelSnapshot || stdoutTail);
+        }
+        const completionPayload = extracted ? extracted.payload : undefined;
+        emitter.emit("completed", { sessionId: session.id, completionPayload });
+        if (typeof session.config.onCompleted === "function") {
+          session.config.onCompleted({
+            sessionId: session.id,
+            completionPayload,
+          });
+        }
+        const activeBroker = getActiveBroker();
+        if (activeBroker && session.config.accountId) {
+          activeBroker.release(session.config.accountId, { ok: true });
+        }
+      } else {
+        // detect rate_limited from recent output before handleFailure
+        if (
+          /(rate.?limit|quota|throttl|too.many.requests|429|usage.limit)/iu.test(
+            recentOutput,
+          )
+        ) {
+          session.lastFailureMode = "rate_limited";
+        }
+        handleFailure(session, `exit_code:${code},signal:${signal}`);
+      }
+
+      maybeAutoShutdown();
+    });
+
+    child.on("error", (err) => {
+      session.alive = false;
+      if (session._descendantSnapshotTimer) {
+        clearTimeout(session._descendantSnapshotTimer);
+        session._descendantSnapshotTimer = null;
+      }
+      eventLog.append("child_error", {
+        session: session.id,
+        error: err.message,
+      });
+      if (!shuttingDown && !TERMINAL_STATES.has(session.state)) {
+        handleFailure(session, `child_error:${err.message}`);
+      }
+    });
+
+    session.alive = true;
+
+    // Health probe 설정
+    session.probe?.stop();
+    const probe = createHealthProbe(
+      {
+        get pid() {
+          return child.pid;
+        },
+        get alive() {
+          return session.alive;
+        },
+        getOutputBytes: () => outputBytes,
+        getRecentOutput: () => recentOutput,
+      },
+      {
+        ...probeOpts,
+        // #165: default off → on. atomic write (#162) 로 race 제거됨.
+        // opt-out: TFX_PROBE_WRITE_STATE=0 명시.
+        writeStateFile:
+          probeOpts.writeStateFile ?? process.env.TFX_PROBE_WRITE_STATE !== "0",
+        // #168 P3: L2 (hub /health) checker wiring. probeOpts 가 명시 주입하면
+        // 그걸 우선. 아니면 TFX_PROBE_L2=0 로 opt-out. 나머지 경우 hub URL 기반
+        // default checker 주입 → deriveState 가 `mcp_initializing` 라벨을 생산 →
+        // heartbeat (read_probe_state) 가 probe-grace 분기로 감.
+        enableL2: probeOpts.enableL2 ?? process.env.TFX_PROBE_L2 !== "0",
+        checkMcp:
+          probeOpts.checkMcp ||
+          (process.env.TFX_PROBE_L2 === "0"
+            ? undefined
+            : createHubHealthChecker({ hubUrl: process.env.TFX_HUB_URL })),
+        onProbe: (result) => handleProbeResult(session, result),
+      },
+    );
+    session.probe = probe;
+    probe.start();
+  }
+
+  /**
+   * 원격 세션 시작 — SSH child process로 직접 실행.
+   * psmux 불필요. 원격 호스트에서 claude -p 를 SSH 경유로 실행하고
+   * 로컬 child process로 관리한다.
+   */
+  function startRemoteSession(session) {
+    transition(session, STATES.STARTING, "remote_initial");
+
+    const { host, prompt, agent, workdir: remoteWorkdir } = session.config;
+
+    // SSH args를 배열로 구성하여 셸 이스케이프 문제 회피
+    const cdPrefix = remoteWorkdir ? `cd ${remoteWorkdir} && ` : "";
+
+    let remoteBin;
+    if (agent === "claude") {
+      remoteBin = "claude --output-format text";
+    } else if (agent === "gemini") {
+      remoteBin = "gemini -y";
+    } else {
+      remoteBin =
+        "codex exec -s danger-full-access --dangerously-bypass-approvals-and-sandbox";
+    }
+
+    // prompt는 stdin으로 전달 — 셸 이스케이프 문제 완전 회피
+    const sshArgs = [
+      "-o",
+      "ConnectTimeout=30",
+      "-o",
+      "BatchMode=yes",
+      host,
+      `${cdPrefix}${remoteBin}`,
+    ];
+
+    const sshCmd = `ssh ${sshArgs.join(" ")}`;
+
+    eventLog.append("remote_start", {
+      session: session.id,
+      host,
+      command: sshCmd,
+    });
+
+    const outPath = join(logsDir, `${session.id}.out.log`);
+    const errPath = join(logsDir, `${session.id}.err.log`);
+    const outWs = createWriteStream(outPath, { flags: "a" });
+    const errWs = createWriteStream(errPath, { flags: "a" });
+
+    let child;
+    try {
+      child = spawnFn("ssh", sshArgs, {
+        env: process.env,
+        reason: `conductor:remoteSession:${session.id}`,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (err) {
+      eventLog.append("spawn_error", {
+        session: session.id,
+        error: err.message,
+      });
+      handleFailure(session, `spawn_error:${err.message}`);
+      return;
+    }
+
+    session.child = child;
+    session.outPath = outPath;
+    session.errPath = errPath;
+    session.alive = true;
+
+    // stdin으로 프롬프트 전달 — 셸 이스케이프 완전 우회
+    if (child.stdin) {
+      child.stdin.write(prompt);
+      child.stdin.end();
+    }
+
+    eventLog.append("spawn", {
+      session: session.id,
+      agent,
+      pid: child.pid,
+      command: sshCmd,
+      remote: true,
+      host,
+    });
+
+    // stdout/stderr 추적 (recentOutput으로 rate_limit 패턴 감지 가능)
+    let outputBytes = 0;
+    let recentOutput = "";
+    // #115 F7 wiring: stdout-only tail for completion payload extraction.
+    let stdoutTail = "";
+    // #125: sentinel-framed capture (preferred over the 16 KiB tail).
+    const sentinelCapture = createSentinelCapture();
+    const trackOutput = (buf) => {
+      outputBytes += buf.length;
+      const text = buf.toString("utf8");
+      recentOutput = (recentOutput + text).slice(-2000);
+    };
+
+    child.stdout?.on("data", (buf) => {
+      trackOutput(buf);
+      outWs.write(buf);
+      const text = buf.toString("utf8");
+      stdoutTail = (stdoutTail + text).slice(-16384);
+      sentinelCapture.push(text);
+    });
+    child.stderr?.on("data", (buf) => {
+      trackOutput(buf);
+      errWs.write(buf);
+    });
+
+    // 상태를 healthy로 전이
+    transition(session, STATES.HEALTHY, "remote_ssh_spawned");
+
+    // Health probe — 주기적으로 출력 변화 체크 (F3 stall 감지)
+    let lastBytes = 0;
+    let stallChecks = 0;
+    const stallThreshold = probeOpts.stallChecks || 8; // 8 * intervalMs = stall
+    const healthInterval = setInterval(() => {
+      if (TERMINAL_STATES.has(session.state)) {
+        clearInterval(healthInterval);
+        return;
+      }
+      if (outputBytes > lastBytes) {
+        lastBytes = outputBytes;
+        stallChecks = 0;
+        if (session.state !== STATES.HEALTHY) {
+          transition(session, STATES.HEALTHY, "output_advancing");
+        }
+      } else {
+        stallChecks++;
+        if (stallChecks >= stallThreshold && session.state === STATES.HEALTHY) {
+          transition(session, STATES.STALLED, "remote_no_output");
+        }
+      }
+    }, probeOpts.intervalMs || 5000);
+
+    // exit 핸들러
+    child.once("exit", (code) => {
+      clearInterval(healthInterval);
+      outWs.end();
+      errWs.end();
+      session.alive = false;
+
+      eventLog.append("remote_exit", {
+        session: session.id,
+        code,
+        outputBytes,
+        host,
+      });
+
+      if (shuttingDown || TERMINAL_STATES.has(session.state)) return;
+
+      // 원격 세션은 broker lease를 사용하지 않으므로 release 불필요
+      // (spawnSession에서 config.remote === true일 때 lease 건너뜀)
+      if (code === 0) {
+        transition(session, STATES.COMPLETED, `exit_${code}`);
+        // #125 Codex R1 MEDIUM: same overflow guard as the local exit path.
+        let extracted;
+        if (sentinelCapture.isOverflow()) {
+          extracted = null;
+        } else {
+          const sentinelSnapshot = sentinelCapture.snapshot();
+          extracted = extractCompletionPayload(sentinelSnapshot || stdoutTail);
+        }
+        const completionPayload = extracted ? extracted.payload : undefined;
+        emitter.emit("completed", { sessionId: session.id, completionPayload });
+        if (typeof session.config.onCompleted === "function") {
+          session.config.onCompleted({
+            sessionId: session.id,
+            completionPayload,
+          });
+        }
+        maybeAutoShutdown();
+      } else {
+        handleFailure(session, `remote_exit_${code}`);
+      }
+    });
+
+    child.once("error", (err) => {
+      clearInterval(healthInterval);
+      outWs.end();
+      errWs.end();
+      eventLog.append("spawn_error", {
+        session: session.id,
+        error: err.message,
+      });
+      if (!shuttingDown && !TERMINAL_STATES.has(session.state)) {
+        handleFailure(session, `spawn_error:${err.message}`);
+      }
+    });
+  }
+
+  /**
+   * 모든 세션이 terminal이면 auto-shutdown.
+   */
+  function maybeAutoShutdown() {
+    if (shuttingDown) return;
+    const allTerminal = [...sessions.values()].every((s) =>
+      TERMINAL_STATES.has(s.state),
+    );
+    if (allTerminal && sessions.size > 0) {
+      emitter.emit("allCompleted");
+    }
+  }
+
+  // ── Public API ──────────────────────────────────────────────
+
+  /**
+   * 새 세션 spawn.
+   * @param {object} config
+   * @param {string} config.id — 세션 ID (unique)
+   * @param {'codex'|'gemini'|'claude'} config.agent
+   * @param {string} config.prompt
+   * @param {string} [config.profile]
+   * @param {string} [config.workdir]
+   * @param {string} [config.model]
+   * @param {boolean} [config.remote=false] — 원격 세션 여부
+   * @param {string} [config.host] — SSH 호스트 (remote=true 필수)
+   * @param {string} [config.paneTarget] — psmux pane target (remote용)
+   * @param {string} [config.sessionName] — psmux 세션 이름 (remote용)
+   * @param {function} [config.onCompleted] — 세션 완료 시 콜백 ({sessionId}) => void
+   * @returns {string} session ID
+   */
+  function spawnSession(config) {
+    if (shuttingDown) throw new Error("Conductor is shutting down");
+    if (!config.id) throw new Error("session id is required");
+    if (sessions.has(config.id))
+      throw new Error(`Session "${config.id}" already exists`);
+    if (config.remote && !config.host)
+      throw new Error("host is required for remote sessions");
+
+    // Phase 1 dynamic routing wire-up (opt-in env TRIFLUX_DYNAMIC_ROUTING).
+    // sync 로만 평가해서 broker.lease atomic 인변량 (commit 761fb7a8 — leased
+    // account = executing account) 을 깨지 않는다. snapshot 은 D-2 cache 의
+    // sync getter 만 사용 — cache miss 면 evaluateDynamicRoute 가 fail-closed
+    // 로 codex-default 를 반환한다.
+    if (
+      isDynamicRoutingEnabled(process.env) &&
+      !config.remote &&
+      config.agent
+    ) {
+      try {
+        const policy = dynamicRoutingInternal.loadPolicy();
+        const snapshot = tryGetCachedSnapshot();
+        const decision = evaluateDynamicRoute(
+          {
+            task_id: config.id,
+            team_size: 1,
+            agent_hint: config.agent,
+          },
+          snapshot || {},
+          policy,
+          { now: Date.now() },
+        );
+        const shard = decision?.shards?.[0];
+        if (shard?.cli && shard.cli !== config.agent) {
+          eventLog.append("dynamic_route_override", {
+            session: config.id,
+            original: config.agent,
+            override: shard.cli,
+            scenario: decision.scenario ?? "unknown",
+            decisionId: decision.decisionId ?? null,
+            snapshotAgeMs: decision.snapshotAgeMs ?? null,
+          });
+          config = { ...config, agent: shard.cli };
+        }
+      } catch (err) {
+        eventLog.append("dynamic_route_error", {
+          session: config.id,
+          error: err?.message || String(err),
+        });
+      }
+    }
+
+    // broker lease (graceful — broker null if accounts.json absent)
+    let lease = null;
+    const activeBroker = getActiveBroker();
+    if (activeBroker && config.agent && !config.remote) {
+      lease = activeBroker.lease({ provider: config.agent });
+      if (lease === null) {
+        const eta = activeBroker.nextAvailableEta(config.agent);
+        eventLog.append("broker_no_lease", {
+          session: config.id,
+          agent: config.agent,
+          eta: eta ? new Date(eta).toISOString() : "unknown",
+        });
+        // 계정이 모두 cooldown이어도 세션 생성 자체는 유지한다.
+        // 로컬 테스트/단일 계정 없는 환경에서도 상태 머신이 일관되게 동작해야 한다.
+      }
+    }
+
+    // apply lease profile/env/auth to config (immutable — new object)
+    const leaseEnv =
+      lease?.authFile && config.agent === "codex"
+        ? { ...(lease.env || {}), CODEX_HOME: dirname(lease.authFile) }
+        : lease?.env || {};
+
+    let resolvedConfig = lease
+      ? {
+          ...config,
+          profile: lease.profile ?? config.profile,
+          env: { ...(config.env || {}), ...leaseEnv },
+          accountId: lease.id,
+        }
+      : {
+          ...config,
+          env: { ...(config.env || {}) },
+        };
+
+    if (!resolvedConfig.remote) {
+      const sandbox = buildWorkerSandboxEnv({
+        cwd: resolvedConfig.workdir || process.cwd(),
+        sessionId: resolvedConfig.id,
+        env: { ...process.env, ...(resolvedConfig.env || {}) },
+      });
+      resolvedConfig = {
+        ...resolvedConfig,
+        env: { ...(resolvedConfig.env || {}), ...sandbox.env },
+        workerSandbox: sandbox.disabled
+          ? { disabled: true }
+          : { root: sandbox.root, home: sandbox.home },
+      };
+    }
+
+    // auth file copy — broker resolved absolute path, conductor does the actual copy
+    swapAuthFile(
+      lease,
+      config.agent,
+      config.id,
+      eventLog,
+      activeBroker,
+      resolvedConfig.env,
+    );
+
+    // 원격 세션은 launcher 불필요 (이미 원격에서 실행 중)
+    const launcher = resolvedConfig.remote
+      ? null
+      : buildLauncher({
+          agent: resolvedConfig.agent,
+          profile: resolvedConfig.profile,
+          prompt: resolvedConfig.prompt,
+          workdir: resolvedConfig.workdir,
+          model: resolvedConfig.model,
+        });
+
+    const session = {
+      id: resolvedConfig.id,
+      config: resolvedConfig,
+      launcher,
+      state: STATES.INIT,
+      child: null,
+      probe: null,
+      alive: false,
+      restarts: 0,
+      outPath: null,
+      errPath: null,
+      createdAt: Date.now(),
+      descendantSnapshot: [],
+    };
+
+    sessions.set(resolvedConfig.id, session);
+    getConductorRegistry()?.register?.(resolvedConfig.id, publicApi);
+
+    if (resolvedConfig.remote) {
+      startRemoteSession(session);
+    } else {
+      void respawnSession(session);
+    }
+    return resolvedConfig.id;
+  }
+
+  /**
+   * 세션 kill.
+   * @param {string} id
+   * @param {string} [reason]
+   */
+  async function killSession(id, reason = "user_kill") {
+    const session = sessions.get(id);
+    if (!session) return;
+    if (TERMINAL_STATES.has(session.state)) return;
+
+    if (session._respawnTimer) {
+      clearTimeout(session._respawnTimer);
+      session._respawnTimer = null;
+    }
+    eventLog.append("kill", { session: id, reason });
+    await cleanupChild(session);
+    transition(session, STATES.FAILED, reason);
+    transition(session, STATES.DEAD, reason);
+  }
+
+  /**
+   * 세션에 stdin 입력 전송 (INPUT_WAIT 해소용).
+   * @param {string} id
+   * @param {string} text
+   */
+  function sendInput(id, text) {
+    const session = sessions.get(id);
+    if (!session) return false;
+
+    // 원격 세션 — stdin 미지원 (psmux send-keys는 별도 경로)
+    if (session.config.remote) {
+      eventLog.append("stdin_remote_unsupported", { session: id });
+      return false;
+    }
+
+    if (!session.child) return false;
+    if (!session.child.stdin?.writable) return false;
+    try {
+      session.child.stdin.write(`${text}\n`);
+      eventLog.append("stdin", { session: id, text: text.slice(0, 100) });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 전체 세션 스냅샷.
+   * @returns {object[]}
+   */
+  function getSnapshot() {
+    return [...sessions.values()].map((s) => ({
+      id: s.id,
+      agent: s.config.agent,
+      state: s.state,
+      pid: s.child?.pid || null,
+      remote: s.config.remote || false,
+      host: s.config.host || null,
+      restarts: s.restarts,
+      health: s.probe?.getStatus() || null,
+      outPath: s.outPath,
+      errPath: s.errPath,
+      createdAt: s.createdAt,
+    }));
+  }
+
+  /**
+   * Graceful shutdown — 전체 세션 종료.
+   */
+  async function shutdown(reason = "shutdown") {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    eventLog.append("shutdown", { reason, sessions: sessions.size });
+
+    const cleanedSessionIds = new Set();
+    const cleanups = [...sessions.values()]
+      .filter((s) => {
+        if (cleanedSessionIds.has(s.id)) return false;
+        cleanedSessionIds.add(s.id);
+        return true;
+      })
+      .map(async (s) => {
+        if (s._respawnTimer) {
+          clearTimeout(s._respawnTimer);
+          s._respawnTimer = null;
+        }
+        if (s._descendantSnapshotTimer) {
+          clearTimeout(s._descendantSnapshotTimer);
+          s._descendantSnapshotTimer = null;
+        }
+        s.probe?.stop();
+        await cleanupChild(s);
+        if (!TERMINAL_STATES.has(s.state)) {
+          transition(s, STATES.FAILED, reason);
+          transition(s, STATES.DEAD, reason);
+        }
+      });
+
+    await Promise.allSettled(cleanups);
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+    if (brokerInstance && onTierFallback) {
+      brokerInstance.removeListener("tierFallback", onTierFallback);
+    }
+    if (conductor._meshBridge) conductor._meshBridge.detach();
+    await eventLog.flush();
+    await eventLog.close();
+    emitter.emit("shutdown");
+  }
+
+  // ── broker tierFallback 구독 ──────────────────────────────────
+  // 토큰 만료 등으로 상위 tier 계정이 불가능해지면, 활성 세션의 auth를 새 lease로 교체.
+  const brokerInstance = optsBroker ?? null;
+  const onTierFallback = brokerInstance
+    ? ({ provider }) => {
+        for (const session of sessions.values()) {
+          if (TERMINAL_STATES.has(session.state)) continue;
+          if (session.config.agent !== provider) continue;
+          if (session.config.remote) continue;
+
+          const newLease = brokerInstance.lease({ provider });
+          if (!newLease) continue;
+          if (newLease.authFile && provider === "codex") {
+            session.config.env = {
+              ...(session.config.env || {}),
+              CODEX_HOME: dirname(newLease.authFile),
+            };
+          }
+
+          swapAuthFile(
+            newLease,
+            provider,
+            session.id,
+            eventLog,
+            brokerInstance,
+            session.config.env,
+          );
+          eventLog.append("tier_fallback_swap", {
+            session: session.id,
+            agent: provider,
+            newAccount: newLease.id,
+          });
+        }
+      }
+    : null;
+
+  if (brokerInstance && onTierFallback) {
+    brokerInstance.on("tierFallback", onTierFallback);
+  }
+
+  // Shutdown traps
+  const onSignal = () => {
+    void shutdown("signal");
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+
+  const conductor = {
+    spawnSession,
+    killSession,
+    sendInput,
+    getSnapshot,
+    getMeshRegistry() {
+      return this._meshRegistry || null;
+    },
+    shutdown,
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+    get sessionCount() {
+      return sessions.size;
+    },
+    get isShuttingDown() {
+      return shuttingDown;
+    },
+    get eventLogPath() {
+      return eventLog.filePath;
+    },
+  };
+
+  if (opts.enableMesh !== false) {
+    try {
+      const registry = opts.meshRegistry || createRegistry();
+      const bridge = createConductorMeshBridge(conductor, registry);
+      bridge.attach();
+      conductor._meshBridge = bridge;
+      conductor._meshRegistry = registry;
+    } catch {
+      // mesh 실패해도 conductor 정상 동작
+    }
+  }
+
+  const frozenApi = Object.freeze(conductor);
+  ensureConductorRegistry();
+  return frozenApi;
+}