throughline 0.3.23 → 0.3.25

package/src/cli/codex-rollback-model-visible-smoke.test.mjs

@@ -0,0 +1,255 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+const EXPERIMENTAL_ENV = 'THROUGHLINE_EXPERIMENTAL_CODEX_ROLLBACK_MODEL_VISIBLE_SMOKE';
+
+function makeFakeCodexAppServer(dir, mode) {
+  const script = join(dir, `fake-codex-rollback-model-visible-${mode}.mjs`);
+  const delta =
+    mode === 'visible'
+      ? 'TL_ROLLBACK_MODEL_VISIBLE_SECRET'
+      : 'TL_ROLLBACK_MODEL_VISIBLE_NOT_VISIBLE';
+  writeFileSync(
+    script,
+    `#!/usr/bin/env node
+import { createInterface } from 'node:readline';
+const rl = createInterface({ input: process.stdin });
+let turns = [{ id: 'turn-1' }];
+function send(message) { process.stdout.write(JSON.stringify(message) + '\\n'); }
+rl.on('line', (line) => {
+  const msg = JSON.parse(line);
+  if (msg.method === 'initialized') return;
+  if (msg.method === 'initialize') {
+    send({ id: msg.id, result: { userAgent: 'fake-codex' } });
+  } else if (msg.method === 'thread/read' || msg.method === 'thread/resume') {
+    send({ id: msg.id, result: { thread: { id: msg.params.threadId, turns } } });
+  } else if (msg.method === 'thread/rollback') {
+    turns = turns.slice(0, Math.max(0, turns.length - msg.params.numTurns));
+    send({ id: msg.id, result: { thread: { id: msg.params.threadId, turns } } });
+  } else if (msg.method === 'turn/start') {
+    const prompt = JSON.stringify(msg.params.input);
+    if (prompt.includes('verification') && prompt.includes('TL_ROLLBACK_MODEL_VISIBLE_SECRET')) {
+      send({ id: msg.id, error: { code: -32000, message: 'full marker leaked into verify prompt' } });
+      return;
+    }
+    turns = [...turns, { id: 'turn-' + (turns.length + 1) }];
+    if (prompt.includes('verification')) {
+      send({ method: 'item/agentMessage/delta', params: { threadId: msg.params.threadId, turnId: 'turn-verify', itemId: 'item-1', delta: '${delta}' } });
+    }
+    send({ method: 'turn/completed', params: { threadId: msg.params.threadId, turn: { id: 'turn-current' } } });
+    send({ id: msg.id, result: { turn: { id: 'turn-current' } } });
+  } else {
+    send({ id: msg.id, error: { code: -32601, message: 'unknown method' } });
+  }
+});
+`,
+  );
+  chmodSync(script, 0o755);
+  return script;
+}
+
+function runSmoke(project, args = [], extraEnv = {}) {
+  return spawnSync(
+    process.execPath,
+    [BIN_PATH, 'codex-rollback-model-visible-smoke', ...args],
+    {
+      cwd: project,
+      env: {
+        ...process.env,
+        ...extraEnv,
+      },
+      encoding: 'utf8',
+    },
+  );
+}
+
+test('codex-rollback-model-visible-smoke refuses without explicit experimental env', () => {
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-rollback-visible-cli-'));
+  try {
+    const result = runSmoke(project, [
+      '--verify',
+      '--codex-thread-id',
+      'thread-rollback-visible',
+      '--marker',
+      'TL_ROLLBACK_MODEL_VISIBLE_SECRET',
+      '--json',
+    ]);
+
+    assert.equal(result.status, 1);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'refused');
+    assert.equal(payload.reason, 'experimental_env_required');
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('codex-rollback-model-visible-smoke prepare starts and rolls back a marker turn', () => {
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-rollback-visible-cli-'));
+  try {
+    const fake = makeFakeCodexAppServer(project, 'hidden');
+    const result = runSmoke(
+      project,
+      [
+        '--prepare',
+        '--codex-thread-id',
+        'thread-rollback-visible',
+        '--marker',
+        'TL_ROLLBACK_MODEL_VISIBLE_SECRET',
+        '--codex-app-server-bin',
+        fake,
+        '--json',
+      ],
+      { [EXPERIMENTAL_ENV]: '1' },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.mode, 'prepare');
+    assert.equal(payload.status, 'prepared');
+    assert.equal(payload.rollbackSent, true);
+    assert.match(payload.nextCommand, /codex-rollback-model-visible-smoke --verify/);
+    assert.match(payload.nextCommand, /TL_ROLLBACK_MODEL_VISIBLE_SECRET/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('codex-rollback-model-visible-smoke marker-file keeps generated marker out of prepare output', () => {
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-rollback-visible-cli-'));
+  try {
+    const fake = makeFakeCodexAppServer(project, 'hidden');
+    const markerFile = join(project, 'rollback-marker.json');
+    const result = runSmoke(
+      project,
+      [
+        '--prepare',
+        '--codex-thread-id',
+        'thread-rollback-visible',
+        '--marker-file',
+        markerFile,
+        '--codex-app-server-bin',
+        fake,
+        '--json',
+      ],
+      { [EXPERIMENTAL_ENV]: '1' },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    const markerPayload = JSON.parse(readFileSync(markerFile, 'utf8'));
+    assert.equal(payload.status, 'prepared');
+    assert.equal(payload.marker, '[redacted]');
+    assert.equal(payload.markerRedacted, true);
+    assert.equal(payload.markerFile, markerFile);
+    assert.match(markerPayload.marker, /^TL_ROLLBACK_MODEL_VISIBLE_/);
+    assert.doesNotMatch(result.stdout, new RegExp(markerPayload.marker));
+    assert.match(payload.nextCommand, /--marker-file/);
+    assert.doesNotMatch(payload.nextCommand, new RegExp(markerPayload.marker));
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('codex-rollback-model-visible-smoke verify exits zero when marker is not reproduced', () => {
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-rollback-visible-cli-'));
+  try {
+    const fake = makeFakeCodexAppServer(project, 'hidden');
+    const result = runSmoke(
+      project,
+      [
+        '--verify',
+        '--codex-thread-id',
+        'thread-rollback-visible',
+        '--marker',
+        'TL_ROLLBACK_MODEL_VISIBLE_SECRET',
+        '--codex-app-server-bin',
+        fake,
+        '--json',
+      ],
+      { [EXPERIMENTAL_ENV]: '1' },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.mode, 'verify');
+    assert.equal(payload.status, 'not-reproduced');
+    assert.equal(payload.promptIncludesMarker, false);
+    assert.equal(payload.rolledBackMarkerModelVisible, false);
+    assert.equal(payload.modelReportedNotVisible, true);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('codex-rollback-model-visible-smoke verify exits nonzero when marker is reproduced', () => {
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-rollback-visible-cli-'));
+  try {
+    const fake = makeFakeCodexAppServer(project, 'visible');
+    const result = runSmoke(
+      project,
+      [
+        '--verify',
+        '--codex-thread-id',
+        'thread-rollback-visible',
+        '--marker',
+        'TL_ROLLBACK_MODEL_VISIBLE_SECRET',
+        '--codex-app-server-bin',
+        fake,
+        '--json',
+      ],
+      { [EXPERIMENTAL_ENV]: '1' },
+    );
+
+    assert.equal(result.status, 1);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.mode, 'verify');
+    assert.equal(payload.status, 'reproduced');
+    assert.equal(payload.promptIncludesMarker, false);
+    assert.equal(payload.rolledBackMarkerModelVisible, true);
+    assert.equal(payload.modelReportedNotVisible, false);
+    assert.deepEqual(payload.observedMarkers, ['TL_ROLLBACK_MODEL_VISIBLE_SECRET']);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('codex-rollback-model-visible-smoke marker-file redacts reproduced marker from verify output', () => {
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-rollback-visible-cli-'));
+  try {
+    const fake = makeFakeCodexAppServer(project, 'visible');
+    const markerFile = join(project, 'rollback-marker.json');
+    writeFileSync(markerFile, JSON.stringify({ marker: 'TL_ROLLBACK_MODEL_VISIBLE_SECRET' }));
+    const result = runSmoke(
+      project,
+      [
+        '--verify',
+        '--codex-thread-id',
+        'thread-rollback-visible',
+        '--marker-file',
+        markerFile,
+        '--codex-app-server-bin',
+        fake,
+        '--json',
+      ],
+      { [EXPERIMENTAL_ENV]: '1' },
+    );
+
+    assert.equal(result.status, 1);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.status, 'reproduced');
+    assert.equal(payload.marker, '[redacted]');
+    assert.equal(payload.markerRedacted, true);
+    assert.deepEqual(payload.observedMarkers, ['[redacted]']);
+    assert.doesNotMatch(result.stdout, /TL_ROLLBACK_MODEL_VISIBLE_SECRET/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});

package/src/cli/codex-sidecar-diagnostics.mjs

@@ -0,0 +1,48 @@
+import { diagnoseCodexSidecar } from '../codex-sidecar.mjs';
+
+function parseArgs(args) {
+  const out = {
+    projectPath: process.cwd(),
+    preset: 'review',
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--project') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--project requires a path');
+      }
+      out.projectPath = value;
+    } else if (arg === '--preset') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--preset requires a value');
+      }
+      out.preset = value;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  return out;
+}
+
+export function run(args) {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-sidecar-diagnostics] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const result = diagnoseCodexSidecar({
+    projectPath: parsed.projectPath,
+    preset: parsed.preset,
+  });
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  process.exit(result.status === 'configured' ? 0 : 1);
+}

package/src/cli/codex-sidecar-dry-run.mjs

@@ -0,0 +1,85 @@
+import { inferWorkflowForPreset, runCodexSidecarDryRun } from '../codex-sidecar.mjs';
+
+function parseArgs(args) {
+  const out = {
+    projectPath: process.cwd(),
+    workflow: null,
+    preset: 'review',
+    contextFile: null,
+    turnTimeoutMs: 30_000,
+    promptParts: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--project') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--project requires a path');
+      }
+      out.projectPath = value;
+    } else if (arg === '--workflow') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--workflow requires a value');
+      }
+      out.workflow = value;
+    } else if (arg === '--preset') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--preset requires a value');
+      }
+      out.preset = value;
+    } else if (arg === '--context-file') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--context-file requires a path');
+      }
+      out.contextFile = value;
+    } else if (arg === '--turn-timeout-ms') {
+      const value = args[++i];
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error('--turn-timeout-ms must be a positive integer');
+      }
+      out.turnTimeoutMs = parsed;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`unknown argument: ${arg}`);
+    } else {
+      out.promptParts.push(arg);
+    }
+  }
+
+  return {
+    projectPath: out.projectPath,
+    workflow: out.workflow ?? inferWorkflowForPreset(out.preset),
+    preset: out.preset,
+    contextFile: out.contextFile,
+    turnTimeoutMs: out.turnTimeoutMs,
+    prompt: out.promptParts.length > 0 ? out.promptParts.join(' ') : null,
+  };
+}
+
+export function run(args) {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-sidecar-dry-run] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const result = runCodexSidecarDryRun({
+    projectPath: parsed.projectPath,
+    workflow: parsed.workflow,
+    preset: parsed.preset,
+    contextFile: parsed.contextFile,
+    prompt: parsed.prompt,
+    turnTimeoutMs: parsed.turnTimeoutMs,
+    timeoutMs: parsed.turnTimeoutMs + 5_000,
+  });
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  process.exit(result.status === 'dry-run' ? 0 : 1);
+}

