@the-open-engine/zeroshot 6.39.1 → 6.40.0

package/README.md

@@ -74,6 +74,36 @@ Every step is written to a crash-safe SQLite ledger. Bring your own provider and
   <em>One run: classify, execute, verify, and repeat when evidence fails.</em>
 </div>
 
+## Classification and routing
+
+The conductor scores every task on complexity (TRIVIAL, SIMPLE, STANDARD, CRITICAL) and type (INQUIRY, TASK, DEBUG) before any code is written, and that score picks the workflow. A junior model runs the pass; when it can't call it, it answers UNCERTAIN and a senior model decides instead.
+
+Rules are evaluated top down, first match wins:
+
+| Classification                         | Workflow           | Agents                                                        |
+| -------------------------------------- | ------------------ | ------------------------------------------------------------- |
+| DEBUG above TRIVIAL, any complexity    | `debug-workflow`   | investigator, fixer, tester, completion-detector              |
+| TRIVIAL TASK or DEBUG, `--pr`/`--ship` | `worker-validator` | worker, 1 validator                                           |
+| TRIVIAL                                | `single-worker`    | worker only, **no validator**                                 |
+| SIMPLE                                 | `worker-validator` | worker, 1 validator                                           |
+| STANDARD                               | `full-workflow`    | planner, worker, 2 validators                                 |
+| CRITICAL                               | `full-workflow`    | planner, worker, meta-coordinator, 4 validators in two stages |
+
+TRIVIAL is the row worth knowing about: one worker, no verifier, so the executor–verifier split doesn't apply on that path. CRITICAL is meant to be rare in the other direction, and the conductor is instructed to pick STANDARD whenever it's torn, since CRITICAL spends a senior model and four validators.
+
+## Custom workflows
+
+Each workflow above is a JSON file in [`cluster-templates/base-templates/`](cluster-templates/base-templates/), and none of them is privileged. Underneath is a message bus: agents subscribe to topics, publish to topics, and the graph is that wiring.
+
+```bash
+zeroshot config list                   # available workflows
+zeroshot config show full-workflow     # read one
+zeroshot config validate ./mine.json   # check yours
+zeroshot run 123 --config ./mine.json  # run it
+```
+
+Agent ids, roles, and topic names are free strings, and a trigger can carry a JavaScript predicate deciding whether a message wakes its agent. Cycles are legal, reject-and-retry being one, though `zeroshot config validate` fails a ring of three or more unless something in it carries escape logic. Sub-clusters nest five deep.
+
 ## Providers and issue sources
 
 Provider engines come from the registry: **Claude, Codex, bundled Gateway, Gemini, OpenCode, Pi, OMP, Kiro, and Copilot**. Model gateways stay behind the single Gateway provider.
@@ -108,6 +138,7 @@ zeroshot run 123 --pr            # worktree + pull request
 zeroshot run 123 --ship          # worktree + PR + merge after approval
 zeroshot run 123 --pr --pr-body $'## Summary\n\nCustom text\n\n{{issue_reference}}'
 zeroshot run 123 -d              # background run
+zeroshot run 123 --config ./mine.json  # custom workflow graph
 
 zeroshot list                    # tasks and clusters (--json)
 zeroshot status <id>             # detailed status (--json)
@@ -115,10 +146,13 @@ zeroshot logs <id> -f            # stream logs
 zeroshot resume <id> [prompt]    # resume a stopped or failed run
 zeroshot stop <id>               # graceful stop
 zeroshot kill <id>               # force stop
+zeroshot export <id> --format trace --output run.trace.jsonl
+zeroshot export <id> --format semantic --output run.semantic.jsonl
 
 zeroshot providers               # provider availability and defaults
 zeroshot settings                # effective settings
 zeroshot agents list             # available agents
