@cocorograph/hub-agent 0.7.32 → 0.7.33

package/src/hub-bundle.mjs

@@ -24,27 +24,41 @@ import { spawn } from "node:child_process"
 const HUB_AI_RULES_BEGIN = "<!-- BEGIN HUB-AI-RULES -->"
 const HUB_AI_RULES_END = "<!-- END HUB-AI-RULES -->"
 
-function resolveClaudeDir() {
-  return process.env.CLAUDE_DIR || path.join(os.homedir(), ".claude")
+// cli_kind ('claude' / 'codex') → 配置先ディレクトリ名 (Cockpit Codex 両対応
+// Stream A、2026-07-02)。Hub backend の hub_ai_views._CLI_DIR_NAME と対の
+// テーブル。既定 'claude' の挙動は完全に従来どおり (後方互換)。
+const _CLI_DIR_NAME = { claude: ".claude", codex: ".codex" }
+
+function resolveClaudeDir(cliKind = "claude") {
+  // CLAUDE_DIR env override は既存の claude 専用テスト/運用で使われているため
+  // cli_kind='claude' のときのみ効かせる (codex は CODEX_DIR で別途上書き可能)。
+  if (cliKind === "codex") {
+    return process.env.CODEX_DIR || path.join(os.homedir(), _CLI_DIR_NAME.codex)
+  }
+  return process.env.CLAUDE_DIR || path.join(os.homedir(), _CLI_DIR_NAME.claude)
 }
 
-function tokenPath() {
-  return path.join(resolveClaudeDir(), "scripts", ".hub_jwt.json")
+function tokenPath(cliKind = "claude") {
+  return path.join(resolveClaudeDir(cliKind), "scripts", ".hub_jwt.json")
 }
 
-function bundleUrl(hubUrl) {
-  return `${hubUrl.replace(/\/+$/, "")}/api/admin/hub-ai/setup-bundle/`
+function bundleUrl(hubUrl, cliKind = "claude") {
+  const base = `${hubUrl.replace(/\/+$/, "")}/api/admin/hub-ai/setup-bundle/`
+  return cliKind === "codex" ? `${base}?cli_kind=codex` : base
 }
 
 /**
  * Hub から bundle を fetch する。
+ * @param {{hubUrl: string, agentId: string, agentToken: string, fetchImpl?: Function,
+ *   cliKind?: 'claude'|'codex'}} args cliKind 省略時は 'claude'（既存呼び出し元は無改修で
+ *   従来どおり ~/.claude 向けバンドルを取得する）。
  * @returns {Promise<{ version: string, files: any[], post_install_commands?: any[], token?: any }>}
  */
-export async function fetchBundle({ hubUrl, agentId, agentToken, fetchImpl } = {}) {
+export async function fetchBundle({ hubUrl, agentId, agentToken, fetchImpl, cliKind = "claude" } = {}) {
   if (!hubUrl) throw new Error("fetchBundle requires hubUrl")
   if (!agentId || !agentToken) throw new Error("fetchBundle requires agentId + agentToken")
   const f = fetchImpl || globalThis.fetch
-  const res = await f(bundleUrl(hubUrl), {
+  const res = await f(bundleUrl(hubUrl, cliKind), {
     headers: {
       Authorization: `Bearer ${agentId}:${agentToken}`,
     },
@@ -62,40 +76,48 @@ export async function fetchBundle({ hubUrl, agentId, agentToken, fetchImpl } = {
   return res.json()
 }
 
-function isClaudeMdEntry(entry) {
+// cli_kind → 指示ファイル名 (Hub backend hub_ai_views._CONFIG_MD_FILENAME と対)。
+const _CONFIG_MD_FILENAME = { claude: "CLAUDE.md", codex: "AGENTS.md" }
+
+function isConfigMdEntry(entry, cliKind = "claude") {
+  const filename = _CONFIG_MD_FILENAME[cliKind] || _CONFIG_MD_FILENAME.claude
+  const dirName = _CLI_DIR_NAME[cliKind] || _CLI_DIR_NAME.claude
   return (
-    entry.path === "CLAUDE.md" ||
-    entry.path === "./CLAUDE.md" ||
-    entry.path === "~/.claude/CLAUDE.md"
+    entry.path === filename ||
+    entry.path === `./${filename}` ||
+    entry.path === `~/${dirName}/${filename}`
   )
 }
 
 /**
- * backend が返した bundle entry の path 文字列を `~/.claude/` 配下の絶対パスに
- * 展開する。
+ * backend が返した bundle entry の path 文字列を `~/.claude/` (または cliKind='codex'
+ * のとき `~/.codex/`) 配下の絶対パスに展開する。
  *
  * 受け付ける入力形式:
  *  - `./scripts/hub_helper.py`        — relative (legacy)
  *  - `scripts/hub_helper.py`          — relative (legacy bare)
- *  - `~/.claude/scripts/hub_helper.py` — `~/.claude/` プレフィックス付き (現行)
+ *  - `~/.claude/scripts/hub_helper.py` — `~/.claude/` プレフィックス付き (現行、
+ *    cliKind='codex' なら backend が `~/.codex/...` で返す)
  *
- * いずれの形式でも `<HOME>/.claude/scripts/hub_helper.py` に解決する。
+ * いずれの形式でも `<HOME>/<cliDir>/scripts/hub_helper.py` に解決する。
  *
  * 2026-05-27 までの実装は `~/.claude/` を strip せず `path.join(base, rel)` を
  * 呼んでいたため、`~` がリテラルディレクトリとして作成され
  * `<HOME>/.claude/~/.claude/scripts/...` という二重展開された壊れたパスに
  * ファイルが配置される事故が発生 (新規端末で hub-agent CLI 経由でセットアップ
  * すると、`readBundleVersion()` が正規パスを読めず bundle_version が null に
- * なる症状で顕在化)。
+ * なる症状で顕在化)。cli_kind 対応 (Stream A, 2026-07-02) でも同じ罠を踏まない
+ * よう、strip 対象を `~/.claude/` と `~/.codex/` の両方にする（cliKind に関わらず
+ * どちらの prefix が来ても正規化できる。通常は cliKind と一致するはず）。
  */
-function intoClaudeAbsolute(rel) {
-  const base = resolveClaudeDir()
-  // `./` / `~/.claude/` の二系統を strip して、純粋な `~/.claude/` 配下の
+function intoClaudeAbsolute(rel, cliKind = "claude") {
+  const base = resolveClaudeDir(cliKind)
+  // `./` / `~/.claude/` / `~/.codex/` の3系統を strip して、純粋な cliDir 配下の
   // サブパスに正規化してから join する。順序に依存しないよう両方を試す。
   let cleaned = rel.replace(/^\.\//, "")
-  cleaned = cleaned.replace(/^~\/\.claude\//, "")
-  // 末端で `~/.claude` (末尾スラッシュ無し) を渡された場合のために最終チェック。
-  if (cleaned === "~/.claude" || cleaned === "~") {
+  cleaned = cleaned.replace(/^~\/\.claude\//, "").replace(/^~\/\.codex\//, "")
+  // 末端で `~/.claude` / `~/.codex` (末尾スラッシュ無し) を渡された場合のために最終チェック。
+  if (cleaned === "~/.claude" || cleaned === "~/.codex" || cleaned === "~") {
     cleaned = ""
   }
   return path.join(base, cleaned)
@@ -111,25 +133,31 @@ function parseMode(mode) {
 }
 
 /**
- * Bundle の files[] を `~/.claude/<path>` に展開する。
+ * Bundle の files[] を `~/.claude/<path>`（cliKind='codex' なら `~/.codex/<path>`）に展開する。
+ *
+ * cliKind は明示指定しなければ `bundle.cli_kind`（backend が `_apply_role_templating`
+ * でレンダリングに使った値、fetchBundle のレスポンスに `cli_kind` として同梱される）から
+ * 自動判定し、それも無ければ 'claude' にフォールバックする（既存呼び出し元は無改修で
+ * 従来どおり動く）。
  * @returns {Promise<{ written: string[], skipped_same: string[], merged_claude_md: boolean }>}
  */
-export async function applyBundle({ bundle, logger } = {}) {
+export async function applyBundle({ bundle, logger, cliKind } = {}) {
   if (!bundle || !Array.isArray(bundle.files)) {
     throw new Error("applyBundle requires bundle.files[]")
   }
+  const kind = cliKind || bundle.cli_kind || "claude"
 
   const written = []
   const skippedSame = []
   let mergedClaudeMd = false
 
   for (const entry of bundle.files) {
-    const dest = intoClaudeAbsolute(entry.path)
+    const dest = intoClaudeAbsolute(entry.path, kind)
     const mode = parseMode(entry.mode)
     const content = entry.content ?? ""
 
-    if (isClaudeMdEntry(entry)) {
-      // CLAUDE.md は marker 範囲だけ置換、無ければ末尾追記
+    if (isConfigMdEntry(entry, kind)) {
+      // CLAUDE.md / AGENTS.md は marker 範囲だけ置換、無ければ末尾追記
       const result = await mergeClaudeMdMarkerBlock(dest, content, { logger })
       if (result.changed) {
         written.push(dest)
@@ -152,9 +180,9 @@ export async function applyBundle({ bundle, logger } = {}) {
     logger?.info({ dest, mode: mode.toString(8) }, "hub-bundle wrote file")
   }
 
-  // JWT を保存 (~/.claude/scripts/.hub_jwt.json)
+  // JWT を保存 (~/.claude/scripts/.hub_jwt.json、または ~/.codex/scripts/.hub_jwt.json)
   if (bundle.token) {
-    const tp = tokenPath()
+    const tp = tokenPath(kind)
     await fs.mkdir(path.dirname(tp), { recursive: true })
     await fs.writeFile(
       tp,
@@ -277,7 +305,7 @@ export async function applyMcpServers(bundle, { logger } = {}) {
   if (servers.length === 0) return { added: [], skipped: [] }
 
   // `claude` CLI の存在確認 (which / where 相当)。なければ no-op。
-  const claudeBin = await resolveClaudeBin()
+  const claudeBin = await resolveCliBin("claude")
   if (!claudeBin) {
     logger?.info("claude CLI が PATH に無いため MCP server 自動登録をスキップ")
     return { added: [], skipped: servers.map((s) => s.name) }
@@ -316,15 +344,60 @@ export async function applyMcpServers(bundle, { logger } = {}) {
 }
 
 /**
- * `claude` バイナリの絶対パスを返す。なければ null。
+ * Bundle response の `mcp_servers` を Codex CLI に登録する（Cockpit Codex 両対応
+ * Stream A2、2026-07-02）。`applyMcpServers`（Claude 版）と対称の役割。
+ *
+ * 実機確認済みコマンド（codex-cli 0.142.5）: `codex mcp add <name> --url <url>`。
+ * Claude の `--transport`/`--scope` に相当するオプションは無い（streamable HTTP
+ * 固定・scope 概念自体が無い、`codex mcp add --help` で確認済み）。
+ *
+ * ⚠️ Hub MCP は Bearer 静的トークンではなく OAuth 2.0 + PKCE（`claude mcp add
+ * --transport http` と同方式）。`codex mcp add` は登録のみで、認証は別途
+ * `codex mcp login <name>`（対話 OAuth）が必要と見込まれるが、headless agent
+ * から起動した codex app-server プロセス内でブラウザ OAuth ポップアップが
+ * どう解決されるかは未検証（A5 のライブ検証で確認。`codex login` 後に
+ * ユーザー自身が `codex mcp login hub`/`hub_staff` を一度実行する運用に
+ * なる可能性が高い）。
+ */
+export async function applyCodexMcpServers(bundle, { logger } = {}) {
+  const servers = Array.isArray(bundle?.mcp_servers) ? bundle.mcp_servers : []
+  if (servers.length === 0) return { added: [], skipped: [] }
+
+  const codexBin = await resolveCliBin("codex")
+  if (!codexBin) {
+    logger?.info("codex CLI が PATH に無いため MCP server 自動登録をスキップ")
+    return { added: [], skipped: servers.map((s) => s.name) }
+  }
+
+  const added = []
+  const skipped = []
+  for (const s of servers) {
+    if (!s?.name || !s?.url) {
+      skipped.push(s?.name || "<unnamed>")
+      continue
+    }
+    const argv = [codexBin, "mcp", "add", s.name, "--url", s.url]
+    try {
+      await runOnce(argv, { logger })
+      added.push(s.name)
+    } catch (err) {
+      logger?.warn({ name: s.name, err: err.message }, "codex mcp add failed")
+      skipped.push(s.name)
+    }
+  }
+  return { added, skipped }
+}
+
+/**
+ * `claude` / `codex` バイナリの絶対パスを返す。なければ null。
  * PATH を辿る (`which` / `where`) ことで fnm / nvm / homebrew / volta 等の
  * バージョンマネージャ配下にあるものも拾う。
  */
-async function resolveClaudeBin() {
+async function resolveCliBin(binName) {
   const isWindows = process.platform === "win32"
   const cmd = isWindows ? "where" : "which"
   return new Promise((resolve) => {
-    const child = spawn(cmd, ["claude"], { stdio: ["ignore", "pipe", "ignore"] })
+    const child = spawn(cmd, [binName], { stdio: ["ignore", "pipe", "ignore"] })
     let out = ""
     child.stdout?.on("data", (chunk) => {
       out += chunk.toString("utf-8")
@@ -340,10 +413,12 @@ async function resolveClaudeBin() {
 
 /**
  * fetch + apply + post_install + MCP server 自動登録をまとめて実行。
+ * cliKind='codex' で Codex 向け（`~/.codex/`、`codex mcp add`）に切り替わる
+ * （Stream A2、2026-07-02。既定 'claude' は完全に従来どおり）。
  */
-export async function syncBundle({ hubUrl, agentId, agentToken, logger, fetchImpl } = {}) {
-  const bundle = await fetchBundle({ hubUrl, agentId, agentToken, fetchImpl })
-  const result = await applyBundle({ bundle, logger })
+export async function syncBundle({ hubUrl, agentId, agentToken, logger, fetchImpl, cliKind = "claude" } = {}) {
+  const bundle = await fetchBundle({ hubUrl, agentId, agentToken, fetchImpl, cliKind })
+  const result = await applyBundle({ bundle, logger, cliKind })
   try {
     await runPostInstall(bundle, { logger })
   } catch (err) {
@@ -351,7 +426,9 @@ export async function syncBundle({ hubUrl, agentId, agentToken, logger, fetchImp
   }
   let mcp = { added: [], skipped: [] }
   try {
-    mcp = await applyMcpServers(bundle, { logger })
+    mcp = cliKind === "codex"
+      ? await applyCodexMcpServers(bundle, { logger })
+      : await applyMcpServers(bundle, { logger })
   } catch (err) {
     logger?.warn({ err: err.message }, "applyMcpServers failed (continuing)")
   }

package/src/main.mjs

@@ -87,12 +87,16 @@ import {
   setTmuxGlobalEnv,
   setTuiEffort,
   setTuiModel,
+  startTerminalMirror,
+  stopTerminalMirror,
 } from "./tmux.mjs"
 import { TuiPermissionBridge } from "./tui-permission-bridge.mjs"
 import { TuiViewerRegistry } from "./tui-viewer-registry.mjs"
 import { JsonlLiveWatchers } from "./jsonl-live-watchers.mjs"
 import {
   boundSessionId,
+  codexSessionUsages,
+  codexUsageForThread,
   contextWindowSize,
   getSessionUsages,
   getUsage,
@@ -358,10 +362,15 @@ export function kickSetupHubAi({
   spawnImpl,
   existsImpl,
   homedir,
+  cliKind = "claude",
 } = {}) {
   try {
     const home = homedir || os.homedir()
-    const setupScript = path.join(home, ".claude", "scripts", "setup_hub_ai.py")
+    // Cockpit Codex 両対応 (Stream A2, 2026-07-02): cliKind='codex' なら
+    // ~/.codex/scripts/setup_hub_ai.py（AGENTS.md/hooks.json 向けにテンプレート
+    // 済みの版）を kick する。既定 'claude' は完全に従来どおり。
+    const dirName = cliKind === "codex" ? ".codex" : ".claude"
+    const setupScript = path.join(home, dirName, "scripts", "setup_hub_ai.py")
     const exists = existsImpl || existsSync
     if (!exists(setupScript)) {
       logger?.info?.(
@@ -2964,6 +2973,90 @@ async function dispatch(msg, ctx) {
         }
         return
       }
+      case "terminal.mirror.start": {
+        // Cockpit Codex 両対応 Stream C (2026-07-03): チャット(SDK/app-server)の会話を
+        // 変えずに、ターミナルのペイン (普通のシェルのまま) へ読み取り専用の実況を
+        // 追加する。詳細は tmux.mjs の startTerminalMirror / session-mirror.mjs 参照。
+        //
+        // session_id はブラウザに要求しない。cwd から hub-agent 側でライブなチャット
+        // session を解決する (claudeBridge.liveSessionIdForCwd / codexBridge.sessions を
+        // cwd で検索)。これにより frontend は「今この cwd で実際に動いているチャット」を
+        // 正確に追従でき、古い/取り違えた session_id を渡すリスクが無い。
+        const request_id = msg.request_id
+        const sessionName = typeof msg.session_name === "string" ? msg.session_name : ""
+        const cwd = typeof msg.cwd === "string" ? msg.cwd : ""
+        const cliKind = msg.cli_kind === "codex" ? "codex" : "claude"
+        const reply = (payload) =>
+          ctx.client.send({
+            type: "terminal.mirror.start.result",
+            request_id,
+            session_name: sessionName,
+            ...payload,
+          })
+        if (!sessionName || !cwd) {
+          reply({ ok: false, error: "session_name / cwd は必須です" })
+          return
+        }
+        let sessionId = null
+        if (cliKind === "codex") {
+          for (const s of ctx.codexBridge?.sessions?.values() ?? []) {
+            if (s.cwd === cwd && s.threadId) {
+              sessionId = s.threadId
+              break
+            }
+          }
+        } else {
+          sessionId = ctx.claudeBridge?.liveSessionIdForCwd?.(cwd) || null
+        }
+        if (!sessionId) {
+          reply({
+            ok: false,
+            error: "この cwd で動作中のチャットセッションが見つかりません (先にチャットを開始してください)",
+          })
+          return
+        }
+        try {
+          const r = await startTerminalMirror(
+            sessionName,
+            { cwd, sessionId, cliKind },
+            { logger },
+          )
+          reply(r)
+        } catch (err) {
+          logger?.warn(
+            { err: err?.message, sessionName },
+            "terminal.mirror.start failed",
+          )
+          reply({ ok: false, error: err?.message || String(err) })
+        }
+        return
+      }
+      case "terminal.mirror.stop": {
+        const request_id = msg.request_id
+        const sessionName = typeof msg.session_name === "string" ? msg.session_name : ""
+        const reply = (payload) =>
+          ctx.client.send({
+            type: "terminal.mirror.stop.result",
+            request_id,
+            session_name: sessionName,
+            ...payload,
+          })
+        if (!sessionName) {
+          reply({ ok: false, error: "session_name は必須です" })
+          return
+        }
+        try {
+          const r = await stopTerminalMirror(sessionName, { logger })
+          reply(r)
+        } catch (err) {
+          logger?.warn(
+            { err: err?.message, sessionName },
+            "terminal.mirror.stop failed",
+          )
+          reply({ ok: false, error: err?.message || String(err) })
+        }
+        return
+      }
       case "claude.mcp.status":
       case "claude.mcp.reconnect":
       case "claude.mcp.authenticate":
@@ -3611,7 +3704,13 @@ async function dispatch(msg, ctx) {
       }
       case "skills.request": {
         try {
-          const skills = await listSkills({ sessionName: msg.session_name })
+          // Cockpit Codex 両対応 (Stream A3, 2026-07-02): browser が cli_kind を
+          // 添えれば Codex 向け skills (~/.codex/skills/) を返す。未指定は
+          // 従来どおり claude 向け。
+          const skills = await listSkills({
+            sessionName: msg.session_name,
+            cliKind: msg.cli_kind === "codex" ? "codex" : "claude",
+          })
           ctx.client.send({
             type: "skills.response",
             request_id: msg.request_id,
@@ -3667,11 +3766,37 @@ async function dispatch(msg, ctx) {
             getUsage(),
             getSessionUsages(),
           ])
+
+          // Codex 版 (Stream B3, 2026-07-03): rollout jsonl の token_count イベントから
+          // 5h/7d + context% を取る。⚠️ Codex の 5h/7d は ChatGPT/OpenAI サブスクリプション
+          // の残量であり、上の `usage` (Claude/Anthropic サブスクリプション) とは別契約の
+          // 別数値のため、`usage` にマージせず独立フィールド `codexUsage`/`codexSessions`
+          // として返す (frontend 側でどちらのアカウントの残量か混同しないため)。
+          let codexUsage = null
+          let codexSessions = []
+          if (ctx.codexBridge && ctx.codexBridge.sessions.size > 0) {
+            try {
+              const liveCodex = Array.from(ctx.codexBridge.sessions.values())
+                .filter((s) => s.threadId && s.cwd)
+                .map((s) => ({ sessionId: s.threadId, cwd: s.cwd, threadId: s.threadId }))
+              if (liveCodex.length > 0) {
+                // 5h/7d はアカウント全体の値 (どの live session から読んでも同じ契約の残量)
+                // なので、代表として最初の 1 件から取る。
+                codexUsage = await codexUsageForThread(liveCodex[0].threadId)
+                codexSessions = await codexSessionUsages(liveCodex)
+              }
+            } catch (err) {
+              ctx.logger?.debug?.({ err: err?.message }, "codex usage snapshot skipped")
+            }
+          }
+
           ctx.client.send({
             type: "usage.response",
             request_id: msg.request_id,
             usage,
             sessions,
+            codexUsage,
+            codexSessions,
           })
         } catch (err) {
           ctx.client.send({
@@ -3679,6 +3804,8 @@ async function dispatch(msg, ctx) {
             request_id: msg.request_id,
             usage: null,
             sessions: [],
+            codexUsage: null,
+            codexSessions: [],
             error: err.message,
           })
         }

package/src/session-mirror.mjs

@@ -0,0 +1,190 @@
+/**
+ * ターミナルへの「チャット追従ミラー」(Cockpit Codex 両対応 Stream C, 2026-07-03)。
+ *
+ * 背景: 2026-06-06 の `claude.tui.bind`（会話継続バインディング）以降、チャット
+ * (SDK/app-server) と TUI ペインは同一 session_id を同時ホストしない排他設計になった
+ * （DESIGN.md C7「二重ホスト防止」）。それ以前は両者が独立 session として並走していたが、
+ * 「別々の会話が同じ cwd で表示を取り合いパタパタする」実害があり意図的に廃止された。
+ *
+ * 本機能は「チャットの動作は一切変えず（今まで通り SDK/app-server が単独で会話を進める）、
+ * ターミナルのペインはユーザーが普通に使えるシェルのまま、そこにチャットの会話ログを
+ * 実況表示するだけの読み取り専用プロセス」を **バックグラウンドジョブとして** 追加する。
+ * ターミナル側は一切書き込まないため C7 のリスクには当たらない（同一ファイルへの
+ * 二重書込は発生しない。読むだけ）。
+ *
+ * 実行方式: `tmux.mjs` の `startTerminalMirror` が対象ペインへ `send-keys` で
+ * `hub-agent mirror ... & disown` を打ち込み、ペインの現在のシェルの子プロセスとして
+ * バックグラウンドで起動する（実機検証済み: 子プロセスの stdout はペインに自然に
+ * 割り込み表示され、ユーザーの入力行は破壊されない — 通常の Unix ターミナルで
+ * バックグラウンドジョブの出力を眺めながら作業するのと同じ挙動）。
+ */
+import { watchSessionFile } from "./claude-history-watch.mjs"
+import { jsonlPath } from "./claude-history.mjs"
+import { watchCodexRollout } from "./codex-rollout-watch.mjs"
+import { findCodexRolloutFile } from "./usage.mjs"
+
+// 依存追加を避けるため、chalk 相当の最小 ANSI ヘルパーを自前で持つ (SGR コードのみ)。
+const noColor = process.env.NO_COLOR || !process.stdout.isTTY
+const ANSI = { cyan: "36", green: "32", yellow: "33", dim: "2", red: "31" }
+
+function c(color, text) {
+  if (noColor) return text
+  return `\x1b[${ANSI[color]}m${text}\x1b[0m`
+}
+
+/** 長い本文をターミナル向けに省略する。 */
+function truncate(text, max = 400) {
+  const s = String(text ?? "")
+  if (s.length <= max) return s
+  return `${s.slice(0, max)}… (${s.length - max} 文字省略)`
+}
+
+function indentBlock(text) {
+  return String(text ?? "")
+    .split("\n")
+    .map((l) => `  ${l}`)
+    .join("\n")
+}
+
+/**
+ * Claude jsonl の 1 イベント (`normalizeHistoryEvent` 済み) をミラー表示用テキストに
+ * 変換する。表示すべきものが無ければ null を返す (呼び出し側は print しない)。
+ *
+ * @param {object} event
+ * @returns {string|null}
+ */
+export function formatClaudeEvent(event) {
+  if (!event || typeof event !== "object") return null
+  const content = event.message?.content
+  if (event.type === "user") {
+    if (!Array.isArray(content)) {
+      const text = typeof content === "string" ? content : ""
+      if (!text.trim()) return null
+      // コマンド echo (/clear /compact /skill 等) はノイズなのでスキップ。
+      if (/<command-name>/.test(text)) return null
+      return `${c('cyan', "›")} ${indentBlock(truncate(text)).trimStart()}`
+    }
+    const isToolResult = content.some((b) => b?.type === "tool_result")
+    if (isToolResult) return null // ツール結果の自動 user ラッパーは表示しない (ノイズ)
+    const text = content
+      .filter((b) => b?.type === "text")
+      .map((b) => b.text)
+      .join("")
+    if (!text.trim() || /<command-name>/.test(text)) return null
+    return `${c('cyan', "›")} ${indentBlock(truncate(text)).trimStart()}`
+  }
+  if (event.type === "assistant") {
+    if (!Array.isArray(content)) return null
+    const lines = []
+    for (const b of content) {
+      if (!b) continue
+      if (b.type === "text" && b.text?.trim()) {
+        lines.push(`${c('green', "●")} ${indentBlock(truncate(b.text)).trimStart()}`)
+      } else if (b.type === "tool_use") {
+        const brief = summarizeToolInput(b.name, b.input)
+        lines.push(`${c('yellow', "⚙")} ${b.name}${brief ? ` ${brief}` : ""}`)
+      }
+    }
+    return lines.length > 0 ? lines.join("\n") : null
+  }
+  return null
+}
+
+/** tool_use の input から簡潔な 1 行要約を作る (Bash はコマンド、それ以外は主要パス等)。 */
+function summarizeToolInput(name, input) {
+  if (!input || typeof input !== "object") return ""
+  if (name === "Bash" && typeof input.command === "string") {
+    return c('dim', truncate(input.command, 120))
+  }
+  const path = input.file_path || input.path || input.notebook_path
+  if (typeof path === "string") return c('dim', path)
+  return ""
+}
+
+/**
+ * Codex rollout jsonl の 1 行 (`{timestamp, type, payload}`) をミラー表示用テキストに
+ * 変換する。表示対象は実機確認済みの `event_msg` サブタイプ（user_message / agent_message /
+ * task_started）に絞る（未確認スキーマの exec 系は誤表示を避けるため今回は対象外）。
+ *
+ * @param {object} line
+ * @returns {string|null}
+ */
+export function formatCodexEvent(line) {
+  if (!line || typeof line !== "object" || line.type !== "event_msg") return null
+  const payload = line.payload
+  if (!payload || typeof payload !== "object") return null
+  switch (payload.type) {
+    case "user_message": {
+      const text = typeof payload.message === "string" ? payload.message : ""
+      if (!text.trim()) return null
+      return `${c('cyan', "›")} ${indentBlock(truncate(text)).trimStart()}`
+    }
+    case "agent_message": {
+      const text = typeof payload.message === "string" ? payload.message : ""
+      if (!text.trim()) return null
+      return `${c('green', "●")} ${indentBlock(truncate(text)).trimStart()}`
+    }
+    case "task_started":
+      return c('dim', "… thinking")
+    default:
+      return null
+  }
+}
+
+/**
+ * Claude セッションのミラーを実行し続ける (SIGINT/SIGTERM まで)。
+ *
+ * @param {object} args
+ * @param {string} args.cwd
+ * @param {string} args.sessionId
+ * @param {string} [args.projectsRoot]
+ * @param {(line: string) => void} [args.write] - テスト用に stdout 以外へ差し替え可能
+ * @param {import('pino').Logger} [args.logger]
+ * @returns {{ stop: () => void }}
+ */
+export function runClaudeMirror({ cwd, sessionId, projectsRoot, write = defaultWrite, logger }) {
+  const filePath = jsonlPath({ cwd, session_id: sessionId, projectsRoot })
+  write(c('dim', `[cockpit mirror] Claude session ${sessionId} を追従中… (${filePath})`))
+  const watcher = watchSessionFile({
+    filePath,
+    fromEnd: true,
+    logger,
+    onEvent: (event) => {
+      const text = formatClaudeEvent(event)
+      if (text) write(text)
+    },
+  })
+  return watcher
+}
+
+/**
+ * Codex セッションのミラーを実行し続ける (SIGINT/SIGTERM まで)。
+ *
+ * @param {object} args
+ * @param {string} args.threadId
+ * @param {(line: string) => void} [args.write]
+ * @param {import('pino').Logger} [args.logger]
+ * @returns {Promise<{ stop: () => void }>}
+ */
+export async function runCodexMirror({ threadId, write = defaultWrite, logger }) {
+  const filePath = await findCodexRolloutFile(threadId)
+  if (!filePath) {
+    write(c('red', `[cockpit mirror] Codex thread ${threadId} の rollout が見つかりません`))
+    return { stop() {} }
+  }
+  write(c('dim', `[cockpit mirror] Codex thread ${threadId} を追従中… (${filePath})`))
+  const watcher = watchCodexRollout({
+    filePath,
+    fromEnd: true,
+    logger,
+    onEvent: (line) => {
+      const text = formatCodexEvent(line)
+      if (text) write(text)
+    },
+  })
+  return watcher
+}
+
+function defaultWrite(line) {
+  process.stdout.write(`${line}\n`)
+}