package/src/cli/codex-summarize.mjs

@@ -0,0 +1,224 @@
+import { getDb } from '../db.mjs';
+import {
+  L2_WINDOW,
+  countDistinctBodyTurns,
+  pickOldestUnsummarizedTurn,
+} from '../turn-processor.mjs';
+import { summarizeToL1 } from '../haiku-summarizer.mjs';
+
+function parseArgs(args) {
+  const out = {
+    sessionId: null,
+    codexThreadId: null,
+    json: false,
+    max: 1,
+    projectPath: process.cwd(),
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--session') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) throw new Error('--session requires a session id');
+      out.sessionId = value;
+    } else if (arg === '--codex-thread-id') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--codex-thread-id requires a thread id');
+      }
+      out.codexThreadId = value;
+    } else if (arg === '--max') {
+      const value = Number(args[++i]);
+      if (!Number.isInteger(value) || value < 1) throw new Error('--max must be a positive integer');
+      out.max = value;
+    } else if (arg === '--project') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) throw new Error('--project requires a path');
+      out.projectPath = value;
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (!arg.startsWith('-') && !out.sessionId) {
+      out.sessionId = arg;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  if (!out.sessionId && out.codexThreadId) {
+    out.sessionId = `codex:${out.codexThreadId}`;
+  }
+  return out;
+}
+
+function findLatestCodexSessionId(db, projectPath) {
+  const row = db
+    .prepare(
+      `SELECT session_id
+       FROM sessions
+       WHERE lower(project_path) = lower(?)
+         AND session_id LIKE 'codex:%'
+       ORDER BY updated_at DESC
+       LIMIT 1`,
+    )
+    .get(projectPath);
+  return row?.session_id ?? null;
+}
+
+function buildL2ForSummary(rows) {
+  return rows
+    .map((row) => `[${row.role}]: ${row.text}`)
+    .join('\n\n')
+    .trim();
+}
+
+function loadTurnRows(db, { sessionId, originSessionId, turnNumber }) {
+  return db
+    .prepare(
+      `SELECT role, text, created_at
+       FROM bodies
+       WHERE session_id = ? AND origin_session_id = ? AND turn_number = ?
+       ORDER BY created_at ASC, id ASC`,
+    )
+    .all(sessionId, originSessionId, turnNumber);
+}
+
+function insertSkeleton(db, { sessionId, originSessionId, turnNumber, summary, createdAt }) {
+  const result = db
+    .prepare(
+      `INSERT OR IGNORE INTO skeletons
+         (session_id, origin_session_id, turn_number, role, summary, created_at)
+       VALUES (?, ?, ?, 'assistant', ?, ?)`,
+    )
+    .run(sessionId, originSessionId, turnNumber, summary, createdAt);
+  return result.changes > 0;
+}
+
+export function summarizeCodexSession(db, { sessionId, projectPath, max, env = process.env }) {
+  if (!sessionId?.startsWith('codex:')) {
+    throw new Error('codex-summarize requires a codex:<thread-id> session');
+  }
+
+  const totalTurns = countDistinctBodyTurns(db, sessionId);
+  if (totalTurns <= L2_WINDOW) {
+    return {
+      status: 'skipped',
+      reason: 'within_l2_window',
+      sessionId,
+      totalTurns,
+      l2Window: L2_WINDOW,
+      summarized: [],
+    };
+  }
+
+  const summarized = [];
+  for (let i = 0; i < max; i++) {
+    const oldest = pickOldestUnsummarizedTurn(db, sessionId);
+    if (!oldest) break;
+    const rows = loadTurnRows(db, {
+      sessionId,
+      originSessionId: oldest.origin_session_id,
+      turnNumber: oldest.turn_number,
+    });
+    const l2Text = buildL2ForSummary(rows);
+    const result = summarizeToL1(l2Text, {
+      projectPath,
+      hostMode: 'codex-primary',
+      env,
+    });
+    const inserted = insertSkeleton(db, {
+      sessionId,
+      originSessionId: oldest.origin_session_id,
+      turnNumber: oldest.turn_number,
+      summary: result.summary,
+      createdAt: oldest.created_at,
+    });
+    summarized.push({
+      originSessionId: oldest.origin_session_id,
+      turnNumber: oldest.turn_number,
+      source: result.source ?? 'codex-cli',
+      inserted,
+    });
+  }
+
+  return {
+    status: summarized.length > 0 ? 'summarized' : 'skipped',
+    reason: summarized.length > 0 ? 'codex_cli_l1_written' : 'no_unsummarized_turns',
+    sessionId,
+    totalTurns,
+    l2Window: L2_WINDOW,
+    summarized,
+  };
+}
+
+function renderTextResult(result) {
+  const lines = [];
+  lines.push('throughline codex summarize');
+  lines.push('');
+  lines.push(`  status:       ${result.status}`);
+  lines.push(`  reason:       ${result.reason}`);
+  lines.push(`  session:      ${result.sessionId}`);
+  lines.push(`  totalTurns:   ${result.totalTurns}`);
+  lines.push(`  l2Window:     ${result.l2Window}`);
+  lines.push(`  summarized:   ${result.summarized.length}`);
+  for (const row of result.summarized) {
+    lines.push(`    - turn ${row.turnNumber} (${row.source})`);
+  }
+  return lines.join('\n');
+}
+
+export async function run(args) {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-summarize] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const db = getDb();
+  const sessionId = parsed.sessionId ?? findLatestCodexSessionId(db, parsed.projectPath);
+  if (!sessionId) {
+    process.stderr.write(
+      '[codex-summarize] no Codex session found for this project. Pass --session codex:<thread-id> explicitly.\n',
+    );
+    process.exit(1);
+  }
+
+  try {
+    const result = summarizeCodexSession(db, {
+      sessionId,
+      projectPath: parsed.projectPath,
+      max: parsed.max,
+    });
+    if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else process.stdout.write(renderTextResult(result) + '\n');
+    process.exit(result.status === 'summarized' || result.status === 'skipped' ? 0 : 1);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    if (parsed.json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            status: 'error',
+            reason: err?.reason ?? 'codex_summarize_failed',
+            source: err?.source ?? null,
+            message: msg,
+            stderr: err?.stderr ?? '',
+            exitCode: err?.exitCode ?? null,
+          },
+          null,
+          2,
+        ) + '\n',
+      );
+    } else {
+      process.stderr.write(`[codex-summarize] ${msg}\n`);
+    }
+    process.exit(1);
+  }
+}
+
+export const _internal = {
+  parseArgs,
+  summarizeCodexSession,
+};