+zeroshot config list             # workflow graphs (config show / config validate)
 ```
 
 `--pr-body` supplies a deterministic pull-request body for `--pr` and `--ship` runs. The
@@ -126,6 +160,16 @@ template supports `{{issue_number}}`, `{{issue_title}}`, and `{{issue_reference}
 expand to empty text for tasks without an issue, so manual runs never emit `Closes #unknown`.
 The unrendered template is retained for detached and resumed runs.
 
+The `trace` export is a deterministic, provider-neutral research bundle. It preserves the ordered
+cluster ledger, exact selected prompts, and exact raw task-log bytes without interpreting a Claude,
+Codex, Pi, or other provider protocol. Missing evidence is recorded explicitly in its footer. File
+exports are create-only: choose a new output path rather than replacing an existing bundle. Live
+tasks are exported only as explicitly incomplete snapshots.
+The separate `semantic` export runs those task bytes through Zeroshot's existing stateful provider
+adapters and emits bounded `text`, `thinking`, `tool_call`, `tool_result`, and `result` events.
+Zeroshot-owned wrapper and stderr records remain native-only. Parser diagnostics affect only
+semantic completeness; they do not alter the native trace or run.
+
 </details>
 
 <details>
@@ -181,7 +225,7 @@ Zeroshot is **Layer 01 · Verification** of [The Open Engine](https://theopeneng
 | 02     | Constraints: **Opcore**    | Sibling · alpha             |
 | 03-05  | Intent · Context · Runtime | In development              |
 
-Zeroshot runs the loop: an agent writes the change, and an **independent** verifier decides whether it holds: approve, or a reproducible failure. **Opcore** is the sibling layer, a deterministic, local, read-only **constraints** gate for coding agents. Zeroshot packages Opcore `0.2.1` and uses introduced-change validation so existing repository debt never blocks an otherwise clean change. Verification asks _"does this meet the goal?"_; constraints ask _"is this within tolerance?"_
+Zeroshot runs the loop: an agent writes the change, and **independent** verifiers decide whether it holds, approving it or rejecting it with the specific objections that blocked it. **Opcore** is the sibling layer, a deterministic, local, read-only **constraints** gate for coding agents. Zeroshot packages Opcore `0.2.1` and uses introduced-change validation so existing repository debt never blocks an otherwise clean change. Verification asks _"does this meet the goal?"_; constraints ask _"is this within tolerance?"_
 
 Each layer ships the same way: extracted from the platform we run, then opened. **Trust nothing. Verify everything.**
 

package/cli/agent-provider-boundary.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripTimestampPrefix = exports.getProviderAdapter = void 0;
+function isRuntime(value, method) {
+    return (value !== null && typeof value === 'object' && typeof Reflect.get(value, method) === 'function');
+}
+function isAdapterRuntime(value) {
+    return isRuntime(value, 'getProviderAdapter');
+}
+function isPrefixRuntime(value) {
+    return isRuntime(value, 'stripTimestampPrefix');
+}
+const adapters = require('../lib/agent-cli-provider/adapters');
+const prefixes = require('../lib/agent-cli-provider/log-prefix');
+if (!isAdapterRuntime(adapters) || !isPrefixRuntime(prefixes)) {
+    throw new Error('Built agent-provider runtime is unavailable');
+}
+exports.getProviderAdapter = adapters.getProviderAdapter;
+exports.stripTimestampPrefix = prefixes.stripTimestampPrefix;

package/cli/agent-provider-boundary.ts

@@ -0,0 +1,79 @@
+interface TextEvent {
+  readonly type: 'text' | 'thinking';
+  readonly text: string;
+}
+
+interface ToolCallEvent {
+  readonly type: 'tool_call';
+  readonly toolName: string | null | undefined;
+  readonly toolId: string | null | undefined;
+  readonly input: unknown;
+}
+
+interface ToolResultEvent {
+  readonly type: 'tool_result';
+  readonly toolId: string | null | undefined;
+  readonly content: unknown;
+  readonly isError: unknown;
+}
+
+interface ResultEvent {
+  readonly type: 'result';
+  readonly success: boolean;
+  readonly result?: unknown;
+  readonly error?: unknown;
+  readonly cost?: unknown;
+  readonly duration?: unknown;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadInputTokens?: number;
+  readonly cacheCreationInputTokens?: number;
+  readonly modelUsage?: unknown;
+  readonly requests?: number;
+  readonly usageSource?: unknown;
+  readonly usageCompleteness?: unknown;
+  readonly invocation?: unknown;
+  readonly ompSdk?: unknown;
+}
+
+export type OutputEvent = TextEvent | ToolCallEvent | ToolResultEvent | ResultEvent;
+export type ProviderParseResult = OutputEvent | readonly OutputEvent[] | null;
+
+export interface ProviderAdapter {
+  readonly id: string;
+  readonly adapterVersion: string;
+  createParserState(): object;
+  parseEvent(line: string, state: object): ProviderParseResult;
+  finishParsing?(state: object): ProviderParseResult;
+}
+
+interface AdapterRuntime {
+  getProviderAdapter(provider: string): ProviderAdapter;
+}
+
+interface PrefixRuntime {
+  stripTimestampPrefix(line: string): string;
+}
+
+function isRuntime(value: unknown, method: string): boolean {
+  return (
+    value !== null && typeof value === 'object' && typeof Reflect.get(value, method) === 'function'
+  );
+}
+
+function isAdapterRuntime(value: unknown): value is AdapterRuntime {
+  return isRuntime(value, 'getProviderAdapter');
+}
+
+function isPrefixRuntime(value: unknown): value is PrefixRuntime {
+  return isRuntime(value, 'stripTimestampPrefix');
+}
+
+const adapters: unknown = require('../lib/agent-cli-provider/adapters');
+const prefixes: unknown = require('../lib/agent-cli-provider/log-prefix');
+if (!isAdapterRuntime(adapters) || !isPrefixRuntime(prefixes)) {
+  throw new Error('Built agent-provider runtime is unavailable');
+}
+
+export const getProviderAdapter = adapters.getProviderAdapter;
+export const stripTimestampPrefix = prefixes.stripTimestampPrefix;

package/cli/export-stream.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nullableString = nullableString;
+exports.isRecord = isRecord;
+exports.compareText = compareText;
+exports.sameFileSnapshot = sameFileSnapshot;
+exports.createExclusiveDestination = createExclusiveDestination;
+exports.createReplacingDestination = createReplacingDestination;
+exports.createRecordWriter = createRecordWriter;
+const crypto = require("crypto");
+const fs = require("fs");
+function nullableString(value) {
+    return typeof value === 'string' ? value : null;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function compareText(left, right) {
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
+}
+function sameFileSnapshot(before, after) {
+    return (before.dev === after.dev &&
+        before.ino === after.ino &&
+        before.size === after.size &&
+        before.mtimeNs === after.mtimeNs &&
+        before.ctimeNs === after.ctimeNs);
+}
+function writeAll(fd, value, label) {
+    const bytes = Buffer.from(value);
+    let offset = 0;
+    while (offset < bytes.length) {
+        const written = fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        if (!Number.isInteger(written) || written <= 0) {
+            throw new Error(`${label} export destination stopped accepting bytes`);
+        }
+        offset += written;
+    }
+}
+function streamDestination(stdout, label) {
+    if (typeof stdout.fd === 'number' && Number.isInteger(stdout.fd)) {
+        const fd = stdout.fd;
+        return { close() { }, write: (value) => writeAll(fd, value, label) };
+    }
+    return {
+        close() { },
+        write(value) {
+            stdout.write(value);
+        },
+    };
+}
+function createExclusiveDestination(outputPath, stdout, label) {
+    if (!outputPath)
+        return streamDestination(stdout, label);
+    const flags = fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_EXCL |
+        (fs.constants.O_NOFOLLOW || 0);
+    const fd = fs.openSync(outputPath, flags, 0o600);
+    try {
+        fs.fchmodSync(fd, 0o600);
+    }
+    catch (error) {
+        fs.closeSync(fd);
+        throw error;
+    }
+    return { close: () => fs.closeSync(fd), write: (value) => writeAll(fd, value, label) };
+}
+function createReplacingDestination(outputPath, stdout) {
+    if (!outputPath)
+        return streamDestination(stdout, 'JSON');
+    const fd = fs.openSync(outputPath, 'w');
+    return { close: () => fs.closeSync(fd), write: (value) => writeAll(fd, value, 'JSON') };
+}
+function createRecordWriter(destination) {
+    const digest = crypto.createHash('sha256');
+    let records = 0;
+    const encode = (record) => `${JSON.stringify(record)}\n`;
+    return {
+        get records() {
+            return records;
+        },
+        write(record) {
+            const line = encode(record);
+            digest.update(line);
+            destination.write(line);
+            records += 1;
+        },
+        finish(record) {
+            destination.write(encode({ ...record, preceding_records: records, records_sha256: digest.digest('hex') }));
+        },
+    };
+}

package/cli/export-stream.ts

@@ -0,0 +1,118 @@
+import crypto = require('crypto');
+import fs = require('fs');
+
+export interface ExportStream {
+  readonly fd?: number;
+  write(value: string): unknown;
+}
+
+export interface Destination {
+  close(): void;
+  write(value: string): void;
+}
+
+export interface RecordWriter {
+  readonly records: number;
+  finish(record: Record<string, unknown>): void;
+  write(record: Record<string, unknown>): void;
+}
+
+export function nullableString(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+}
+
+export function sameFileSnapshot(before: fs.BigIntStats, after: fs.BigIntStats): boolean {
+  return (
+    before.dev === after.dev &&
+    before.ino === after.ino &&
+    before.size === after.size &&
+    before.mtimeNs === after.mtimeNs &&
+    before.ctimeNs === after.ctimeNs
+  );
+}
+
+function writeAll(fd: number, value: string, label: string): void {
+  const bytes = Buffer.from(value);
+  let offset = 0;
+  while (offset < bytes.length) {
+    const written = fs.writeSync(fd, bytes, offset, bytes.length - offset);
+    if (!Number.isInteger(written) || written <= 0) {
+      throw new Error(`${label} export destination stopped accepting bytes`);
+    }
+    offset += written;
+  }
+}
+
+function streamDestination(stdout: ExportStream, label: string): Destination {
+  if (typeof stdout.fd === 'number' && Number.isInteger(stdout.fd)) {
+    const fd = stdout.fd;
+    return { close(): void {}, write: (value) => writeAll(fd, value, label) };
+  }
+  return {
+    close(): void {},
+    write(value): void {
+      stdout.write(value);
+    },
+  };
+}
+
+export function createExclusiveDestination(
+  outputPath: string | null | undefined,
+  stdout: ExportStream,
+  label: string
+): Destination {
+  if (!outputPath) return streamDestination(stdout, label);
+  const flags =
+    fs.constants.O_WRONLY |
+    fs.constants.O_CREAT |
+    fs.constants.O_EXCL |
+    (fs.constants.O_NOFOLLOW || 0);
+  const fd = fs.openSync(outputPath, flags, 0o600);
+  try {
+    fs.fchmodSync(fd, 0o600);
+  } catch (error) {
+    fs.closeSync(fd);
+    throw error;
+  }
+  return { close: () => fs.closeSync(fd), write: (value) => writeAll(fd, value, label) };
+}
+
+export function createReplacingDestination(
+  outputPath: string | null | undefined,
+  stdout: ExportStream
+): Destination {
+  if (!outputPath) return streamDestination(stdout, 'JSON');
+  const fd = fs.openSync(outputPath, 'w');
+  return { close: () => fs.closeSync(fd), write: (value) => writeAll(fd, value, 'JSON') };
+}
+
+export function createRecordWriter(destination: Destination): RecordWriter {
+  const digest = crypto.createHash('sha256');
+  let records = 0;
+  const encode = (record: Record<string, unknown>): string => `${JSON.stringify(record)}\n`;
+  return {
+    get records(): number {
+      return records;
+    },
+    write(record): void {
+      const line = encode(record);
+      digest.update(line);
+      destination.write(line);
+      records += 1;
+    },
+    finish(record): void {
+      destination.write(
+        encode({ ...record, preceding_records: records, records_sha256: digest.digest('hex') })
+      );
+    },
+  };
+}

package/cli/index.js

@@ -59,6 +59,7 @@ const {
 } = require('../lib/provider-names');
 const { commandExists } = require('../lib/provider-detection');
 const { getProvider, parseProviderChunk } = require('../src/providers');
+const { decodeTaskLogLine } = require('../src/task-log-line');
 const { readClustersFileSync } = require('../lib/clusters-registry');
 const { MOUNT_PRESETS, resolveEnvs } = require('../lib/docker-config');
 const {
@@ -78,7 +79,10 @@ const {
   resolveEffectiveRunPlan,
 } = require('../lib/start-cluster');
 const { requirePreflight } = require('../src/preflight');
+const { resolveTaskExecutionContext } = require('../src/task-execution-context');
 const {
+  buildForegroundResult,
+  exitCodeForForegroundResult,
   exitCodeForResult,
   isForegroundStatusSettled,
   writeForegroundResult,
@@ -752,16 +756,25 @@ async function finishForegroundRun({ cluster, orchestrator, clusterId, plan, res
       plan,
       Boolean(resultPath)
     );
-    if (!resultPath) return;
-    const receipt = writeForegroundResult({
+    if (resultPath) {
+      const receipt = writeForegroundResult({
+        orchestrator,
+        cluster,
+        clusterId,
+        resultPath,
+        cancelled: foreground.cancelled,
+      });
+      process.exitCode = exitCodeForResult(receipt);
+      console.log(chalk.dim(`Result ${receipt.outcome} committed to ${resultPath}`));
+      return;
+    }
+    const result = buildForegroundResult({
       orchestrator,
       cluster,
       clusterId,
-      resultPath,
       cancelled: foreground.cancelled,
     });
-    process.exitCode = exitCodeForResult(receipt);
-    console.log(chalk.dim(`Result ${receipt.outcome} committed to ${resultPath}`));
+    process.exitCode = exitCodeForForegroundResult(result);
   } finally {
     orchestrator.close();
   }
@@ -1418,19 +1431,10 @@ function startClusterDbPolling(cluster, clusterId, isActive, options) {
 }
 
 function parseIncrementalTaskLogLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed.startsWith('{')) {
-    return null;
-  }
-
-  let timestamp = Date.now();
-  let jsonContent = trimmed;
-
-  const timestampMatch = jsonContent.match(/^\[(\d{13})\](.*)$/);
-  if (timestampMatch) {
-    timestamp = parseInt(timestampMatch[1], 10);
-    jsonContent = timestampMatch[2];
-  }
+  const decoded = decodeTaskLogLine(line.trim());
+  if (!decoded.providerOutput) return null;
+  const timestamp = decoded.timestamp ?? Date.now();
+  const jsonContent = decoded.content.trim();
 
   if (!jsonContent.startsWith('{')) {
     return null;
@@ -2607,37 +2611,7 @@ function findAgentFromLifecycle(agents, taskId, lifecycleMessages) {
 }
 
 function parseTaskLogLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed.startsWith('[')) {
-    return null;
-  }
-
-  const parsed = parseTimestampedLine(trimmed);
-  if (!parsed.jsonContent.startsWith('{')) {
-    return null;
-  }
-
-  try {
-    const json = JSON.parse(parsed.jsonContent);
-    if (json.type === 'system' && json.subtype === 'init') {
-      return null;
-    }
-  } catch {
-    return null;
-  }
-
-  return parsed;
-}
-
-function parseTimestampedLine(line) {
-  const timestampMatch = line.match(/^\[(\d{13})\](.*)$/);
-  if (!timestampMatch) {
-    return { timestamp: Date.now(), jsonContent: line };
-  }
-  return {
-    timestamp: parseInt(timestampMatch[1], 10),
-    jsonContent: timestampMatch[2],
-  };
+  return parseIncrementalTaskLogLine(line);
 }
 
 function buildTaskLogMessage({ taskId, timestamp, jsonContent, cluster, agent, iteration }) {
@@ -3053,6 +3027,7 @@ taskCmd
         requireDocker: false, // Docker not needed for plain tasks
         quiet: false,
         provider: providerOverride,
+        executionContext: resolveTaskExecutionContext(),
       });
 
       // Dynamically import task command (ESM module)
@@ -3392,9 +3367,9 @@ program
   .command('export <cluster-id>')
   .helpGroup('Maintenance:')
   .description('Export cluster conversation')
-  .option('-f, --format <format>', 'Export format: json, markdown, html', 'html')
+  .option('-f, --format <format>', 'Export format: json, trace, semantic, markdown, html', 'html')
   .option('-o, --output <file>', 'Output file (auto-generated for html)')
-  .action((clusterId, options) => {
+  .action(async (clusterId, options) => {
     try {
       // Get messages from DB
       const Ledger = require('../src/ledger');
@@ -3405,14 +3380,7 @@ program
         throw new Error(`Cluster ${clusterId} not found (no DB file)`);
       }
 
-      // JSON export
-      if (options.format === 'json') {
-        exportClusterJson(dbPath, clusterId, options.output || null);
-        if (options.output) {
-          console.log(`Exported to ${options.output}`);
-        }
-        return;
-      }
+      if (await exportClusterDataFormat(dbPath, clusterId, options)) return;
 
       const ledger = new Ledger(dbPath);
       const messages = ledger.getAll(clusterId);
@@ -3727,6 +3695,7 @@ program
           requireDocker: false,
           quiet: false,
           provider: providerName,
+          executionContext: resolveTaskExecutionContext(),
         });
 
         // Try resuming as task
@@ -5092,9 +5061,18 @@ function formatToolCall(toolName, input) {
 function formatToolResult(content, isError, toolName, toolInput) {
   if (!content) return isError ? 'error' : 'done';
 
+  let normalizedContent = content;
+  if (typeof content !== 'string') {
+    try {
+      normalizedContent = JSON.stringify(content) ?? String(content);
+    } catch {
+      normalizedContent = String(content);
+    }
+  }
+
   // For errors, show full message
   if (isError) {
-    const firstLine = content.split('\n')[0].substring(0, 80);
+    const firstLine = normalizedContent.split('\n')[0].substring(0, 80);
     return chalk.red(firstLine);
   }
 
@@ -5123,7 +5101,7 @@ function formatToolResult(content, isError, toolName, toolInput) {
   }
 
   // For success, show summary
-  const lines = content.split('\n').filter((l) => l.trim());
+  const lines = normalizedContent.split('\n').filter((l) => l.trim());
   if (lines.length === 0) return 'done';
   if (lines.length === 1) {
     const line = lines[0].substring(0, 60);
@@ -6179,6 +6157,98 @@ function exportClusterJson(dbPath, clusterId, outputPath) {
   );
 }
 
+function tryExportClusterTraceSnapshot(dbPath, clusterId, outputPath, readTask, allowedLogRoot) {
+  const Ledger = require('../src/ledger');
+  const { streamClusterTraceExport } = require('./trace-export');
+  const ledger = new Ledger(dbPath, { readonly: true });
+  try {
+    return ledger.withReadSnapshot(() => {
+      if (ledger.needsAgentOutputReconciliation(clusterId)) return false;
+      streamClusterTraceExport({
+        ledger,
+        clusterId,
+        readTask,
+        allowedLogRoot,
+        outputPath,
+      });
+      return true;
+    });
+  } finally {
+    ledger.close();
+  }
+}
+
+function exportClusterTrace(dbPath, clusterId, outputPath, readTask, allowedLogRoot) {
+  const Ledger = require('../src/ledger');
+  const maxReconciliationAttempts = 3;
+  for (let attempt = 0; attempt <= maxReconciliationAttempts; attempt += 1) {
+    if (tryExportClusterTraceSnapshot(dbPath, clusterId, outputPath, readTask, allowedLogRoot)) {
+      return;
+    }
+    if (attempt === maxReconciliationAttempts) break;
+    const reconciliationLedger = new Ledger(dbPath);
+    reconciliationLedger.close();
+  }
+  throw new Error(
+    `Cluster ${clusterId} output changed during ${maxReconciliationAttempts} reconciliation attempts`
+  );
+}
+
+function tryExportClusterSemanticSnapshot(dbPath, clusterId, outputPath, readTask, allowedLogRoot) {
+  const Ledger = require('../src/ledger');
+  const { streamClusterSemanticExport } = require('./semantic-export');
+  const ledger = new Ledger(dbPath, { readonly: true });
+  try {
+    return ledger.withReadSnapshot(() => {
+      if (ledger.needsAgentOutputReconciliation(clusterId)) return false;
+      streamClusterSemanticExport({
+        ledger,
+        clusterId,
+        readTask,
+        allowedLogRoot,
+        outputPath,
+      });
+      return true;
+    });
+  } finally {
+    ledger.close();
+  }
+}
+
+function exportClusterSemantic(dbPath, clusterId, outputPath, readTask, allowedLogRoot) {
+  const Ledger = require('../src/ledger');
+  const maxReconciliationAttempts = 3;
+  for (let attempt = 0; attempt <= maxReconciliationAttempts; attempt += 1) {
+    if (tryExportClusterSemanticSnapshot(dbPath, clusterId, outputPath, readTask, allowedLogRoot)) {
+      return;
+    }
+    if (attempt === maxReconciliationAttempts) break;
+    const reconciliationLedger = new Ledger(dbPath);
+    reconciliationLedger.close();
+  }
+  throw new Error(
+    `Cluster ${clusterId} output changed during ${maxReconciliationAttempts} reconciliation attempts`
+  );
+}
+
+async function exportClusterDataFormat(dbPath, clusterId, options) {
+  if (options.format === 'json') {
+    exportClusterJson(dbPath, clusterId, options.output || null);
+    if (options.output) console.log(`Exported to ${options.output}`);
+    return true;
+  }
+  if (options.format !== 'trace' && options.format !== 'semantic') return false;
+
+  const [{ getTask }, { LOGS_DIR }] = await Promise.all([
+    import('../task-lib/store.js'),
+    import('../task-lib/config.js'),
+  ]);
+  const exporter = options.format === 'trace' ? exportClusterTrace : exportClusterSemantic;
+  exporter(dbPath, clusterId, options.output || null, getTask, LOGS_DIR);
+  if (options.output) console.log(`Exported ${options.format} to ${options.output}`);
+  return true;
+}
+
 // Main entry point
 async function main() {
   printLegacyDistroNotice();
@@ -6235,4 +6305,5 @@ module.exports = {
   buildCompletionPrompt,
   resolveRunMode,
   killRunningClusters,
+  parseTaskLogLine,
 };