triflux 10.52.0 → 10.53.0

package/hub/cli-adapter-base.mjs

@@ -15,61 +15,6 @@ import {
 import { IS_WINDOWS, killProcess } from "./platform.mjs";
 import { createInterventionLadder } from "./team/intervention.mjs";
 
-// ── Quota retry-after 파싱 ──────────────────────────────────────
-
-const FALLBACK_COOLDOWN_MS = { codex: 5 * 3600_000, gemini: 86400_000 };
-
-/**
- * 에러 텍스트에서 retry-after 시간을 동적 파싱.
- * "try again at 2026-04-11T10:00:00Z", "retry after 3600 seconds",
- * "resets in 7 days", "wait 5 hours" 등을 감지.
- */
-export function parseRetryAfterMs(text, provider) {
-  // 1. ISO timestamp: "try again at 2026-04-11T10:00:00"
-  const isoMatch = text.match(
-    /(?:try again|retry|available|resets?)\s+(?:at|after)\s+(\d{4}-\d{2}-\d{2}T[\d:.]+Z?)/i,
-  );
-  if (isoMatch) {
-    const target = new Date(isoMatch[1]).getTime();
-    if (target > Date.now()) return target - Date.now();
-  }
-
-  // 2. Duration: "N seconds/minutes/hours/days"
-  const durMatch = text.match(
-    /(?:retry|wait|resets?|again)\s+(?:in\s+|after\s+)?(\d+)\s*(second|minute|hour|day|week)/i,
-  );
-  if (durMatch) {
-    const n = Number(durMatch[1]);
-    const unit = durMatch[2].toLowerCase();
-    const multipliers = {
-      second: 1000,
-      minute: 60_000,
-      hour: 3600_000,
-      day: 86400_000,
-      week: 604800_000,
-    };
-    return n * (multipliers[unit] || 3600_000);
-  }
-
-  // 3. "7 days" / "24 hours" 단독 (context 없이)
-  const standaloneMatch = text.match(/(\d+)\s*(day|hour|week|minute)/i);
-  if (standaloneMatch) {
-    const n = Number(standaloneMatch[1]);
-    const unit = standaloneMatch[2].toLowerCase();
-    const multipliers = {
-      minute: 60_000,
-      hour: 3600_000,
-      day: 86400_000,
-      week: 604800_000,
-    };
-    const parsed = n * (multipliers[unit] || 3600_000);
-    if (parsed >= 3600_000) return parsed; // 1시간 이상만 신뢰
-  }
-
-  // 4. fallback: provider 기본값
-  return FALLBACK_COOLDOWN_MS[provider] || 5 * 3600_000;
-}
-
 // ── Shell utilities ─────────────────────────────────────────────
 
 export function normalizePathForShell(value) {
@@ -195,47 +140,28 @@ export function appendWarnings(stderr, warnings = []) {
   return [stderr, text].filter(Boolean).join("\n");
 }
 
-// ── Broker-integrated execution ─────────────────────────────────
+// ── Attempt execution ───────────────────────────────────────────
 
 /**
- * Shared execute() logic that uses account-broker for per-account circuit
- * breaking instead of a global breaker.
+ * preflight 뒤 buildAttemptsFn 이 만든 시도를 순서대로 실행한다.
  *
  * @param {object} params
- * @param {string} params.provider — 'codex' | 'gemini'
  * @param {(prompt: string, workdir: string, preflight: object, attempt: object) => Promise<object>} params.runFn
  * @param {(opts: object) => Promise<object>} params.preflightFn
  * @param {(opts: object, preflight: object) => object[]} params.buildAttemptsFn
  * @param {object} params.opts — caller-supplied execute options
  * @returns {Promise<object>} createResult-shaped result
  */
-export async function executeWithCircuitBroker({
-  provider,
+export async function executeWithAttempts({
   runFn,
   preflightFn,
   buildAttemptsFn,
   opts = {},
 }) {
-  // late-import to avoid circular dependency at module load time
-  const brokerMod = await import("./account-broker.mjs");
   const { withRetry } = await import("./workers/worker-utils.mjs");
 
-  // access broker as live binding property (not destructured) so reloadBroker() propagates
-  const hasBroker = brokerMod.broker != null;
-  // Empty broker (TFX_DISABLE_ACCOUNT_BROKER=1 or zero accounts) must not
-  // gate execution. lease() is null because there are no accounts to lease,
-  // not because all accounts are busy/cooldown/circuit. Treat it like
-  // hasBroker=false and fall through to the default auth path.
-  const brokerDisabled = hasBroker && brokerMod.broker.isDisabled === true;
-  const effectiveBroker = hasBroker && !brokerDisabled;
-  const lease = effectiveBroker ? brokerMod.broker.lease({ provider }) : null;
-  if (effectiveBroker && !lease) {
-    return createResult(false, { fellBack: true, failureMode: "circuit_open" });
-  }
-
   const preflight = await preflightFn(opts);
   if (!preflight.ok) {
-    if (lease) brokerMod.broker.release(lease.id, { ok: false });
     return createResult(false, {
       stderr: appendWarnings("", preflight.warnings),
       fellBack: opts.fallbackToClaude !== false,
@@ -250,15 +176,11 @@ export async function executeWithCircuitBroker({
   try {
     lastResult = await withRetry(
       async () => {
-        // PRD A1: lease 메타데이터를 runFn 에 전달해서 adapter 가 실제 spawn 시
-        // 해당 account 의 authFile/env/profile 을 적용할 수 있게 한다. lease=null
-        // 이면 adapter 는 default 경로 (단일 ~/.codex/auth.json) 로 동작한다.
         const result = await runFn(
           opts.prompt || "",
           opts.workdir || process.cwd(),
           preflight,
           attempts[attemptIndex],
-          lease,
         );
         const current = {
           ...result,
@@ -286,26 +208,7 @@ export async function executeWithCircuitBroker({
       createResult(false, { stderr: String(error?.message || error) });
   }
 
-  if (lastResult.ok) {
-    if (lease) brokerMod.broker.release(lease.id, { ok: true });
-    return lastResult;
-  }
-
-  if (lease) {
-    if (lastResult.failureMode === "rate_limited") {
-      const text = `${lastResult.output || ""}\n${lastResult.stderr || ""}`;
-      const coolMs = parseRetryAfterMs(text, provider);
-      brokerMod.broker.markRateLimited(lease.id, coolMs);
-      brokerMod.broker.emit("cooldown", {
-        id: lease.id,
-        provider,
-        coolMs,
-        reason: "quota_exhausted",
-      });
-    } else {
-      brokerMod.broker.release(lease.id, { ok: false });
-    }
-  }
+  if (lastResult.ok) return lastResult;
   return {
     ...lastResult,
     retried: attempts.length > 1,
@@ -374,13 +277,10 @@ export async function runProcess(command, workdir, timeout, opts = {}) {
   let child;
 
   try {
-    // PRD A1: opts.spawnEnv 가 있으면 그 env 로 spawn (lease 의 authFile/env 적용).
-    // undefined 면 spawn 의 default 동작 (부모 process env inherit) 유지.
     child = spawnProcess(command, {
       cwd: workdir,
       shell: true,
       windowsHide: true,
-      env: opts.spawnEnv,
     });
   } catch (error) {
     return createResult(false, {

package/hub/codex-adapter.mjs

@@ -1,11 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { join } from "node:path";
 import { codexProfileConfigOverrides } from "../scripts/lib/codex-profile-config.mjs";
 import {
   buildExecCommand,
-  createResult,
-  executeWithCircuitBroker,
+  executeWithAttempts,
   normalizePathForShell,
   runProcess,
   shellQuote,
@@ -113,7 +112,7 @@ export function buildLaunchScript(opts = {}) {
 
 // CTO boundary: this adapter assembles Codex prompts outside
 // scripts/tfx-route.sh. Keep north-star injection in tfx-route.sh until
-// launcher/circuit-broker workdir contracts have focused coverage.
+// launcher workdir contracts have focused coverage.
 export function buildExecArgs(opts = {}) {
   const prompt = typeof opts.prompt === "string" ? opts.prompt : "";
   const command = buildExecCommand(prompt, opts.resultFile || null, {
@@ -153,7 +152,7 @@ export function buildExecArgs(opts = {}) {
 
 // ── Codex execution ─────────────────────────────────────────────
 
-async function runCodex(prompt, workdir, preflight, attempt, lease) {
+async function runCodex(prompt, workdir, preflight, attempt) {
   const dir = join(tmpdir(), "triflux-codex-exec");
   mkdirSync(dir, { recursive: true });
   const resultFile = join(
@@ -162,7 +161,7 @@ async function runCodex(prompt, workdir, preflight, attempt, lease) {
   );
   const command = commandWithOverrides(
     buildExecCommand(prompt, resultFile, {
-      profile: lease?.profile ?? attempt.profile,
+      profile: attempt.profile,
       skipGitRepoCheck: true,
       sandboxBypass: attempt.forceBypass,
     }),
@@ -170,125 +169,17 @@ async function runCodex(prompt, workdir, preflight, attempt, lease) {
     preflight.codexPath,
     buildOverrides(attempt.requested, attempt.excluded),
   );
-  // PRD A1 — lease 메타데이터를 spawn env 에 적용한다. lease.authFile 이 있으면
-  // 해당 파일이 위치한 디렉토리를 CODEX_HOME 으로 export 해서 codex CLI 가 그
-  // account 의 auth.json 을 사용하게 한다. lease 가 null 이면 default ~/.codex
-  // 동작 유지 (회귀 없음). lease.env 는 추가 환경변수 (provider 고정 등) 주입용.
-  const spawnEnv = lease ? buildLeaseSpawnEnv(lease) : undefined;
-  const authCheck = validateLeaseAuth(lease, spawnEnv);
-  if (!authCheck.ok) {
-    return createResult(false, {
-      stderr: authCheck.error,
-      failureMode: "auth_sync",
-      skipCircuit: true,
-    });
-  }
   return runProcess(command, workdir, attempt.timeout, {
     resultFile,
     inferStallMode,
-    spawnEnv,
     cli: "codex",
-    codexHome: spawnEnv?.CODEX_HOME,
   });
 }
 
-function buildLeaseSpawnEnv(lease) {
-  const extra = {};
-  if (lease.authFile) {
-    // lease.authFile 은 보통 ~/.claude/cache/tfx-hub/codex-auth-<account>.json 형식.
-    // codex CLI 는 CODEX_HOME 을 통해 auth.json 위치를 결정하므로, 이 cache 파일을
-    // 직접 CODEX_HOME 후보 디렉토리로 사용한다. cache 파일 자체가 auth.json 이름이
-    // 아니라면 후속 PR 에서 isolated dir + symlink/복사 처리한다 (PRD Open Question).
-    // 현재는 lease.authFile 의 dirname 을 export 하되, 그 dirname 안에 auth.json 이
-    // 실제로 있을 때만 적용한다 (false-positive 회피).
-    try {
-      const dir = dirnameOf(lease.authFile);
-      if (dir) extra.CODEX_HOME = dir;
-    } catch {}
-  }
-  if (lease.env && typeof lease.env === "object") {
-    Object.assign(extra, lease.env);
-  }
-  return Object.keys(extra).length ? { ...process.env, ...extra } : undefined;
-}
-
-function validateLeaseAuth(lease, spawnEnv) {
-  if (!lease?.authFile) return { ok: true };
-  if (basename(lease.authFile) !== "auth.json") {
-    return {
-      ok: false,
-      error: `lease authFile must resolve to auth.json for account ${lease.id}`,
-    };
-  }
-  if (!existsSync(lease.authFile)) {
-    return {
-      ok: false,
-      error: `lease authFile missing for account ${lease.id}: ${lease.authFile}`,
-    };
-  }
-  if (dirnameOf(lease.authFile) !== spawnEnv?.CODEX_HOME) {
-    return {
-      ok: false,
-      // This is currently expected to match because buildLeaseSpawnEnv derives
-      // CODEX_HOME from authFile. Keep the guard so future lease.env overrides
-      // cannot silently point Codex at a different account home.
-      error: `CODEX_HOME mismatch for account ${lease.id}`,
-    };
-  }
-  try {
-    const parsed = JSON.parse(readFileSync(lease.authFile, "utf8"));
-    const accountId =
-      parsed?.tokens?.account_id ??
-      parsed?.account_id ??
-      parsed?.accountId ??
-      null;
-    if (!accountId) {
-      return {
-        ok: false,
-        error: `lease authFile has no account_id for account ${lease.id}`,
-      };
-    }
-    if (accountId !== lease.id) {
-      return {
-        ok: false,
-        error: `lease authFile account mismatch: expected ${lease.id}, got ${accountId}`,
-      };
-    }
-  } catch (error) {
-    return {
-      ok: false,
-      error: `lease authFile unreadable for account ${lease.id}: ${error?.message || error}`,
-    };
-  }
-  return { ok: true };
-}
-
-function dirnameOf(filePath) {
-  if (typeof filePath !== "string" || !filePath) return null;
-  const lastSep = Math.max(
-    filePath.lastIndexOf("/"),
-    filePath.lastIndexOf("\\"),
-  );
-  if (lastSep < 0) return null;
-  return filePath.slice(0, lastSep);
-}
-
 // ── Public API ──────────────────────────────────────────────────
 
-export async function getCircuitState() {
-  const brokerMod = await import("./account-broker.mjs");
-  if (!brokerMod.broker) return { state: "closed", failures: [] };
-  const snap = brokerMod.broker
-    .snapshot()
-    .filter((a) => a.provider === "codex");
-  return snap.length
-    ? { state: snap[0].circuitState, accounts: snap }
-    : { state: "closed", failures: [] };
-}
-
 export function execute(opts = {}) {
-  return executeWithCircuitBroker({
-    provider: "codex",
+  return executeWithAttempts({
     runFn: runCodex,
     preflightFn: (o) =>
       runPreflight({

package/hub/team/claude-transcript.mjs

@@ -157,6 +157,25 @@ function acceptLine(state, line, marker) {
   }
 }
 
+// daemon 과 tmux wait 가 같은 기준으로 끝을 판정한다. 아직이면 null.
+export function claudeWaitVerdict(transcript, idle) {
+  if (transcript?.error)
+    return { ok: false, status: "failed", error: transcript.error };
+  if (
+    !transcript?.userSeen ||
+    !transcript.turnEnded ||
+    !(idle || transcript.sectionClosed)
+  )
+    return null;
+  if (!transcript.response.trim())
+    return {
+      ok: false,
+      status: "failed",
+      error: "turn ended without assistant text",
+    };
+  return { status: "completed", done: true };
+}
+
 export async function readClaudeTranscript(transcriptPath, { requestId } = {}) {
   if (!transcriptPath) return null;
   const marker = requestId ? `[tfx-live req=${requestId}]` : null;

package/hub/team/cli/commands/start/start-headless.mjs

@@ -173,6 +173,8 @@ export async function startHeadlessTeam({
     console.log(
       `=== HEADLESS_COMPLETE succeeded=${succeeded.length} failed=${failed.length} total=${results.length} ===`,
     );
+    if (handle.resultsIndexPath)
+      console.log(`  ${DIM}결과 색인: ${handle.resultsIndexPath}${RESET}`);
 
     if (failed.length > 0) {
       for (const r of failed)

package/hub/team/codex-queue.mjs

@@ -1,8 +1,9 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { open, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { createInterface } from "node:readline";
 import { StringDecoder } from "node:string_decoder";
 import { promisify } from "node:util";
 import { codexThreadNames } from "../lib/codex-session-registry.mjs";
@@ -214,6 +215,112 @@ export async function queueCodexMessage({
   return { queuedMessageId: match[1] };
 }
 
+// 공식 app-server 를 stdio 로 잠깐 띄워 요청을 보낸다. 큐 조회와 삭제가 실험 API 라 experimentalApi 를 켠다.
+export async function withCodexAppServer(
+  run,
+  { env = process.env, timeoutMs = 30_000, spawnFn = spawn } = {},
+) {
+  const child = spawnFn("codex", ["app-server"], {
+    env,
+    cwd: env.HOME || homedir(),
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+  const pending = new Map();
+  let nextId = 0;
+  let closed = null;
+  const settleAll = (error) => {
+    closed ??= error;
+    for (const { reject } of pending.values()) reject(closed);
+    pending.clear();
+  };
+  child.on("error", settleAll);
+  // 먼저 끝난 app-server 에 쓰면 EPIPE 가 stdin 에서 나므로 요청 실패로 돌린다.
+  child.stdin.on("error", settleAll);
+  child.on("exit", (code) =>
+    settleAll(new Error(`codex app-server exited (${code})`)),
+  );
+  createInterface({ input: child.stdout }).on("line", (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const waiter = pending.get(message.id);
+    if (!waiter) return;
+    pending.delete(message.id);
+    if (message.error)
+      waiter.reject(new Error(`${waiter.method}: ${message.error.message}`));
+    else waiter.resolve(message.result);
+  });
+  const send = (message) =>
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+  const request = (method, params) => {
+    if (closed) return Promise.reject(closed);
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { method, resolve, reject });
+      send({ id, method, params });
+    });
+  };
+  const timer = setTimeout(
+    () => settleAll(new Error("codex app-server timed out")),
+    timeoutMs,
+  );
+  try {
+    await request("initialize", {
+      clientInfo: { name: "triflux-tfx-live", version: "1.0.0" },
+      capabilities: { experimentalApi: true },
+    });
+    send({ method: "initialized", params: {} });
+    return await run(request);
+  } finally {
+    clearTimeout(timer);
+    child.kill();
+  }
+}
+
+function queuedRequestId(texts) {
+  return texts.join("\n").match(/\[tfx-live req=([^\]\s]+)\]/)?.[1] ?? null;
+}
+
+// TUI 가 가져가기 전의 항목만 보인다. 가져간 뒤의 처리 여부는 wait 가 rollout 으로 본다.
+export function listCodexQueue(threadId, options = {}) {
+  return withCodexAppServer(async (request) => {
+    const items = [];
+    let cursor = null;
+    do {
+      const page = await request("thread/queue/list", { threadId, cursor });
+      for (const item of page?.data ?? []) {
+        const texts = (item.input ?? []).map((part) => part.text ?? "");
+        items.push({
+          id: item.id,
+          requestId: queuedRequestId(texts),
+          text: texts.join("\n"),
+        });
+      }
+      cursor = page?.nextCursor ?? null;
+    } while (cursor);
+    return items;
+  }, options);
+}
+
+// 지우기 전에 TUI 가 가져간 항목은 deleted: false 라 missing 으로 돌려준다.
+export function deleteCodexQueueItems(threadId, ids, options = {}) {
+  return withCodexAppServer(async (request) => {
+    const deleted = [];
+    const missing = [];
+    for (const id of ids) {
+      const result = await request("thread/queue/delete", {
+        threadId,
+        queuedSubmissionId: id,
+      });
+      (result?.deleted === true ? deleted : missing).push(id);
+    }
+    return { deleted, missing };
+  }, options);
+}
+
 function userTexts(entry) {
   const payload = entry.payload ?? {};
   if (

package/hub/team/headless.mjs

@@ -43,6 +43,7 @@ import {
   startCapture,
   waitForCompletion,
 } from "./psmux.mjs";
+import { createResultsIndex, resultsIndexPath } from "./results-index.mjs";
 import { createLogDashboard } from "./tui.mjs";
 import { createWtManager } from "./wt-manager.mjs";
 
@@ -126,6 +127,14 @@ export function normalizeHeadlessRole(role) {
   return normalized && VALID_ROUTE_AGENTS.has(normalized) ? normalized : "";
 }
 
+export function headlessResultFile(sessionName, paneName) {
+  return join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
+}
+
+export function headlessResultsIndexPath(sessionName) {
+  return resultsIndexPath(RESULT_DIR, sessionName).replace(/\\/g, "/");
+}
+
 export function resolveHeadlessDisplayName(assignment = {}, paneName = "") {
   const normalized = String(assignment.displayName || "")
     .trim()
@@ -543,10 +552,7 @@ async function dispatchProgressive(sessionName, assignments, opts = {}) {
       });
 
     // 캡처 시작 + 컬러 배너 + 명령 dispatch
-    const resultFile = join(
-      RESULT_DIR,
-      `${sessionName}-${paneName}.txt`,
-    ).replace(/\\/g, "/");
+    const resultFile = headlessResultFile(sessionName, paneName);
     // Issue #118 review R1 HIGH: stale artifact 제거 (이전 run / restart 잔재)
     cleanStaleResultArtifacts(resultFile);
     const cmd = buildHeadlessCommand(
@@ -634,10 +640,7 @@ async function dispatchBatch(sessionName, assignments, opts = {}) {
       const displayName = resolveHeadlessDisplayName(assignment, paneName);
       const workerId = getHeadlessWorkerAgentId(sessionName, i);
       const resolvedCli = resolveCliType(assignment.cli);
-      const resultFile = join(
-        RESULT_DIR,
-        `${sessionName}-${paneName}.txt`,
-      ).replace(/\\/g, "/");
+      const resultFile = headlessResultFile(sessionName, paneName);
       // Issue #118 review R1 HIGH: stale artifact 제거 (이전 run / restart 잔재)
       cleanStaleResultArtifacts(resultFile);
       const cmd = buildHeadlessCommand(
@@ -918,6 +921,23 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     return { sessionName, results: [], sessionOwnership, agentsRows };
   }
 
+  const resultsIndex = createResultsIndex(
+    headlessResultsIndexPath(sessionName),
+    sessionName,
+    normalizedAssignments.map((a, i) => {
+      const paneName = `worker-${i + 1}`;
+      return {
+        paneName,
+        displayName: a.displayName,
+        cli: resolveCliType(a.cli),
+        role: a.role,
+        resultFile: headlessResultFile(sessionName, paneName),
+      };
+    }),
+    // 같은 이름의 남의 세션 색인을 덮어쓰지 않도록 세션을 소유한 동안만 쓴다.
+    () => sessionOwnership.owned,
+  );
+
   let runCompleted = false;
   let completedResults = [];
   let runFailed = false;
@@ -996,6 +1016,11 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
 
   // onProgress 예외를 삼켜 실행 흐름 보호 (onPoll과 동일 패턴)
   const combinedProgress = (event) => {
+    if (event.type === "session_created") resultsIndex.begin();
+    else if (event.type === "dispatched")
+      resultsIndex.workerStarted(event.paneName);
+    else if (event.type === "completed")
+      resultsIndex.workerFinished(event.paneName, event);
     feedTui(event);
     if (onProgress) {
       try {
@@ -1077,6 +1102,7 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     runFailed = true;
     runError = error;
   }
+  resultsIndex.finish(runCompleted);
 
   if (!runCompleted) {
     sessionOwnership.release();
@@ -1086,6 +1112,7 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
   return {
     sessionName,
     results: completedResults,
+    resultsIndexPath: resultsIndex.path,
     sessionOwnership,
     agentsRows,
   };
@@ -1638,6 +1665,7 @@ export async function runHeadlessInteractive(
   const handle = {
     sessionName,
     results,
+    resultsIndexPath: runResult.resultsIndexPath,
     dispatches,
     _killed: false,
 

package/hub/team/results-index.mjs

@@ -0,0 +1,92 @@
+// headless 세션 결과 색인. 화면의 HEADLESS_COMPLETE 문자열 대신 읽도록 세션당 JSON 하나를 둔다 (ADR-0034).
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const RESULTS_INDEX_VERSION = 1;
+
+export function resultsIndexPath(dir, sessionName) {
+  return join(dir, `${sessionName}.results.json`);
+}
+
+/**
+ * @param {string} path
+ * @param {string} sessionName
+ * @param {Array<{paneName: string, displayName?: string, cli: string, role?: string, resultFile: string}>} workers
+ * @param {() => boolean} canWrite
+ */
+export function createResultsIndex(path, sessionName, workers, canWrite) {
+  const now = () => new Date().toISOString();
+  const index = {
+    version: RESULTS_INDEX_VERSION,
+    sessionName,
+    startedAt: now(),
+    finishedAt: null,
+    completed: false,
+    workers: workers.map((w) => ({
+      paneName: w.paneName,
+      displayName: w.displayName || w.paneName,
+      cli: w.cli,
+      role: w.role || "",
+      status: "pending",
+      matched: null,
+      exitCode: null,
+      sessionDead: false,
+      startedAt: null,
+      finishedAt: null,
+      resultFile: w.resultFile,
+    })),
+  };
+  const byPane = new Map(index.workers.map((w) => [w.paneName, w]));
+
+  // 임시 파일에 쓰고 rename 해 읽는 쪽이 반쯤 쓴 JSON 을 보지 않게 한다.
+  // 색인은 보조 산출물이라 쓰기 실패가 실행을 멈추면 안 된다.
+  const flush = () => {
+    if (!canWrite()) return;
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+      writeFileSync(tmp, `${JSON.stringify(index, null, 2)}\n`, "utf8");
+      renameSync(tmp, path);
+    } catch {
+      try {
+        rmSync(tmp, { force: true });
+      } catch {
+        /* best-effort */
+      }
+    }
+  };
+
+  return {
+    path,
+    // 같은 이름의 이전 실행 색인이 남아 있으면 세션을 잡자마자 덮어 오판을 막는다.
+    begin: flush,
+    workerStarted(paneName) {
+      const w = byPane.get(paneName);
+      if (!w || w.status !== "pending") return;
+      w.status = "running";
+      w.startedAt = now();
+      flush();
+    },
+    workerFinished(paneName, { matched, exitCode, sessionDead } = {}) {
+      const w = byPane.get(paneName);
+      if (!w) return;
+      w.status = matched && exitCode === 0 ? "completed" : "failed";
+      w.matched = Boolean(matched);
+      w.exitCode = exitCode ?? null;
+      w.sessionDead = Boolean(sessionDead);
+      w.finishedAt = now();
+      flush();
+    },
+    finish(completed) {
+      // 예외로 끝나면 끝나지 못한 워커를 failed 로 확정해 "아직 도는 중"과 구분한다.
+      for (const w of index.workers) {
+        if (w.status === "pending" || w.status === "running") {
+          w.status = "failed";
+          w.finishedAt = now();
+        }
+      }
+      index.finishedAt = now();
+      index.completed = Boolean(completed);
+      flush();
+    },
+  };
+}