package/src/cli/codex-threads.mjs

@@ -0,0 +1,89 @@
+import { listCodexThreadCandidates } from '../codex-thread-index.mjs';
+
+function parseArgs(args) {
+  const out = {
+    json: false,
+    allProjects: false,
+    limit: 10,
+    codexHome: null,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      out.json = true;
+    } else if (arg === '--all-projects') {
+      out.allProjects = true;
+    } else if (arg === '--limit') {
+      const value = Number(args[++i]);
+      if (!Number.isInteger(value) || value < 1) {
+        throw new Error('--limit must be an integer >= 1');
+      }
+      out.limit = value;
+    } else if (arg === '--codex-home') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) {
+        throw new Error('--codex-home requires a path');
+      }
+      out.codexHome = value;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  return out;
+}
+
+export function run(args) {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[codex-threads] ${msg}\n`);
+    process.exit(1);
+  }
+
+  const candidates = listCodexThreadCandidates({
+    codexHome: parsed.codexHome ?? undefined,
+    projectPath: process.cwd(),
+    allProjects: parsed.allProjects,
+    limit: parsed.limit,
+  });
+
+  if (parsed.json) {
+    process.stdout.write(JSON.stringify({ candidates }, null, 2) + '\n');
+    process.exit(0);
+  }
+
+  process.stdout.write(renderReport(candidates, { allProjects: parsed.allProjects }) + '\n');
+  process.exit(0);
+}
+
+function renderReport(candidates, { allProjects }) {
+  const lines = [];
+  lines.push('## Codex Thread Candidates');
+  lines.push('');
+  lines.push(`Scope: ${allProjects ? 'all projects' : 'current project'}`);
+  lines.push('Read-only: yes');
+  lines.push('');
+
+  if (candidates.length === 0) {
+    lines.push('No Codex rollout candidates found.');
+    lines.push('Pass --all-projects to inspect other projects, or --codex-home <path> for a non-default CODEX_HOME.');
+    return lines.join('\n');
+  }
+
+  for (const candidate of candidates) {
+    lines.push(`- ${candidate.id}`);
+    if (candidate.threadName) lines.push(`  name: ${candidate.threadName}`);
+    lines.push(`  updated: ${candidate.updatedAt ?? 'unknown'}`);
+    lines.push(`  cwd: ${candidate.cwd ?? 'unknown'}`);
+    lines.push(`  rollout: ${candidate.rolloutPath}`);
+  }
+
+  lines.push('');
+  lines.push('Use one candidate explicitly with throughline trim --host codex --codex-thread-id <id>.');
+  lines.push('This command never selects a thread for automatic trim.');
+  return lines.join('\n');
+}