@tangle-network/traces 0.12.0 → 0.15.1

package/dist/cli.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 import {
+  DEFAULT_ANALYST_MODEL,
+  DEFAULT_QUESTION_MAX_COST_USD,
   DEFAULT_SANDBOX_BASE_URL,
+  MAX_TRACE_QUESTION_CHARS,
+  analysisEngineFromEnv,
   appendAll,
   assembleSessionBundle,
+  assertOutsideSourceBundle,
   buildPolicyEvidenceRecord,
+  buildSessionFactsReport,
   buildSessionIndexFromRows,
   cmdReplayVerify,
   cmdReplayVerifyBatch,
@@ -13,17 +19,21 @@ import {
   commandRedactor,
   executeUpload,
   exportTraceEvidenceFile,
+  externalFailureMessage,
   fileRunContextSupervisorRunReader,
+  findingRejectionDetail,
   haloAnalyzer,
   hodoscopeAnalyzer,
   importCodeTraceBench,
   indexSessionIdsByTrace,
   inspectSessionIndex,
-  isFileRunContextDir,
+  isBridgeMismatchError,
   knownHarnesses,
+  loadTraceQuestionsFile,
   loadTracesConfig,
   locateSessions,
   mergeTracesConfig,
+  normalizeTraceQuestions,
   parseCorpusFlag,
   parseSession,
   parseSince,
@@ -33,12 +43,14 @@ import {
   readOtlpInput,
   readSessionIndexFile,
   renderInspectionReport,
+  renderSessionFacts,
   renderValidation,
   renderVerifiedFindingsSection,
   resolveAdapter,
   resolveRunWatchTarget,
   runTraceImprovement,
   runTraceInvestigation,
+  runTraceQuestions,
   saveReport,
   selectAdapters,
   serializePolicyEvidence,
@@ -57,89 +69,23 @@ import {
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
-  writeTraceEvidenceExportFile
-} from "./chunk-CV22VGCK.js";
+  writeTraceEvidenceExportFile,
+  writeTraceQuestionsArtifacts
+} from "./chunk-7DOBU7BJ.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { readdir, readFile, stat } from "fs/promises";
+import { mkdir, mkdtemp, readFile, stat, writeFile } from "fs/promises";
+import { tmpdir } from "os";
 import { basename, join, resolve } from "path";
 import {
   analyzeSupervisorRun,
   findSupervisorRunDirs,
-  isUnavailable,
+  isRuntimeSupervisorRunDir,
   renderSupervisorRollupMarkdown,
   renderSupervisorRunMarkdown,
   rollupSupervisorRuns
 } from "@tangle-network/agent-eval/supervisor-run";
-import { createDspyRlmTraceEngine } from "@tangle-network/agent-eval/analyst";
-
-// src/analyst-model-call.ts
-import {
-  callLlm,
-  costReceiptFromLlm,
-  costReceiptFromLlmError,
-  LlmCallError
-} from "@tangle-network/agent-eval";
-var PROVIDER_ERROR_BODY_LIMIT = 2e3;
-function createAnalystModelCall(opts) {
-  const { apiKey, baseUrl } = opts;
-  return async ({ request, callId, signal }) => {
-    try {
-      const req = structuredClone(request);
-      const response = await callLlm(req, {
-        apiKey,
-        baseUrl,
-        signal,
-        idempotencyKey: callId
-      });
-      return {
-        succeeded: true,
-        response,
-        receipt: costReceiptFromLlm(response),
-        execution: {
-          callId,
-          baseUrl,
-          requestedModel: req.model,
-          servedModel: response.servedModel ?? null,
-          finishReason: response.finishReason ?? null,
-          durationMs: response.durationMs
-        }
-      };
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      const aborted = signal.aborted;
-      const message = aborted ? `AbortError: ${err.message}` : err.message;
-      const detail = err instanceof LlmCallError ? { status: err.status, body: err.body.slice(0, PROVIDER_ERROR_BODY_LIMIT) } : {};
-      return {
-        succeeded: false,
-        error: message,
-        // costReceiptFromLlmError recovers the provider receipt when the
-        // response completed but violated the contract; otherwise usage and
-        // cost stay explicitly unknown.
-        receipt: costReceiptFromLlmError(err) ?? {
-          model: request.model,
-          inputTokens: 0,
-          outputTokens: 0,
-          costUnknown: true,
-          usageUnknown: true
-        },
-        execution: {
-          callId,
-          baseUrl,
-          requestedModel: request.model,
-          aborted,
-          error: message,
-          ...detail
-        }
-      };
-    }
-  };
-}
-
-// src/cli.ts
-var DEFAULT_ANALYST_MODEL = "gpt-5-mini";
-var TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
 function packageVersion() {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
@@ -173,7 +119,8 @@ function parseArgs(argv) {
     attrs: [],
     concurrency: 4,
     verifyFindings: false,
-    replayCorpora: []
+    replayCorpora: [],
+    questions: []
   };
   for (let i = 1; i < argv.length; i++) {
     const arg = argv[i];
@@ -231,6 +178,9 @@ function parseArgs(argv) {
       case "--otlp":
         a.otlp = next();
         break;
+      case "--source-bundle":
+        a.sourceBundle = next();
+        break;
       case "--otlp-out":
         a.otlpOut = next();
         break;
@@ -310,6 +260,17 @@ function parseArgs(argv) {
       case "--analyzer-prompt":
         a.analyzerPrompt = next();
         break;
+      case "--question": {
+        const v = next();
+        if (v !== void 0) a.questions.push(v);
+        break;
+      }
+      case "--questions":
+        a.questionsFile = next();
+        break;
+      case "--question-budget":
+        a.questionBudget = Number(next());
+        break;
       case "--redactor":
         a.redactorCmd = next();
         break;
@@ -332,7 +293,7 @@ function parseArgs(argv) {
   }
   return a;
 }
-var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "investigate", "improve", "stream", "validate"]);
+var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "facts", "investigate", "improve", "ask", "stream", "validate"]);
 function migrateWritingOtlpFlag(args) {
   if (args.otlp === void 0 || OTLP_INPUT_COMMANDS.has(args.command)) return args;
   if (args.otlpOut !== void 0) {
@@ -358,8 +319,10 @@ function validateOtlpSelection(raw) {
 }
 var CURRENT_SESSION_COMMANDS = /* @__PURE__ */ new Set([
   "analyze",
+  "facts",
   "investigate",
   "improve",
+  "ask",
   "convert",
   "index",
   "evidence",
@@ -368,8 +331,10 @@ var CURRENT_SESSION_COMMANDS = /* @__PURE__ */ new Set([
 ]);
 var WORKFLOW_COMMANDS = /* @__PURE__ */ new Set([
   "analyze",
+  "facts",
   "investigate",
   "improve",
+  "ask",
   "convert",
   "index",
   "evidence"
@@ -484,41 +449,11 @@ async function resolveSelectedSession(args) {
     `session ID "${args.session}" is ambiguous across ${matches.length} files; select one harness or pass its explicit session path`
   );
 }
-function buildAnalysisEngine(model, budgetUsd) {
-  const tangleKey = process.env.TANGLE_API_KEY;
-  const openAiKey = process.env.OPENAI_API_KEY;
-  const apiKey = tangleKey || openAiKey;
-  if (!apiKey) {
-    throw new Error(
-      "--llm needs a model key: TANGLE_API_KEY for the Tangle router (the default endpoint), or OPENAI_API_KEY for OpenAI. Set OPENAI_BASE_URL to target any other OpenAI-compatible gateway. Deterministic analysis needs no key."
-    );
-  }
-  const baseUrl = process.env.OPENAI_BASE_URL || (tangleKey ? TANGLE_ROUTER_BASE_URL : "https://api.openai.com/v1");
-  const python = process.env.TRACES_PYTHON;
-  return createDspyRlmTraceEngine({
-    call: createAnalystModelCall({ apiKey, baseUrl }),
-    callRef: `traces-cli:${baseUrl}#${model}`,
-    recordExecution: (observation) => {
-      analystLog(
-        `[analyst] model call ${observation.sequence} ${observation.succeeded ? "ok" : "FAIL"} ${observation.model}`,
-        observation.succeeded ? void 0 : { error: observation.error }
-      );
-    },
-    model,
-    // Pinned, not defaulted: one findings array from a current coding model
-    // needs this cap, and glm-5.2 counts reasoning tokens in
-    // completion_tokens — a smaller cap breaches its cost reservation and the
-    // fail-closed ledger then refuses every later call in the run.
-    maxOutputTokens: 16384,
-    // maxCostUsd defaults to $1 per analyst — a proxy-side ceiling separate
-    // from --budget. With the larger token cap the per-call reservation grows
-    // ~4x, so that default binds before the registry's --budget allocation
-    // and kills analysts mid-run. --budget is the operator's spend authority
-    // and the registry still splits it across analysts, so forwarding it here
-    // only stops the engine's own default from cutting runs short.
-    ...budgetUsd !== void 0 && Number.isFinite(budgetUsd) && budgetUsd > 0 ? { maxCostUsd: budgetUsd } : {},
-    ...python ? { runner: { command: python } } : {}
-  });
+function llmAnalysisEngine(args, model) {
+  return analysisEngineFromEnv({ model, maxCostUsd: args.budget, log: analystLog });
+}
+function analystModelFor(args) {
+  return args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
 }
 function requiredBridgeVersion() {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -528,11 +463,14 @@ function requiredBridgeVersion() {
   }
   return version;
 }
-function assertAgenticAnalystsRan(args, agenticPerAnalyst) {
-  if (!args.llm) return;
-  if (!totalAgenticFailureMessage(agenticPerAnalyst)) return;
-  const message = totalAgenticFailureMessage(agenticPerAnalyst, { requiredBridgeVersion: requiredBridgeVersion() });
-  throw new Error(message);
+function assertRequestedAnalysesRan(args, result) {
+  const messages = [];
+  if (args.llm && totalAgenticFailureMessage(result.agenticPerAnalyst)) {
+    messages.push(totalAgenticFailureMessage(result.agenticPerAnalyst, { requiredBridgeVersion: requiredBridgeVersion() }));
+  }
+  const external = externalFailureMessage(result.external);
+  if (external) messages.push(external);
+  if (messages.length > 0) throw new Error(messages.join("\n"));
 }
 async function cmdList(args) {
   const groups = await discover({ ...args, last: args.last || 20 });
@@ -582,6 +520,16 @@ async function collectOtlpSpans(path) {
   };
 }
 async function collectSpans(args) {
+  if (args.sourceBundle) {
+    if (!["analyze", "investigate", "improve", "ask"].includes(args.command)) throw new Error("--source-bundle is an analysis option");
+    if (args.session || args.otlp || args.input || args.current || args.workflow || args.noContent || args.redactorCmd) {
+      throw new Error("--source-bundle cannot be combined with another input, redaction, or metadata-only selection");
+    }
+    for (const output of [args.out, args.dir, args.otlpOut]) {
+      if (output) await assertOutsideSourceBundle(args.sourceBundle, output);
+    }
+    return collectOtlpSpans(join(args.sourceBundle, "derived", "trace.otlp.jsonl"));
+  }
   if (args.otlp) return collectOtlpSpans(args.otlp);
   if (args.input) {
     if (args.workflow) throw new Error("--workflow reads discovered sessions and cannot be combined with an input file");
@@ -647,6 +595,9 @@ function workflowIssueText(issue) {
   if (issue.kind === "parent-conflict") {
     return `parent conflict for ${issue.sessionId}: declared ${issue.declaredParentSessionId ?? "none"}, referenced by ${issue.referencedParentSessionIds.join(", ") || "none"}`;
   }
+  if (issue.kind === "unjoined-child") {
+    return `unjoined child ${issue.agentPath} spawned by ${issue.parentSessionId}: ${issue.reason}` + (issue.candidates ? ` (${issue.candidates.join(", ")})` : "");
+  }
   return `${issue.kind} ${issue.sessionId}, referenced as ${issue.relation} by ${issue.referencedBySessionId}`;
 }
 function warnIncompleteWorkflow(workflow) {
@@ -754,6 +705,30 @@ async function cmdBundleView(args) {
     `${manifest.view} view \u2192 ${result.directory}  (${manifest.files.length} file(s) carried, ${manifest.excluded.length} excluded, ${leakCheck.matches} session-text match(es) against ${leakCheck.sourceSignatures} signature(s) from ${leakCheck.comparedSources.length} excluded source(s))`
   );
 }
+async function cmdFacts(args) {
+  const format = args.format ?? "json";
+  if (format !== "json" && format !== "text") {
+    throw new Error(`unknown facts format "${format}" (expected json or text)`);
+  }
+  const collected = await collectSpans(args);
+  if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
+  warnIncompleteWorkflow(collected.workflow);
+  const report = buildSessionFactsReport(collected.spans, { harness: collected.harness });
+  const unread = report.sessions.filter((facts) => facts.recordSpans === 0);
+  if (unread.length > 0) {
+    throw new Error(
+      `no records could be read from ${unread.length} selected session(s): ` + unread.map((facts) => `${facts.sessionId ?? facts.traceId} (${facts.unreadRecords.value ?? 0} unread record(s))`).join(", ") + ". The facts sheet would state zeros the spans cannot support."
+    );
+  }
+  const rendered = format === "json" ? `${JSON.stringify(report, null, 2)}
+` : renderSessionFacts(report);
+  if (args.out) {
+    await writeFile(args.out, rendered, "utf8");
+    console.log(`session facts \u2192 ${args.out}  (${report.sessions.length} session(s), $0, no model call)`);
+    return;
+  }
+  process.stdout.write(rendered);
+}
 async function cmdInspect(args) {
   if (!args.input) throw new Error("inspect needs an index file; run `traces index --out session-index.json` first");
   const index = await readSessionIndexFile(args.input);
@@ -876,7 +851,7 @@ ${renderVerifiedFindingsSection(run)}`;
   } else {
     console.log(report);
   }
-  assertAgenticAnalystsRan(args, result.agenticPerAnalyst);
+  assertRequestedAnalysesRan(args, result);
 }
 async function verifyAnalyzeFindings(args, result) {
   if (args.replayCorpora.length === 0) {
@@ -898,55 +873,24 @@ async function verifyAnalyzeFindings(args, result) {
   });
 }
 async function cmdAnalyzeSupervisorRun(runDir, args) {
-  const runContextDirs = await findFileRunContextDirs(runDir);
-  const nested = runContextDirs.length > 0 ? [] : await findSupervisorRunDirs(runDir);
-  let markdown;
-  if (runContextDirs.length > 1) {
-    markdown = renderSupervisorRollupMarkdown(
-      rollupSupervisorRuns(
-        await Promise.all(
-          runContextDirs.map((dir) => analyzeSupervisorRun(fileRunContextSupervisorRunReader(dir)))
-        )
-      ),
-      `Supervisor rollup \u2014 ${runDir}`
-    );
-  } else if (runContextDirs.length === 1) {
-    markdown = renderSupervisorRunMarkdown(
-      await analyzeSupervisorRun(fileRunContextSupervisorRunReader(runContextDirs[0]))
-    );
-  } else if (nested.length > 0) {
-    markdown = renderSupervisorRollupMarkdown(
-      rollupSupervisorRuns(await Promise.all(nested.map((dir) => analyzeSupervisorRun(dir)))),
-      `Supervisor rollup \u2014 ${runDir}`
+  const single = await isRuntimeSupervisorRunDir(runDir);
+  const runDirs = single ? [runDir] : await findSupervisorRunDirs(runDir);
+  if (runDirs.length === 0) {
+    throw new Error(
+      `no supervisor run found at ${runDir} \u2014 expected a Runtime run containing spawn-journal.jsonl, observer.jsonl, or failure.json, or a parent directory containing such runs`
     );
-  } else {
-    const report = await analyzeSupervisorRun(runDir);
-    if (isUnavailable(report.orchestration.workersSpawned)) {
-      throw new Error(
-        `no supervisor run found at ${runDir} \u2014 expected <runDir>/spawn-journal.jsonl (agent-runtime createFileRunContext), <runDir>/ws/.agent/supervisor/<id> (or the pre-rename <runDir>/ws/.loops/supervisor/<id>), or a parent directory containing such runs`
-      );
-    }
-    markdown = renderSupervisorRunMarkdown(report);
   }
-  const runs = Math.max(runContextDirs.length, nested.length, 1);
+  const reports = await Promise.all(
+    runDirs.map((dir) => analyzeSupervisorRun(fileRunContextSupervisorRunReader(dir)))
+  );
+  const markdown = single ? renderSupervisorRunMarkdown(reports[0]) : renderSupervisorRollupMarkdown(rollupSupervisorRuns(reports), `Supervisor rollup \u2014 ${runDir}`);
   if (args.out) {
     await saveReport(args.out, markdown);
-    console.log(`supervisor report \u2192 ${args.out}  (${runs === 1 ? "1 run" : `${runs} runs`})`);
+    console.log(`supervisor report \u2192 ${args.out}  (${runDirs.length === 1 ? "1 run" : `${runDirs.length} runs`})`);
   } else {
     console.log(markdown);
   }
 }
-async function findFileRunContextDirs(dir) {
-  if (await isFileRunContextDir(dir)) return [dir];
-  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
-  const found = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const child = join(dir, entry.name);
-    if (await isFileRunContextDir(child)) found.push(child);
-  }
-  return found.sort();
-}
 async function collectImportedSpans(args) {
   if (!args.input) throw new Error("input file missing");
   const attributes = await loadExportAttributes(args);
@@ -977,6 +921,13 @@ async function collectImportedSpans(args) {
   };
 }
 function analystLog(msg, fields) {
+  const rejection = findingRejectionDetail(msg, fields);
+  if (rejection !== void 0) {
+    process.stderr.write(rejection ? `${msg} \u2014 ${rejection}
+` : `${msg}
+`);
+    return;
+  }
   const error = typeof fields?.error === "string" && fields.error ? fields.error : void 0;
   const errorClass = typeof fields?.error_class === "string" && fields.error_class ? `${fields.error_class}: ` : "";
   process.stderr.write(error ? `${msg} \u2014 ${errorClass}${error}
@@ -996,7 +947,7 @@ async function cmdInvestigate(args) {
   } else {
     console.log(result.report);
   }
-  assertAgenticAnalystsRan(args, result.agenticPerAnalyst);
+  assertRequestedAnalysesRan(args, result);
 }
 function conformanceOptions(collected) {
   return {
@@ -1014,9 +965,10 @@ async function investigate(args, options = {}) {
   const { spans, harness, cwds, sources, workflow } = collected;
   if (spans.length === 0) throw new Error("no spans found for the given selection");
   const config = args.config !== void 0 || options.loadDefaultConfig !== false ? await loadTracesConfig(args.config) : void 0;
-  const analystModel = args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
-  const engine = args.llm ? buildAnalysisEngine(analystModel, args.budget) : void 0;
+  const analystModel = analystModelFor(args);
+  const engine = args.llm ? llmAnalysisEngine(args, analystModel) : void 0;
   return runTraceInvestigation(mergeTracesConfig({
+    sourceBundle: args.sourceBundle ? { path: args.sourceBundle } : void 0,
     spans,
     harness,
     sources,
@@ -1038,10 +990,11 @@ async function cmdImprove(args) {
   const { spans, harness, cwds, sources, workflow } = collected;
   if (spans.length === 0) throw new Error("no spans found for the given selection");
   const config = await loadTracesConfig(args.config);
-  const analystModel = args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
-  const engine = args.llm ? buildAnalysisEngine(analystModel, args.budget) : void 0;
+  const analystModel = analystModelFor(args);
+  const engine = args.llm ? llmAnalysisEngine(args, analystModel) : void 0;
   const result = await runTraceImprovement({
     ...mergeTracesConfig({
+      sourceBundle: args.sourceBundle ? { path: args.sourceBundle } : void 0,
       spans,
       harness,
       sources,
@@ -1064,7 +1017,76 @@ async function cmdImprove(args) {
   console.log(
     `improvement artifacts \u2192 ${dir}  (${result.findings.length} findings with actions and checks, OTLP: ${result.otlpPath})`
   );
-  assertAgenticAnalystsRan(args, result.agenticPerAnalyst);
+  assertRequestedAnalysesRan(args, result);
+}
+async function cmdAsk(args) {
+  if (args.out) throw new Error("ask writes a directory of artifacts; pass --dir <dir> instead of --out");
+  if (args.llm) throw new Error("ask always uses the model-backed engine; drop --llm");
+  const questions = [
+    ...args.questionsFile ? await loadTraceQuestionsFile(args.questionsFile) : [],
+    ...args.questions.map((question) => ({ question }))
+  ];
+  if (questions.length === 0) {
+    throw new Error('ask needs --question "<text>" (repeatable) or --questions <questions.json>');
+  }
+  normalizeTraceQuestions(questions);
+  if (args.questionBudget !== void 0 && (!Number.isFinite(args.questionBudget) || args.questionBudget <= 0)) {
+    throw new Error("--question-budget must be a positive number of USD");
+  }
+  if (args.budget !== void 0 && (!Number.isFinite(args.budget) || args.budget <= 0)) {
+    throw new Error("--budget must be a positive number of USD");
+  }
+  const engine = analysisEngineFromEnv({
+    model: analystModelFor(args),
+    maxCostUsd: args.questionBudget ?? Math.min(args.budget ?? Infinity, DEFAULT_QUESTION_MAX_COST_USD),
+    log: analystLog
+  });
+  const collected = await collectSpans(args);
+  if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
+  warnIncompleteWorkflow(collected.workflow);
+  const directory = resolve(args.dir ?? await mkdtemp(join(tmpdir(), "traces-ask-")));
+  await mkdir(directory, { recursive: true });
+  const controller = new AbortController();
+  const interrupt = () => controller.abort(new Error("ask interrupted"));
+  process.once("SIGINT", interrupt);
+  let result;
+  try {
+    result = await runTraceQuestions({
+      questions,
+      spans: collected.spans,
+      engine,
+      harness: collected.harness,
+      concurrency: args.concurrency,
+      ...args.budget !== void 0 ? { budgetUsd: args.budget } : {},
+      ...args.sourceBundle ? { sourceBundle: { path: args.sourceBundle } } : {},
+      otlpOutPath: args.otlpOut ?? join(directory, "traces.otlp.jsonl"),
+      signal: controller.signal,
+      log: analystLog
+    });
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+  }
+  const artifacts = await writeTraceQuestionsArtifacts(result, directory);
+  process.stdout.write(result.report);
+  for (const warning of result.warnings) process.stderr.write(`warning: ${warning}
+`);
+  process.stderr.write(
+    `ask artifacts \u2192 ${artifacts.directory}  (${result.totals.answered}/${result.totals.questions} answered, wall ${(result.totals.wallTimeMs / 1e3).toFixed(1)} s, answers: ${artifacts.result})
+`
+  );
+  if (!result.ok) {
+    const failed = result.questions.filter((answer) => answer.status === "failed");
+    const lines = [
+      `${failed.length} of ${result.questions.length} question(s) failed; the answers file holds every result.`,
+      ...failed.map((answer) => `  ${answer.id}: ${answer.failure?.kind}: ${answer.failure?.message.slice(0, 300)}`)
+    ];
+    if (failed.some((answer) => isBridgeMismatchError(answer.failure?.message ?? ""))) {
+      lines.push(
+        `hint: the DSPy bridge protocol is version-locked \u2014 the TRACES_PYTHON interpreter needs agent-eval-rpc[dspy]==${requiredBridgeVersion()} (matching this package's @tangle-network/agent-eval).`
+      );
+    }
+    throw new Error(lines.join("\n"));
+  }
 }
 function summarizeFindingEvidence(finding) {
   const first = finding.evidence[0];
@@ -1387,6 +1409,17 @@ Commands:
             (--supervisor-run-dir <dir> reports a supervision tree instead)
   investigate Run typed investigation flow, including BYO config + evidence-backed actions
   improve   Write findings, evidence, report, and canonical trace artifacts
+  ask       Answer free-form questions over the selected sessions with the
+            model-backed engine: questions run concurrently under one budget,
+            every trace:// citation is checked, and answers.json + report.md
+            are written to --dir (exit 1 when any question fails)
+  facts     Print the deterministic session-facts sheet for the selected
+            sessions: tool calls excluding synthesized spans, subagent spawns
+            with task names, human turns in order, the final message per task,
+            changed paths, first/last record times, and the harness token total.
+            No model call, no budget, $0. Every fact names the span ids it came
+            from; a fact the spans cannot support is null with its reason.
+            --format json (default) or text (exit 1 when a session cannot be read)
   convert   Emit OTLP-JSONL only, to --otlp-out (HALO: use analyze --analyzer halo)
   index     Emit a reusable session index JSON for later investigation
   bundle    Assemble one session's durable evidence directory: transcript +
@@ -1435,21 +1468,24 @@ Options:
                    analyze: report a SUPERVISION TREE instead of harness sessions \u2014
                    steers, spawn waves, concurrency, idle wall, cost by role,
                    accepted vs rejected. Rolls up when the dir holds many runs.
-                   watch: same directory, live. Reads the loops layout, the
-                   agent-runtime createFileRunContext journal, and OTLP span files.
+                   analyze reads Runtime journals and recorded startup failures.
+                   watch reads a live Runtime journal and OTLP span files.
   --since <t>      upload: window, 30m / 2h / 7d or an ISO date (default 24h); analyze: ISO cutoff
   --out <path>     Write report to a file
-  --dir <path>     improve: write artifacts to this directory
+  --dir <path>     improve/ask: write artifacts to this directory
   --otlp <file|dir>  READ OTLP-JSONL emitted by any system, skipping the adapters.
                    A directory reads the OTLP files under it \u2014 only the otlp/
                    subdirectory when the producer made one \u2014 and names the JSONL
                    that is not OTLP instead of reading it as broken spans.
-                   Supported by: validate, analyze, investigate, improve, stream.
+                   Supported by: validate, analyze, investigate, improve, ask, stream.
                    On a WRITING command it is the deprecated spelling of
                    --otlp-out; it still works, with a warning, until 0.12.
+  --source-bundle <dir>  Analyze a retained full bundle; explicitly grant source-field reads.
+                   Available for analyze, investigate, improve, and ask.
   --otlp-out <path>  WRITE the OTLP-JSONL artifact here (also evidence
                    provenance / dry-run upload preview)
   --format <kind>  analyze/export: auto | policy-evidence | sandbox-events | openinference | intelligence-spans | chat-trajectory
+                   facts: json (default) | text
   --metadata <json> analyze/export file: attach JSON object fields as span attributes
   --attr <k=v>     analyze/export file: attach one span attribute (repeatable)
   --mode <kind>    stream: visualizer | findings | agent (default visualizer)
@@ -1466,10 +1502,20 @@ Options:
                    agent-eval-rpc[dspy] (TRACES_PYTHON selects the interpreter),
                    version-matched to this package's @tangle-network/agent-eval.
                    Exits 1 when every agentic analyst fails, with each reason.
+                   ask uses the same engine and credentials without --llm.
   --model <id>     Model for --llm, HALO, and Hodoscope (default for --llm: ${DEFAULT_ANALYST_MODEL})
   --config <path>  investigate/improve/stream: JS config with analysts, liveAnalysts, or external analyzers
-  --budget <usd>   USD cap for agentic analysts
-  --analyzer <id>  analyze: also run halo, hodoscope, prime, or an installed command (repeatable)
+  --budget <usd>   USD cap for agentic analysts; ask: one ceiling shared by every question
+  --question <text> ask: a question (repeatable, at most ${MAX_TRACE_QUESTION_CHARS} characters)
+  --questions <file> ask: JSON array of questions, strings or
+                   { id?, question, instructions?, answerSchema? }
+  --question-budget <usd>
+                   ask: provider ceiling for one question (default: the smaller
+                   of --budget and $${DEFAULT_QUESTION_MAX_COST_USD})
+  --concurrency <n> ask: questions running at once (default 4);
+                   import-codetracebench: trajectories imported at once
+  --analyzer <id>  analyze: also run halo, hodoscope, prime, or an installed command (repeatable);
+                   exits 1 after writing the report when any requested analyzer fails
                    prime posts the full span projection to an OpenAI-compatible bridge
                    (TRACES_PRIME_BRIDGE_URL, default http://localhost:4181;
                    TRACES_PRIME_MODEL, default prime/zai/glm-5.2; TRACES_PRIME_TIMEOUT_MS)
@@ -1551,6 +1597,12 @@ async function main() {
     case "improve":
       await cmdImprove(args);
       break;
+    case "ask":
+      await cmdAsk(args);
+      break;
+    case "facts":
+      await cmdFacts(args);
+      break;
     case "convert":
       await cmdConvert(args);
       break;