@tangle-network/traces 0.22.0 → 0.23.0

package/README.md

@@ -295,6 +295,7 @@ traces investigate --all --last 10 --out report.md  # explicit investigation ali
 traces improve --all --last 10 --dir .traces/improvement
 traces ask --harness codex --session <id> --question "Which commands failed?"
 traces facts --harness codex --session <id>        # the deterministic facts sheet, $0
+traces facts --all --since 2026-10-14 --until 2026-10-15  # every session with a record that day, that day's turns
 traces skills --since 30d                          # skill use across every local session, incremental, $0
 traces diff  run-a.otlp.jsonl run-b.otlp.jsonl      # where two runs of one task first diverge
 traces mcp   --otlp spans.otlp.jsonl                # read-only trace tools for an MCP client
@@ -347,7 +348,8 @@ See [Replay verification](./docs/replay-verify.md) for setup, semantics, and hon
 | `--workflow` | Expand selected files through stable parent and child session IDs |
 | `--max-workflow-sessions <n>` | Stop workflow expansion before parsing more than `n` files; default `100` |
 | `--cwd <dir>` | Filter by working directory |
-| `--since <t>` | `upload`: window, `30m`/`2h`/`7d` or ISO (default 24h); `analyze`: ISO cutoff |
+| `--since <t>` | `30m`/`2h`/`7d` before now, or an ISO date. Commands that select sessions read those modified at or after it; `upload`: its window (default 24h); `facts`: opens a time window — see [Session facts](#session-facts) |
+| `--until <t>` | `facts`: closes the time window (exclusive), same forms as `--since` |
 | `--out <path>` | Write the report to a file |
 | `--dir <path>` | `improve`: write the full artifact pack to this directory; `ask`: write `answers.json` + `report.md` there |
 | `--otlp <file\|dir>` | **READ** OTLP-JSONL from any system, skipping the adapters; a directory reads the OTLP files under it (only `otlp/` when the producer made one) and names the JSONL that is not OTLP. `validate`, `check`, `analyze`, `investigate`, `improve`, `ask`, `stream` |
@@ -590,11 +592,14 @@ The same facts sheet includes observed tool outcomes, captured input/output byte
 volumes, call-to-result intervals, compaction boundaries and available context
 sizes, spawn intervals, and existing skill invocation/document-read evidence.
 Each measurement carries coverage; absent telemetry remains unknown.
-`facts --no-content` withholds conversation, command, changed-file and assignment
-text while retaining measurement metadata. This is a local metadata view, not a
+`facts --no-content` withholds conversation (including each turn's `answered` text),
+command, changed-file, working-directory and assignment text while retaining
+measurement metadata. This is a local metadata view, not a
 share-safety certificate.
 
 SDK consumers use `buildSessionFactsReport(spans, { includeContent: false })`.
+Pass `window: { since, until }` (ISO bounds) for the windowed report `facts --since/--until` prints, and use
+`createSessionFactsReportBuilder(options)` (`add(spans)`, `addUnread(...)`, `build()`) to build it one session at a time.
 Cache by `measurementVersion` and `sourceDigest`; `evidenceThrough` is the latest
 recorded endpoint, not current liveness. Computing the sheet parses the supplied
 spans; returning a stored sheet needs no model call or trace scan. Semantic
@@ -608,8 +613,17 @@ No model call, no engine, no budget — it costs $0 and always returns the same
 traces facts --harness codex --session <id>                 # JSON on stdout
 traces facts --harness codex --last 5 --format text         # the short readable form
 traces facts --otlp spans.otlp.jsonl --out facts.json
+traces facts --harness claude-code --since 7d               # every session with a record in the last week
+traces facts --all --since 2026-10-14 --until 2026-10-15    # one day, across every harness
 ```
 
+`--since <t>` and `--until <t>` open a half-open time window `[since, until)`; each takes `30m`/`2h`/`7d` before now or an ISO date, and either may be left open.
+With a window, `facts` selects **every** session with a record that starts or ends inside it, not only the newest (`--last <n>` still caps it to the newest `n` per harness, and `--session` or `--otlp` still name the input).
+Sessions are read one at a time, and a session file last modified before `since` is not read, because it cannot hold a later record.
+Within a selected session, `humanTurns`, `excludedTurns` and `turnsByActor` keep only turns that started inside the window, so a one-day run counts only that day's turns; every other fact covers the whole session.
+The report's `selection` states the window, both rules, the sessions read whose records all fell outside it (`outsideWindow`), and every session that could not be read (`unreadSessions`, each with its reason).
+A report built without a window has `selection: null`.
+
 | Fact | What it is |
 |---|---|
 | `toolCalls` | TOOL spans **this session's agent** actually invoked. Synthesized lifecycle spans are excluded and counted in `synthesizedToolSpans`, so the total is not high by the number of subagents; calls a spawned subagent made are excluded and counted in `subagentToolSpans` |
@@ -617,7 +631,8 @@ traces facts --otlp spans.otlp.jsonl --out facts.json
 | `subagentToolSpans` | TOOL spans excluded because a subagent, not this agent, made the call. Zero on a trace that carries no subagent records |
 | `subagents` | every subagent-spawning call with the task name the adapter recorded |
 | `pullRequests` | the pull requests the commands created and merged, each named by number or head branch, with the command span and how the identity was joined. Scanned the way a shell reads the script, so a `gh pr create` inside a heredoc body is not a command that ran |
-| `humanTurns` | `user.prompt` turns a person typed into this session, in order, with the timestamp. Inherited fork or compaction history, harness-injected blocks, and a second record of the same turn are excluded — each listed in `excludedTurns` with its reason and span ids, never silently dropped. `turnsByActor` shows every turn by actor so the filter is checkable |
+| `cwd` | the working directory the harness recorded for the session (`traces.session.cwd` on the root span): Claude Code's first record `cwd`, Codex's `session_meta` cwd, Pi's session header, OpenCode's session directory (the older JSON store: its messages' `path.cwd`), Factory's `session_start`. Never decoded from a directory name or inferred from paths; `null` with the reason when the source names none or its adapter does not read one |
+| `humanTurns` | `user.prompt` turns a person typed into this session, in order, with the timestamp. Inherited fork or compaction history, harness-injected blocks, and a second record of the same turn are excluded — each listed in `excludedTurns` with its reason and span ids, never silently dropped. `turnsByActor` shows every turn by actor so the filter is checkable. Each turn's `answered` is the last message this session's own agent wrote before it (not a subagent's, not inherited history), clipped to 1,500 characters with a `… [+N chars]` marker, with its span in `answeredSpanId`; `null` when the agent had written no text yet in the spans read (a `--latest-turn` read starts at the latest task, so its first turn has none) |
 | `finalMessages` | the last message of the session's own agent, and of each subagent task, kept apart |
 | `changedFiles` | paths the harness recorded for the changes it applied, plus paths named by patch headers and file-editing tool arguments, with the operation |
 | `firstRecordAt` / `lastRecordAt` | the earliest span start and latest span end among this session's own records — a subagent that outlives the session does not stretch its window |
@@ -631,7 +646,8 @@ Three rules hold for every field:
 - **Every fact names its span ids.** `spanIds` lists the spans the value was computed from, so any number here can be opened and checked. The sheet itself is not a span and cannot be cited.
 - **A fact the spans cannot support is `null` with its reason.** It is never guessed, and never a silent zero. `partial` marks a measured value that is known to be incomplete — a truncated patch, or a list above the entry cap.
 
-`facts` exits non-zero when a selected session cannot be read at all: a session that produced no record spans would otherwise print a sheet of zeros stating, in the sheet's own voice, that the session did nothing.
+Without a window, `facts` exits non-zero when a selected session cannot be read at all: a session that produced no record spans would otherwise print a sheet of zeros stating, in the sheet's own voice, that the session did nothing.
+With a window, a session that cannot be read — the parser failed, or no record could be read — is named in `selection.unreadSessions` with its reason and a warning on stderr, and the run still exits 0 with the sessions it could read; it is never counted as a session with no turns.
 
 The same sheet reaches the model-backed analysts as prepared context, before their first model call — see [Trace analysts](docs/trace-analysts.md#session-facts-as-prepared-context).
 

package/dist/{chunk-DON6NQ7H.js → chunk-COSWFESO.js}

@@ -151,6 +151,7 @@ var ATTR = {
    *  in-container path even when no such path exists on this host. */
   ENVIRONMENT_CWD: "tangle.environment.cwd"
 };
+var SESSION_CWD_ATTR = "traces.session.cwd";
 var INGEST_SOURCE_CLI = "cli";
 function environmentAttributes(environment) {
   if (!environment) return {};
@@ -254,6 +255,9 @@ function parseIsoToEpochMs(ts) {
   return n;
 }
 function parseSince(value) {
+  return parseTimeBound(value, "--since");
+}
+function parseTimeBound(value, flag) {
   const m = value.match(/^(\d+)\s*([mhd])$/i);
   if (m) {
     const unit = m[2].toLowerCase();
@@ -261,7 +265,7 @@ function parseSince(value) {
     return Date.now() - Number(m[1]) * ms2;
   }
   const t = Date.parse(value);
-  if (Number.isNaN(t)) throw new Error(`--since: expected 30m / 2h / 7d or an ISO date, got "${value}"`);
+  if (Number.isNaN(t)) throw new Error(`${flag}: expected 30m / 2h / 7d or an ISO date, got "${value}"`);
   return t;
 }
 
@@ -2585,6 +2589,7 @@ var GeminiAdapter = class extends GeminiFamilyAdapter {
 };
 
 // src/adapters/actor.ts
+import { claudeRecordIsMachine } from "@tangle-network/harness-sessions";
 var CMD_MARKERS = [
   "<command-name>",
   "<local-command-caveat>",
@@ -2633,22 +2638,6 @@ var SYNTHETIC_MARKERS = [
   "Staff-engineer code review"
 ];
 var AGENT_PROMPT = /^(you are\b|you're\b|read[- ]only\b|stop now\b|your task\b|your job\b|review the\b|audit\b|analyze the\b|return (only|a |the )|here is the\b|context:|task:|do not (revert|edit|touch)|work only in\b|you have been\b|act as\b|operate the\b|goal:|objective:)/i;
-var CLAUDE_MACHINE_PREFIXES = [
-  "<local-command-caveat>",
-  "<local-command-stdout>",
-  "<local-command-stderr>",
-  "Caveat: The messages below",
-  "<task-notification>",
-  "<bash-stdout>",
-  "<bash-stderr>",
-  "<user-prompt-submit-hook>",
-  "[Request interrupted by user"
-];
-function claudeRecordIsMachine(args) {
-  if (args.isMeta === true || args.isCompactSummary === true || args.entrypoint === "sdk-cli") return true;
-  const text2 = args.text.trimStart();
-  return CLAUDE_MACHINE_PREFIXES.some((prefix) => text2.startsWith(prefix));
-}
 function textIsCmdOrInject(s) {
   return CMD_MARKERS.some((m) => s.includes(m)) || INJECT_MARKERS.some((m) => s.includes(m));
 }
@@ -2686,7 +2675,7 @@ function claudePromptStartsTask(args) {
 }
 function claudeActor(args) {
   if (args.isSidechain === true) return "subagent-spawn";
-  if (claudeRecordIsMachine(args)) return "injected";
+  if (claudeRecordIsMachine({ ...args, entrypoint: args.entrypoint ?? void 0 })) return "injected";
   if (args.userType != null && args.userType !== "external") return "injected";
   if (textIsCmdOrInject(args.text)) return "injected";
   if (textIsSynthetic(args.text)) return "injected";
@@ -2770,6 +2759,7 @@ import {
   LLM_OUTPUT_TOKENS as LLM_OUTPUT_TOKENS2
 } from "@tangle-network/agent-eval/trace-attributes";
 import { ATTR as ATTR3, deriveHexId as deriveHexId2 } from "@tangle-network/agent-trace-contract";
+import { claudeRecordIsMachine as claudeRecordIsMachine2, claudeTypedPromptText } from "@tangle-network/harness-sessions";
 
 // src/adapters/claude-subagent-sources.ts
 import { readdir as readdir6, realpath } from "fs/promises";
@@ -3125,8 +3115,6 @@ var ORIGIN_EVIDENCE_ATTR = "traces.claude.actor_evidence";
 var MACHINE_RECORD_ATTR = "traces.claude.machine_record";
 var ORIGIN_RECORDED_ATTR = "traces.claude.origin_recorded";
 var ORIGIN_KIND_ATTR = "traces.claude.origin_kind";
-var COMMAND_NAME = /<command-name>([\s\S]*?)<\/command-name>/;
-var COMMAND_ARGS = /<command-args>([\s\S]*?)<\/command-args>/;
 var SPAWN_TYPE_KEY = "subagent_type";
 var SPAWN_DESCRIPTION_KEY = "description";
 var SPAWN_TYPE_ATTR = "traces.claude.subagent_type";
@@ -3322,12 +3310,6 @@ function claudeActorFromOrigin(recorded, fallback) {
   }
   return fallback();
 }
-function typedPromptText(text2) {
-  const name = COMMAND_NAME.exec(text2)?.[1]?.trim();
-  if (!name) return text2;
-  const args = COMMAND_ARGS.exec(text2)?.[1]?.trim();
-  return args ? `${name} ${args}` : name;
-}
 function recordedOrigin(origin) {
   const kind = origin?.kind;
   return typeof kind === "string" && kind.length > 0 ? kind : null;
@@ -3533,11 +3515,11 @@ function consumeClaudeEvent(event, uid, ctx, state) {
     }
   } else if (event.kind === "user") {
     if (event.prompt) {
-      const machine = claudeRecordIsMachine({
+      const machine = claudeRecordIsMachine2({
         text: event.prompt,
         isMeta: event.isMeta,
         isCompactSummary: event.isCompactSummary,
-        entrypoint: event.entrypoint
+        entrypoint: event.entrypoint ?? void 0
       });
       const actor = machine ? "injected" : claudeActorFromOrigin(event.originKind, () => claudeActor({
         text: event.prompt ?? "",
@@ -3556,7 +3538,7 @@ function consumeClaudeEvent(event, uid, ctx, state) {
         service: SERVICE4,
         agent: ctx.agent,
         step: state.step,
-        content: actor === "human" ? typedPromptText(event.prompt) : event.prompt,
+        content: actor === "human" ? claudeTypedPromptText(event.prompt) : event.prompt,
         contentSource: event.contentSource,
         actor
       });
@@ -3577,7 +3559,7 @@ function consumeClaudeEvent(event, uid, ctx, state) {
   } else if (event.kind === "attachment") {
     backfillResult(state.toolSpanByUseId.get(event.result.toolUseId), event.timestamp, event.result);
   } else if (event.kind === "queued-prompt") {
-    const machine = claudeRecordIsMachine({ text: event.prompt });
+    const machine = claudeRecordIsMachine2({ text: event.prompt });
     const actor = machine ? "injected" : claudeActorFromOrigin(event.originKind, () => "injected");
     if (event.originKind) state.sawRecordedOrigin = true;
     const prompt = userPromptSpan({
@@ -3588,7 +3570,7 @@ function consumeClaudeEvent(event, uid, ctx, state) {
       service: SERVICE4,
       agent: ctx.agent,
       step: state.step,
-      content: actor === "human" ? typedPromptText(event.prompt) : event.prompt,
+      content: actor === "human" ? claudeTypedPromptText(event.prompt) : event.prompt,
       contentSource: event.contentSource,
       actor
     });
@@ -3900,10 +3882,12 @@ var ClaudeAdapter = class {
     let active = taskScope === "all";
     let offeredTools;
     let runResult;
+    let recordedCwd;
     for await (const event of readJsonl(ref.path, sessionJsonlOptions(ref, options))) {
       options.signal?.throwIfAborted();
       const eventSessionId = event.sessionId ?? event.session_id;
       if (!discoveredTraceId && eventSessionId) discoveredTraceId = eventSessionId;
+      if (!recordedCwd && typeof event.cwd === "string" && event.cwd.length > 0) recordedCwd = event.cwd;
       if (event.type === "system" && event.subtype === "init" && Array.isArray(event.tools)) {
         offeredTools = modelFacingToolNames(
           event.tools.filter((t) => typeof t === "string"),
@@ -3973,6 +3957,7 @@ var ClaudeAdapter = class {
     if (offeredTools) {
       root.attributes[TOOL_DEFINITIONS_ATTR] = JSON.stringify(offeredTools.map((name) => ({ type: "function", name })));
     }
+    if (recordedCwd) root.attributes[SESSION_CWD_ATTR] = recordedCwd;
     if (runResult) {
       root.attributes[RUN_STATUS_ATTR] = runResult.failed ? "failed" : "completed";
       root.status = runResult.failed ? { code: "ERROR", message: `the run ended with ${runResult.subtype}` } : { code: "OK" };
@@ -4626,6 +4611,9 @@ var CODEX_TOTAL_TOKENS_SOURCE = "codex.token_count.info.total_token_usage";
 function reportedCount(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
 }
+function nonEmpty(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
 function normalizeCodexIds(spans) {
   for (const item of spans) {
     const sourceTraceId = item.trace_id;
@@ -5203,6 +5191,7 @@ var CodexAdapter = class {
       }
     }
     const traceId = meta?.payload?.id ?? ref.sessionId;
+    const recordedCwd = nonEmpty(meta?.payload?.cwd);
     const scriptLaunched = meta?.payload?.originator === "codex_exec" || meta?.payload?.source === "exec";
     const sessionRole = parentSessionId || meta?.payload?.thread_source === "subagent" ? "child" : "operator";
     const rootId = `root:${traceId}`;
@@ -5221,6 +5210,7 @@ var CodexAdapter = class {
         // Keep the source session identity searchable after the wire id is normalized.
         "tangle.sessionId": traceId,
         "traces.session.role": sessionRole,
+        ...recordedCwd ? { [SESSION_CWD_ATTR]: recordedCwd } : {},
         "traces.codex.task_scope": options.taskScope === "latest" ? "latest" : options.taskScope === "turn" ? "turn" : forkBoundary ? "fork-current" : "all",
         ...selectedBoundary?.turnId ? { "traces.codex.turn_id": selectedBoundary.turnId } : {},
         ...parentSessionId ? { "traces.parent_session_id": parentSessionId } : {},
@@ -5865,6 +5855,7 @@ var OpencodeAdapter = class {
       messages.push(await readJsonFile(join9(ref.path, f), options));
     }
     messages.sort((a, b) => (a.time?.created ?? 0) - (b.time?.created ?? 0));
+    const recordedCwd = messages.map((message) => message.path?.cwd).find((cwd) => typeof cwd === "string" && cwd.length > 0);
     const spans = [
       span({
         traceId,
@@ -5875,7 +5866,8 @@ var OpencodeAdapter = class {
         startTime: isoOf(messages[0]?.time?.created),
         endTime: isoOf(messages.at(-1)?.time?.completed ?? messages.at(-1)?.time?.created),
         service: SERVICE6,
-        agent: SERVICE6
+        agent: SERVICE6,
+        ...recordedCwd ? { extra: { [SESSION_CWD_ATTR]: recordedCwd } } : {}
       })
     ];
     let step = 0;
@@ -6317,6 +6309,7 @@ var HarnessSessionsAdapter = class {
     const root = spans[0];
     root.attributes["service.name"] = this.harness;
     root.attributes["traces.session.role"] = session.parentNativeSessionId ? "child" : "operator";
+    if (session.cwd) root.attributes[SESSION_CWD_ATTR] = session.cwd;
     if (session.parentNativeSessionId) root.attributes["traces.parent_session_id"] = session.parentNativeSessionId;
     if (session.children.length > 0) {
       root.attributes["traces.child_session_ids"] = JSON.stringify(session.children.map((child) => child.nativeSessionId));
@@ -8811,12 +8804,13 @@ function computeSessionMeasurements(spans, tools, sessionId, harness) {
 // src/session-facts.ts
 import { OPENINFERENCE_SPAN_KIND as OPENINFERENCE_SPAN_KIND4, TOOL_NAME as TOOL_NAME5 } from "@tangle-network/agent-eval/trace-attributes";
 import { ingestSpans, rankFirstFailure } from "@tangle-network/agent-eval/diagnosis";
-var SESSION_FACTS_MEASUREMENT_VERSION = "3";
+var SESSION_FACTS_MEASUREMENT_VERSION = "4";
 var SESSION_TOKEN_TOTAL_ATTR = "traces.session.total_tokens";
 var SPAN_SYNTHESIZED_ATTR = "traces.codex.span_synthesized";
 var CORRUPTION_COUNT_ATTR = "traces.session.corruption_count";
 var CORRUPTION_RECEIPT_VERSION_ATTR = "traces.session.corruption.receipt_version";
 var FACT_TEXT_CAP = 2e3;
+var ANSWERED_TEXT_CAP = 1500;
 var FACT_LIST_CAP = 200;
 var CHANGED_FILE_LIST_CAP = 5e3;
 function attr(span2, key) {
@@ -9046,47 +9040,105 @@ function turnText(span2) {
 function normalizedTurnText(span2) {
   return turnText(span2).replace(/\s+/g, " ").trim();
 }
+var CAPTURE_CUT_MARKER = /… \[\+(\d+) chars\]$/;
+function clipAnswered(raw) {
+  const text2 = raw.trim();
+  const marker = CAPTURE_CUT_MARKER.exec(text2);
+  const body = marker ? text2.slice(0, marker.index) : text2;
+  if (body.length <= ANSWERED_TEXT_CAP) return text2;
+  const lastKept = body.charCodeAt(ANSWERED_TEXT_CAP - 1);
+  const keep = lastKept >= 55296 && lastKept <= 56319 ? ANSWERED_TEXT_CAP - 1 : ANSWERED_TEXT_CAP;
+  const hidden = body.length - keep + (marker ? Number(marker[1]) : 0);
+  return `${body.slice(0, keep)}\u2026 [+${hidden} chars]`;
+}
+function isOwnAgentMessage(span2) {
+  return span2.name === "message.assistant" && span2.attributes[INHERITED_SPAN_ATTR] !== true && typeof span2.attributes.content === "string" && span2.attributes.content.trim().length > 0;
+}
 function humanTurnsOf(spans) {
   const excluded = /* @__PURE__ */ new Map();
-  const drop = (reason, spanId) => {
-    excluded.set(reason, [...excluded.get(reason) ?? [], spanId]);
+  const drop = (reason, span2) => {
+    excluded.set(reason, [...excluded.get(reason) ?? [], { spanId: span2.span_id, at: span2.start_time }]);
   };
   const kept = [];
+  const turns = [];
   let sinceKept = [];
+  let lastAgentMessage = null;
   for (const span2 of spans) {
     if (isSubagentSpan(span2.attributes)) {
-      if (span2.name === "user.prompt") drop(SUBAGENT_TURN_REASON, span2.span_id);
+      if (span2.name === "user.prompt") drop(SUBAGENT_TURN_REASON, span2);
       continue;
     }
     if (span2.name !== "user.prompt") {
+      if (isOwnAgentMessage(span2)) lastAgentMessage = span2;
       sinceKept.push(span2);
       continue;
     }
     if (span2.attributes[INHERITED_SPAN_ATTR] === true) {
       const source = stringAttr2(span2, INHERITED_SOURCE_ATTR);
-      drop(source === null ? INHERITED_TURN_REASON : `${INHERITED_TURN_REASON} (${source})`, span2.span_id);
+      drop(source === null ? INHERITED_TURN_REASON : `${INHERITED_TURN_REASON} (${source})`, span2);
       continue;
     }
     const actor = stringAttr2(span2, ACTOR_ATTR) ?? "unclassified";
     if (actor !== "human") {
-      drop(TURN_EXCLUSION_REASONS[actor] ?? `the adapter classified this turn as "${actor}", not as a person typing`, span2.span_id);
+      drop(TURN_EXCLUSION_REASONS[actor] ?? `the adapter classified this turn as "${actor}", not as a person typing`, span2);
       continue;
     }
     const previous = kept[kept.length - 1];
     const duplicate = previous !== void 0 && previous.start_time === span2.start_time && normalizedTurnText(previous) === normalizedTurnText(span2) && normalizedTurnText(span2).length > 0 && !sinceKept.some(isAgentActivity);
     if (duplicate) {
-      drop(DUPLICATE_TURN_REASON, span2.span_id);
+      drop(DUPLICATE_TURN_REASON, span2);
       continue;
     }
     kept.push(span2);
+    turns.push({
+      actor: "human",
+      at: span2.start_time,
+      text: turnText(span2),
+      spanId: span2.span_id,
+      answered: lastAgentMessage ? clipAnswered(lastAgentMessage.attributes.content) : null,
+      answeredSpanId: lastAgentMessage?.span_id ?? null
+    });
     sinceKept = [];
   }
+  return { turns, excluded };
+}
+function excludedTurnFacts(excluded, keep) {
+  return [...excluded].map(([reason, entries]) => [reason, entries.filter((entry) => keep(entry.at)).map((entry) => entry.spanId)]).filter(([, spanIds]) => spanIds.length > 0).sort(([left], [right]) => left.localeCompare(right)).map(([reason, spanIds]) => ({ reason, turns: spanIds.length, spanIds }));
+}
+function windowBounds(window) {
+  if (!window || window.since === void 0 && window.until === void 0) return null;
+  const bound = (value, name, open4) => {
+    if (value === void 0) return open4;
+    const ms2 = Date.parse(value);
+    if (!Number.isFinite(ms2)) throw new RangeError(`window ${name} is not a readable time: ${value}`);
+    return ms2;
+  };
+  const sinceMs = bound(window.since, "since", Number.NEGATIVE_INFINITY);
+  const untilMs = bound(window.until, "until", Number.POSITIVE_INFINITY);
+  if (!(sinceMs < untilMs)) throw new RangeError(`window since (${window.since}) must be before until (${window.until})`);
   return {
-    turns: kept.map((span2) => ({ actor: "human", at: span2.start_time, text: turnText(span2), spanId: span2.span_id })),
-    excluded: [...excluded].sort(([left], [right]) => left.localeCompare(right)).map(([reason, spanIds]) => ({ reason, turns: spanIds.length, spanIds }))
+    since: window.since === void 0 ? null : new Date(sinceMs).toISOString(),
+    until: window.until === void 0 ? null : new Date(untilMs).toISOString(),
+    sinceMs,
+    untilMs
   };
 }
+function insideWindow(bounds, time) {
+  if (bounds === null) return true;
+  const ms2 = Date.parse(time);
+  return Number.isFinite(ms2) && ms2 >= bounds.sinceMs && ms2 < bounds.untilMs;
+}
+function isRecordSpan(span2) {
+  return span2.parent_span_id !== null && span2.attributes[CORRUPTION_RECEIPT_VERSION_ATTR] === void 0;
+}
 function computeSessionFacts(spans, options = {}) {
+  const bounds = windowBounds(options.window);
+  return groupByTrace(spans).sort((left, right) => compareIds(left.traceId, right.traceId)).map((group) => sessionFactsForTrace(group.traceId, group.sessionId, group.spans, options, bounds));
+}
+function compareIds(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function groupByTrace(spans) {
   const { sessionByTrace } = indexSessionIdsByTrace(spans);
   const byTrace = /* @__PURE__ */ new Map();
   for (const span2 of spans) {
@@ -9094,9 +9146,13 @@ function computeSessionFacts(spans, options = {}) {
     if (group) group.push(span2);
     else byTrace.set(span2.trace_id, [span2]);
   }
-  return [...byTrace].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([traceId, traceSpans]) => sessionFactsForTrace(traceId, sessionByTrace.get(traceId) ?? null, traceSpans, options));
+  return [...byTrace].map(([traceId, traceSpans]) => ({
+    traceId,
+    sessionId: sessionByTrace.get(traceId) ?? null,
+    spans: traceSpans
+  }));
 }
-function sessionFactsForTrace(traceId, sessionId, unordered, options) {
+function sessionFactsForTrace(traceId, sessionId, unordered, options, bounds) {
   const spans = [...unordered].sort(byTraceOrder);
   const harness = spans.map((span2) => stringAttr2(span2, "service.name")).find((name) => name !== null) ?? null;
   const ownSpans = spans.filter((span2) => !isSubagentSpan(span2.attributes));
@@ -9110,8 +9166,11 @@ function sessionFactsForTrace(traceId, sessionId, unordered, options) {
   for (const span2 of invoked) byName[toolName3(span2)] = (byName[toolName3(span2)] ?? 0) + 1;
   const subagents = subagentsOf(ownSpans, spans);
   const pullRequests = readPullRequests(ownSpans);
-  const promptSpans = spans.filter((span2) => span2.name === "user.prompt");
-  const { turns: humanTurns, excluded: excludedTurns } = humanTurnsOf(spans);
+  const inWindow = (at) => insideWindow(bounds, at);
+  const promptSpans = spans.filter((span2) => span2.name === "user.prompt" && inWindow(span2.start_time));
+  const turnFacts = humanTurnsOf(spans);
+  const humanTurns = turnFacts.turns.filter((turn) => inWindow(turn.at));
+  const excludedTurns = excludedTurnFacts(turnFacts.excluded, inWindow);
   const actorCounts = /* @__PURE__ */ new Map();
   for (const span2 of promptSpans) {
     const actor = stringAttr2(span2, ACTOR_ATTR) ?? "unclassified";
@@ -9131,16 +9190,20 @@ function sessionFactsForTrace(traceId, sessionId, unordered, options) {
   );
   const tokenSpan = spans.find((span2) => typeof span2.attributes[SESSION_TOKEN_TOTAL_ATTR] === "number");
   const receipts = spans.filter((span2) => span2.attributes[CORRUPTION_RECEIPT_VERSION_ATTR] !== void 0);
-  const recordSpans = spans.filter(
-    (span2) => span2.parent_span_id !== null && span2.attributes[CORRUPTION_RECEIPT_VERSION_ATTR] === void 0
-  ).length;
+  const recordSpans = spans.filter(isRecordSpan).length;
   const corruptionSpan = spans.find((span2) => typeof span2.attributes[CORRUPTION_COUNT_ATTR] === "number");
+  const cwdSpan = spans.find((span2) => stringAttr2(span2, SESSION_CWD_ATTR) !== null);
   const facts = {
     schemaVersion: 1,
     kind: "traces.session_facts",
     traceId,
     sessionId,
     harness,
+    cwd: cwdSpan ? { value: stringAttr2(cwdSpan, SESSION_CWD_ATTR), spanIds: [cwdSpan.span_id], unavailable: null } : {
+      value: null,
+      spanIds: [],
+      unavailable: `no span carries ${SESSION_CWD_ATTR}: the session source records no working directory, or the adapter that read it does not read one`
+    },
     spanCount: spans.length,
     recordSpans,
     unreadRecords: corruptionSpan ? {
@@ -9213,6 +9276,7 @@ function sessionFactsForTrace(traceId, sessionId, unordered, options) {
   });
   return {
     ...facts,
+    cwd: withheld(),
     humanTurns: withheld(),
     finalMessages: withheld(),
     changedFiles: withheld(),
@@ -9229,26 +9293,88 @@ function sessionFactsForTrace(traceId, sessionId, unordered, options) {
   };
 }
 function buildSessionFactsReport(spans, options = {}) {
-  const digest = createHash7("sha256");
-  const ordered2 = [...spans].sort((a, b) => a.trace_id.localeCompare(b.trace_id) || a.span_id.localeCompare(b.span_id));
+  const builder = createSessionFactsReportBuilder(options);
+  builder.add(spans);
+  return builder.build();
+}
+var WINDOW_SESSION_RULE = "a session is selected when at least one of its records starts or ends inside [since, until)";
+var WINDOW_TURN_RULE = "humanTurns, excludedTurns and turnsByActor keep only user.prompt turns that started inside [since, until); every other fact, and each turn's answered text, covers the whole session";
+function createSessionFactsReportBuilder(options = {}) {
+  const bounds = windowBounds(options.window);
+  const sessions = [];
+  const digests = [];
+  const outsideWindow = [];
+  const unreadSessions = [];
+  let spanCount = 0;
   let evidenceThrough = null;
-  for (const span2 of ordered2) {
-    digest.update(canonicalJson(span2)).update("\n");
-    for (const time of [span2.start_time, span2.end_time]) {
-      if (Number.isFinite(Date.parse(time)) && (evidenceThrough === null || Date.parse(time) > Date.parse(evidenceThrough))) evidenceThrough = time;
+  const select = (group) => {
+    const digest = createHash7("sha256");
+    for (const span2 of [...group.spans].sort((a, b) => a.span_id.localeCompare(b.span_id))) {
+      digest.update(canonicalJson(span2)).update("\n");
+      for (const time of [span2.start_time, span2.end_time]) {
+        if (Number.isFinite(Date.parse(time)) && (evidenceThrough === null || Date.parse(time) > Date.parse(evidenceThrough))) evidenceThrough = time;
+      }
     }
-  }
+    digests.push({ traceId: group.traceId, digest: digest.digest("hex") });
+    spanCount += group.spans.length;
+    sessions.push(sessionFactsForTrace(group.traceId, group.sessionId, group.spans, options, bounds));
+  };
   return {
-    schemaVersion: 1,
-    kind: "traces.session_facts_report",
-    measurementVersion: SESSION_FACTS_MEASUREMENT_VERSION,
-    sourceDigest: "sha256:" + digest.digest("hex"),
-    evidenceThrough,
-    contentIncluded: options.includeContent !== false,
-    generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-    harness: options.harness ?? null,
-    spanCount: spans.length,
-    sessions: computeSessionFacts(spans, options)
+    add(spans) {
+      for (const group of groupByTrace(spans)) {
+        if (bounds === null) {
+          select(group);
+          continue;
+        }
+        const records = group.spans.filter(isRecordSpan);
+        if (records.length === 0) {
+          const unread = group.spans.find((span2) => typeof span2.attributes[CORRUPTION_COUNT_ATTR] === "number");
+          unreadSessions.push({
+            sessionId: group.sessionId,
+            traceId: group.traceId,
+            source: null,
+            reason: `no record could be read (${unread ? `${unread.attributes[CORRUPTION_COUNT_ATTR]} unread record(s)` : "no record spans"}), so whether the session holds a record inside the window is unknown`
+          });
+          continue;
+        }
+        if (records.some((span2) => insideWindow(bounds, span2.start_time) || insideWindow(bounds, span2.end_time))) select(group);
+        else outsideWindow.push(group.sessionId ?? group.traceId);
+      }
+    },
+    addUnread(session) {
+      if (bounds === null) {
+        throw new Error("an unread session is reported only by a windowed report; without a window, refuse the selection");
+      }
+      unreadSessions.push(session);
+    },
+    build() {
+      const digest = createHash7("sha256");
+      for (const entry of [...digests].sort((a, b) => a.traceId.localeCompare(b.traceId) || a.digest.localeCompare(b.digest))) {
+        digest.update(`${entry.traceId}
+${entry.digest}
+`);
+      }
+      return {
+        schemaVersion: 1,
+        kind: "traces.session_facts_report",
+        measurementVersion: SESSION_FACTS_MEASUREMENT_VERSION,
+        sourceDigest: "sha256:" + digest.digest("hex"),
+        evidenceThrough,
+        contentIncluded: options.includeContent !== false,
+        generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+        harness: options.harness ?? null,
+        spanCount,
+        selection: bounds === null ? null : {
+          since: bounds.since,
+          until: bounds.until,
+          sessionRule: WINDOW_SESSION_RULE,
+          turnRule: WINDOW_TURN_RULE,
+          outsideWindow: [...outsideWindow].sort(compareIds),
+          unreadSessions: [...unreadSessions]
+        },
+        sessions: [...sessions].sort((left, right) => compareIds(left.traceId, right.traceId))
+      };
+    }
   };
 }
 function factLine(label2, fact, rendered) {
@@ -9260,8 +9386,18 @@ function renderSessionFacts(report) {
   const lines = [
     `session facts \u2014 ${report.sessions.length} session(s), ${report.spanCount} span(s), deterministic, $0`
   ];
+  const selection = report.selection;
+  if (selection) {
+    lines.push(
+      `window [${selection.since ?? "open"}, ${selection.until ?? "open"}): turn facts count only turns inside it; ${selection.outsideWindow.length} session(s) read with no record inside it`
+    );
+    for (const unread of selection.unreadSessions) {
+      lines.push(`  unread session ${unread.sessionId ?? unread.traceId ?? unread.source ?? "unknown"}: ${unread.reason}`);
+    }
+  }
   for (const facts of report.sessions) {
     lines.push("", `${facts.sessionId ?? facts.traceId} [${facts.harness ?? "unknown harness"}] ${facts.spanCount} spans`);
+    lines.push(factLine("cwd", facts.cwd, String(facts.cwd.value)));
     lines.push(
       factLine(
         "tool calls",
@@ -9329,6 +9465,9 @@ function renderSessionFactsContext(report, options = {}) {
 ${JSON.stringify({ sessions, ...dropped2.length ? { omitted_fields: dropped2 } : {} })}`;
   const dropped = [];
   const sheds = [
+    ["human_turn_answered", (facts) => {
+      for (const turn of facts.human_turns) delete turn.answered;
+    }],
     ["human_turn_text", (facts) => {
       for (const turn of facts.human_turns) delete turn.text;
     }],
@@ -9419,6 +9558,7 @@ function compactFacts(facts) {
   return {
     session_id: facts.sessionId,
     trace_id: facts.traceId,
+    cwd: factJson(facts.cwd),
     spans: facts.spanCount,
     tool_calls: {
       count: facts.toolCalls.value,
@@ -9441,7 +9581,8 @@ function compactFacts(facts) {
     human_turns: (facts.humanTurns.value ?? []).map((turn) => ({
       at: turn.at,
       span_id: turn.spanId,
-      text: turn.text
+      text: turn.text,
+      answered: turn.answered
     })),
     excluded_turns: facts.excludedTurns.value?.map((entry) => ({
       reason: entry.reason,
@@ -20550,6 +20691,7 @@ export {
   isSynthesizedSpan,
   isInheritedSpan,
   ATTR,
+  SESSION_CWD_ATTR,
   INGEST_SOURCE_CLI,
   environmentAttributes,
   stampEnvironmentAttrs,
@@ -20561,6 +20703,7 @@ export {
   appendAll,
   parseIsoToEpochMs,
   parseSince,
+  parseTimeBound,
   resolveOtlpInputFiles,
   inferSpanKind,
   otlpRowToSpan,
@@ -20649,10 +20792,12 @@ export {
   SESSION_TOKEN_TOTAL_ATTR,
   SPAN_SYNTHESIZED_ATTR,
   FACT_TEXT_CAP,
+  ANSWERED_TEXT_CAP,
   FACT_LIST_CAP,
   CHANGED_FILE_LIST_CAP,
   computeSessionFacts,
   buildSessionFactsReport,
+  createSessionFactsReportBuilder,
   renderSessionFacts,
   PREPARED_CONTEXT_BYTE_CEILING,
   renderSessionFactsContext,

package/dist/cli.js

@@ -13,7 +13,6 @@ import {
   assertOutsideSourceBundle,
   assessSpans,
   buildPolicyEvidenceRecord,
-  buildSessionFactsReport,
   buildSessionIndexFromRows,
   buildSkillUsageReport,
   cmdReplayVerify,
@@ -22,6 +21,7 @@ import {
   collectSessionSelection,
   commandAnalyzer,
   commandRedactor,
+  createSessionFactsReportBuilder,
   defaultSkillUsageStorePath,
   diffRuns,
   executeUpload,
@@ -47,6 +47,7 @@ import {
   parseIsoToEpochMs,
   parseSession,
   parseSince,
+  parseTimeBound,
   planUpload,
   primeAnalyzer,
   projectSessionBundle,
@@ -66,6 +67,7 @@ import {
   runTraceInvestigation,
   runTraceQuestions,
   saveReport,
+  scanSessions,
   selectAdapters,
   serializePolicyEvidence,
   serializeSessionIndex,
@@ -90,7 +92,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-DON6NQ7H.js";
+} from "./chunk-COSWFESO.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
@@ -489,6 +491,9 @@ function parseArgs(argv) {
       case "--since":
         a.since = next();
         break;
+      case "--until":
+        a.until = next();
+        break;
       case "--out":
         a.out = next();
         break;
@@ -703,6 +708,10 @@ function validateViewSelection(args) {
     `--view is not supported by ${args.command}. A view is a projection of an assembled bundle: run \`traces bundle ... --out <dir>\` first, then \`traces bundle-view <dir> --view evidence-only --out <view-dir>\`.`
   );
 }
+function validateUntilSelection(args) {
+  if (args.until === void 0 || args.command === "facts") return args;
+  throw new Error(`--until is not supported by ${args.command}; it bounds the facts window (traces facts --since <t> --until <t>)`);
+}
 function validateWorkflowSelection(args) {
   if (!args.workflow && !args.latestTurn) return args;
   if (!WORKFLOW_COMMANDS.has(args.command)) {
@@ -736,7 +745,7 @@ function adaptersFor(args) {
   return selectAdapters({ all: args.all, harnesses: [args.harness] });
 }
 async function discover(args) {
-  const sinceMs = args.since ? Date.parse(args.since) : void 0;
+  const sinceMs = args.since ? parseSince(args.since) : void 0;
   const out = [];
   for (const adapter of adaptersFor(args)) {
     let refs = await locateSessions(adapter, { cwd: args.cwd, sinceMs });
@@ -1201,10 +1210,50 @@ async function cmdFacts(args) {
   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, includeContent: !args.noContent });
+  const window = args.since !== void 0 || args.until !== void 0 ? {
+    ...args.since !== void 0 ? { since: new Date(parseSince(args.since)).toISOString() } : {},
+    ...args.until !== void 0 ? { until: new Date(parseTimeBound(args.until, "--until")).toISOString() } : {}
+  } : void 0;
+  const builder = createSessionFactsReportBuilder({ includeContent: !args.noContent, window });
+  let report;
+  const discoversWindow = window !== void 0 && !args.session && !args.otlp && !args.input && !args.sourceBundle && !args.workflow;
+  if (discoversWindow) {
+    const harnesses = /* @__PURE__ */ new Set();
+    for await (const scanned of scanSessions({
+      adapters: adaptersFor(args),
+      cwd: args.cwd,
+      sinceMs: window.since === void 0 ? void 0 : Date.parse(window.since),
+      last: args.last > 0 ? args.last : void 0,
+      taskScope: args.latestTurn ? "latest" : "all",
+      onError: (error, ref) => {
+        if (!ref) throw error;
+        builder.addUnread({
+          sessionId: ref.sessionId,
+          traceId: null,
+          source: ref.path,
+          reason: error instanceof Error ? error.message : String(error)
+        });
+      }
+    })) {
+      harnesses.add(scanned.adapter.harness);
+      builder.add(scanned.spans);
+    }
+    report = { ...builder.build(), harness: [...harnesses].join("+") || args.harness };
+  } else {
+    const collected = await collectSpans(args);
+    if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
+    warnIncompleteWorkflow(collected.workflow);
+    builder.add(collected.spans);
+    report = { ...builder.build(), harness: collected.harness };
+  }
+  const unreadInWindow = report.selection?.unreadSessions ?? [];
+  if (unreadInWindow.length > 0) {
+    const named = unreadInWindow.slice(0, 3).map((entry) => entry.source ?? entry.sessionId ?? entry.traceId);
+    process.stderr.write(
+      `warning: ${unreadInWindow.length} session(s) could not be read; each is named with its reason in selection.unreadSessions (${named.join(", ")}${unreadInWindow.length > named.length ? ", \u2026" : ""})
+`
+    );
+  }
   const unread = report.sessions.filter((facts) => facts.recordSpans === 0);
   if (unread.length > 0) {
     throw new Error(
@@ -2050,10 +2099,15 @@ Commands:
             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, the harness token total, and
-            the first failure by agent-eval's fixed precedence (or none).
+            the first failure by agent-eval's fixed precedence (or none), the
+            session's recorded working directory, and for each human turn the
+            agent message it answered.
             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)
+            --since/--until select every session with a record in the window and
+            count only that window's turns; a session that cannot be read is named
+            in selection.unreadSessions. Without a window: exit 1 when a selected
+            session cannot be read. --format json (default) or text
   skills    Count skill use across Claude Code, Codex, and Kimi Code sessions on this
             machine, and list installed skills with no use in the window.
             Incremental: a run reads only transcript bytes appended since the
@@ -2129,7 +2183,11 @@ Options:
                    accepted vs rejected. Rolls up when the dir holds many runs.
                    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
+  --since <t>      30m / 2h / 7d (before now) or an ISO date. Selection commands read
+                   sessions modified at or after it; upload: its window (default 24h).
+                   facts: opens a time window and selects EVERY session with a record
+                   in it, not only the newest; its turn facts keep only turns inside it
+  --until <t>      facts: closes the window (exclusive), same forms as --since
   --out <path>     Write report to a file
   --dir <path>     improve/ask: write artifacts to this directory
   --otlp <file|dir>  READ OTLP-JSONL emitted by any system, skipping the adapters.
@@ -2261,7 +2319,7 @@ async function main() {
     return;
   }
   const args = validateOtlpSelection(
-    validateViewSelection(validateWorkflowSelection(applyCurrentSessionSelection(parsedArgs)))
+    validateViewSelection(validateWorkflowSelection(validateUntilSelection(applyCurrentSessionSelection(parsedArgs))))
   );
   switch (args.command) {
     case "help":

package/dist/index.d.ts

@@ -900,6 +900,14 @@ declare const ATTR: {
      *  in-container path even when no such path exists on this host. */
     readonly ENVIRONMENT_CWD: "tangle.environment.cwd";
 };
+/**
+ * The working directory the harness recorded for a session, verbatim, on the
+ * adapter's root `session` span. Unlike `tangle.cwd` it is never repaired,
+ * decoded from a directory name, or inferred from paths the spans mention: an
+ * adapter sets it only from a field the session source itself carries, and
+ * leaves it absent when the source names none.
+ */
+declare const SESSION_CWD_ATTR = "traces.session.cwd";
 /** `tangle.ingest_source` value for CLI-uploaded traces. Wire contract. */
 declare const INGEST_SOURCE_CLI = "cli";
 /**
@@ -957,6 +965,9 @@ declare function parseIsoToEpochMs(ts: string): number;
 /** Parse a `--since` window: `30m` / `2h` / `7d` (relative to now) or an ISO
  *  date, → epoch ms. Throws on a malformed value (fail-loud, not silent). */
 declare function parseSince(value: string): number;
+/** Parse one time bound the way `--since` reads it: `30m` / `2h` / `7d` before
+ *  now, or an ISO date. `flag` names the option in the error. */
+declare function parseTimeBound(value: string, flag: string): number;
 
 type JsonSourceErrorKind = 'read' | 'parse';
 declare class JsonSourceError extends Error {
@@ -3844,10 +3855,28 @@ declare function readPullRequests(spans: readonly OtlpSpan[]): PullRequestReadin
  * deltas, which is a different (and smaller) number.
  */
 /** Cache invalidation key for deterministic measurements and prepared analyst context. */
-declare const SESSION_FACTS_MEASUREMENT_VERSION = "3";
+declare const SESSION_FACTS_MEASUREMENT_VERSION = "4";
+/**
+ * A half-open time window: a time `t` is inside when `since <= t < until`.
+ * Either bound may be absent, which leaves that side open.
+ */
+interface SessionFactsWindow {
+    /** ISO-8601 lower bound, inclusive. */
+    readonly since?: string;
+    /** ISO-8601 upper bound, exclusive. */
+    readonly until?: string;
+}
 interface SessionFactsOptions {
     /** Defaults to true for compatibility. False withholds conversation, commands, paths and assignment text. */
     readonly includeContent?: boolean;
+    /**
+     * Limit the turn facts to a time window. `humanTurns`, `excludedTurns` and
+     * `turnsByActor` keep only `user.prompt` turns that started inside it; every
+     * other fact still covers the whole session. A report built with a window
+     * also leaves out every session with no record inside it, and names them in
+     * {@link SessionFactsReport.selection}.
+     */
+    readonly window?: SessionFactsWindow;
 }
 declare const SESSION_TOKEN_TOTAL_ATTR = "traces.session.total_tokens";
 /**
@@ -3859,6 +3888,8 @@ declare const SESSION_TOKEN_TOTAL_ATTR = "traces.session.total_tokens";
 declare const SPAN_SYNTHESIZED_ATTR = "traces.codex.span_synthesized";
 /** Max characters of message or prompt text kept per fact entry. */
 declare const FACT_TEXT_CAP = 2000;
+/** Max characters of the agent message kept in {@link SessionTurnFact.answered}. */
+declare const ANSWERED_TEXT_CAP = 1500;
 /** Entries kept per list field before the sheet reports the rest as omitted. */
 declare const FACT_LIST_CAP = 200;
 /**
@@ -3904,6 +3935,15 @@ interface SessionTurnFact {
     readonly at: string;
     readonly text: string;
     readonly spanId: string;
+    /**
+     * The text of the last message this session's own agent wrote before the
+     * turn: what the person was answering. Clipped to {@link ANSWERED_TEXT_CAP}
+     * characters with a visible `… [+N chars]` marker. Null when the agent had
+     * written no text before the turn.
+     */
+    readonly answered: string | null;
+    /** The `message.assistant` span `answered` was read from. */
+    readonly answeredSpanId: string | null;
 }
 /** How many `user.prompt` turns each actor produced. */
 interface TurnActorCount {
@@ -3952,6 +3992,13 @@ interface SessionFacts {
     readonly traceId: string;
     readonly sessionId: string | null;
     readonly harness: string | null;
+    /**
+     * The working directory the harness recorded for the session, read from
+     * `traces.session.cwd` on the adapter's root span. Null with the reason when
+     * no span carries it; never decoded from a directory name or inferred from
+     * the paths the session touched.
+     */
+    readonly cwd: SessionFact<string>;
     /** Spans in this trace, including the synthesized ones. */
     readonly spanCount: number;
     /**
@@ -4002,18 +4049,45 @@ interface SessionFacts {
     readonly firstFailure: FirstFailure;
     readonly measurements: SessionMeasurements;
 }
+/** A session the report could not read, so whether it belongs in the window is unknown. */
+interface UnreadSessionFact {
+    readonly sessionId: string | null;
+    readonly traceId: string | null;
+    /** Where the session was read from, when the reader knows. */
+    readonly source: string | null;
+    readonly reason: string;
+}
+/** How a windowed report chose its sessions and turns. Null on a report built without a window. */
+interface SessionFactsSelection {
+    /** The window's inclusive lower bound, or null when open. */
+    readonly since: string | null;
+    /** The window's exclusive upper bound, or null when open. */
+    readonly until: string | null;
+    /** Which sessions the report holds. */
+    readonly sessionRule: string;
+    /** Which turns `humanTurns`, `excludedTurns` and `turnsByActor` hold. */
+    readonly turnRule: string;
+    /** Sessions read in full whose records all fall outside the window, by session id. */
+    readonly outsideWindow: readonly string[];
+    /** Sessions that could not be read; each is named with the reason, never counted as empty. */
+    readonly unreadSessions: readonly UnreadSessionFact[];
+}
 interface SessionFactsReport {
     readonly schemaVersion: 1;
     readonly kind: 'traces.session_facts_report';
     readonly generatedAt: string;
     readonly measurementVersion: typeof SESSION_FACTS_MEASUREMENT_VERSION;
-    /** SHA-256 of the canonical selected spans, including content, attributes, links and timing. */
+    /**
+     * SHA-256 over the selected sessions in trace-id order, each contributing the
+     * SHA-256 of its canonical spans (content, attributes, links and timing).
+     */
     readonly sourceDigest: string;
     /** Latest recorded endpoint, not the last time the filesystem was checked. */
     readonly evidenceThrough: string | null;
     readonly contentIncluded: boolean;
     readonly harness: string | null;
     readonly spanCount: number;
+    readonly selection: SessionFactsSelection | null;
     readonly sessions: readonly SessionFacts[];
 }
 /**
@@ -4022,11 +4096,25 @@ interface SessionFactsReport {
  * model, network call, or budget is involved.
  */
 declare function computeSessionFacts(spans: readonly OtlpSpan[], options?: SessionFactsOptions): SessionFacts[];
-/** The facts sheet for a set of spans, as one report. */
-declare function buildSessionFactsReport(spans: readonly OtlpSpan[], options?: SessionFactsOptions & {
+type SessionFactsReportOptions = SessionFactsOptions & {
     harness?: string | null;
     generatedAt?: string;
-}): SessionFactsReport;
+};
+/** The facts sheet for a set of spans, as one report. */
+declare function buildSessionFactsReport(spans: readonly OtlpSpan[], options?: SessionFactsReportOptions): SessionFactsReport;
+/**
+ * Builds one report from sessions supplied a batch at a time, so a caller
+ * reading many sessions holds one session's spans at once rather than all of
+ * them. `add` the whole spans of one or more sessions per call; a trace split
+ * across two calls is reported as two sessions.
+ */
+interface SessionFactsReportBuilder {
+    add(spans: readonly OtlpSpan[]): void;
+    /** Name a session that could not be read at all. Only a windowed report holds these. */
+    addUnread(session: UnreadSessionFact): void;
+    build(): SessionFactsReport;
+}
+declare function createSessionFactsReportBuilder(options?: SessionFactsReportOptions): SessionFactsReportBuilder;
 /** The short readable form: the same facts, one screen, no span-id lists. */
 declare function renderSessionFacts(report: SessionFactsReport): string;
 /**
@@ -5129,4 +5217,4 @@ declare function parseRetainedSession(input: {
     readonly signal?: AbortSignal;
 }): Promise<RetainedSessionSelection>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalysisEngineFromEnvOptions, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChangedFileFact, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type CompactionMeasurement, type ConformanceRenderOptions, type ContentFootprint, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, type CoveredMeasurement, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, DEFAULT_SWEEP_THRESHOLD, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EvidenceOnlyVerdict, type ExcludedTurnFact, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FACT_LIST_CAP, FACT_TEXT_CAP, FactoryAdapter, type FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, type FindingsFileOutcome, type FollowUpKind, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, HarnessSessionsAdapter, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, INHERITED_SOURCE_ATTR, INHERITED_SPANS_OMITTED_ATTR, INHERITED_SPAN_ATTR, INHERITED_SPAN_COUNT_ATTR, type InheritedSpanSource, type InspectSessionIndexOptions, type InstalledSkill, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, MAX_SHELL_DEPTH, MAX_TRACE_QUESTION_CHARS, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, POLICY_EVIDENCE_NOTE, PREPARED_CONTEXT_BYTE_CEILING, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PiAdapterOptions, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrimeAnalyzerOptions, type PrimeTransport, type PrimeTransportRequest, type PrimeTransportResponse, type ProjectSessionBundleOptions, type ProjectSessionBundleResult, type PullRequestFact, type PullRequestFacts, type PullRequestReading, QwenAdapter, REACTIONS, RESULT_FILE, RETAINED_SESSION_READER_VERSION, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RetainedSessionFile, type RetainedSessionSelection, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunDiffOptions, type RunDiffReport, type RunDiffSide, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SESSION_FACTS_MEASUREMENT_VERSION, SESSION_FACTS_VERSION_SUFFIX, SESSION_TOKEN_TOTAL_ATTR, SOURCE_ATTRIBUTE_PREFIX, SPAN_SYNTHESIZED_ATTR, SPAWN_JOURNAL_FILE, STATUS_MARK, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleIssue, type SessionBundleIssueKind, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleVerification, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionFact, type SessionFacts, type SessionFactsOptions, type SessionFactsReport, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionMeasurements, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionTextLeak, type SessionTextLeakReport, type SessionTurnFact, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkillCatalogRoots, type SkillUsageEvent, type SkillUsageHarness, type SkillUsageKind, type SkillUsageRefresh, type SkillUsageReport, type SkillUsageReportOptions, type SkillUsageRow, type SkillUsageSources, SkillUsageStore, type SkippedAnalysis, type SkippedInputFile, type SourceRecordReference, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpawnedChildResolution, type SpendRoll, type SteeringChainReport, type SteeringEdge, type SubagentSpawnFact, TRACE_QUESTION_PREVIEW_HEAD_CHARS, type ToolMeasurement, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceQuestion, type TraceQuestionAnswer, type TraceQuestionCitation, type TraceQuestionFailureKind, type TraceQuestionTrace, type TraceQuestionsArtifacts, type TraceQuestionsOptions, type TraceQuestionsResult, type TraceQuestionsTotals, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type TurnActorCount, type UnavailableCapabilities, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type VerifySafeOptions, type VerifySafeResult, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, assessSpans, buildPolicyEvidenceRecord, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSkillUsageReport, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeAdoption, computeSessionFacts, conformanceOfSpans, connectors, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultSkillCatalogRoots, defaultSkillUsageSources, defaultSkillUsageStorePath, defaultTraceLiveAnalysts, describeSessionRelationship, diffRuns, engineCallReservationFloorUsd, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, forEachTreeNode, formatFindingRejections, formatVerdict, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSynthesizedSpan, iterSerializedSpans, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseJsonAnswer, parseRetainedSession, parseSession, parseSince, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readInstalledSkills, readJsonFile, readJsonl, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunSide, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunDiff, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSkillUsage, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionFactsContext, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, sessionTextSignatures, shellCommands, skippedAnalyses, span, spanRunTotals, stampEnvironmentAttrs, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, totalFindingRejections, traceAgenticKinds, traceCitationsInText, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, verdictExitCode, verifyFindingsInSandbox, verifySafe, verifySessionBundle, watchRunTarget, watchSessions, withSessionFactsContext, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };
+export { ACTOR_ATTR, ANSWERED_TEXT_CAP, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalysisEngineFromEnvOptions, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChangedFileFact, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type CompactionMeasurement, type ConformanceRenderOptions, type ContentFootprint, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, type CoveredMeasurement, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, DEFAULT_SWEEP_THRESHOLD, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EvidenceOnlyVerdict, type ExcludedTurnFact, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FACT_LIST_CAP, FACT_TEXT_CAP, FactoryAdapter, type FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, type FindingsFileOutcome, type FollowUpKind, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, HarnessSessionsAdapter, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, INHERITED_SOURCE_ATTR, INHERITED_SPANS_OMITTED_ATTR, INHERITED_SPAN_ATTR, INHERITED_SPAN_COUNT_ATTR, type InheritedSpanSource, type InspectSessionIndexOptions, type InstalledSkill, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, MAX_SHELL_DEPTH, MAX_TRACE_QUESTION_CHARS, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, POLICY_EVIDENCE_NOTE, PREPARED_CONTEXT_BYTE_CEILING, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PiAdapterOptions, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrimeAnalyzerOptions, type PrimeTransport, type PrimeTransportRequest, type PrimeTransportResponse, type ProjectSessionBundleOptions, type ProjectSessionBundleResult, type PullRequestFact, type PullRequestFacts, type PullRequestReading, QwenAdapter, REACTIONS, RESULT_FILE, RETAINED_SESSION_READER_VERSION, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RetainedSessionFile, type RetainedSessionSelection, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunDiffOptions, type RunDiffReport, type RunDiffSide, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SESSION_CWD_ATTR, SESSION_FACTS_MEASUREMENT_VERSION, SESSION_FACTS_VERSION_SUFFIX, SESSION_TOKEN_TOTAL_ATTR, SOURCE_ATTRIBUTE_PREFIX, SPAN_SYNTHESIZED_ATTR, SPAWN_JOURNAL_FILE, STATUS_MARK, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleIssue, type SessionBundleIssueKind, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleVerification, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionFact, type SessionFacts, type SessionFactsOptions, type SessionFactsReport, type SessionFactsReportBuilder, type SessionFactsReportOptions, type SessionFactsSelection, type SessionFactsWindow, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionMeasurements, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionTextLeak, type SessionTextLeakReport, type SessionTurnFact, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkillCatalogRoots, type SkillUsageEvent, type SkillUsageHarness, type SkillUsageKind, type SkillUsageRefresh, type SkillUsageReport, type SkillUsageReportOptions, type SkillUsageRow, type SkillUsageSources, SkillUsageStore, type SkippedAnalysis, type SkippedInputFile, type SourceRecordReference, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpawnedChildResolution, type SpendRoll, type SteeringChainReport, type SteeringEdge, type SubagentSpawnFact, TRACE_QUESTION_PREVIEW_HEAD_CHARS, type ToolMeasurement, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceQuestion, type TraceQuestionAnswer, type TraceQuestionCitation, type TraceQuestionFailureKind, type TraceQuestionTrace, type TraceQuestionsArtifacts, type TraceQuestionsOptions, type TraceQuestionsResult, type TraceQuestionsTotals, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type TurnActorCount, type UnavailableCapabilities, type UnreadSessionFact, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type VerifySafeOptions, type VerifySafeResult, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, assessSpans, buildPolicyEvidenceRecord, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSkillUsageReport, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeAdoption, computeSessionFacts, conformanceOfSpans, connectors, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, createSessionFactsReportBuilder, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultSkillCatalogRoots, defaultSkillUsageSources, defaultSkillUsageStorePath, defaultTraceLiveAnalysts, describeSessionRelationship, diffRuns, engineCallReservationFloorUsd, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, forEachTreeNode, formatFindingRejections, formatVerdict, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSynthesizedSpan, iterSerializedSpans, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseJsonAnswer, parseRetainedSession, parseSession, parseSince, parseTimeBound, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readInstalledSkills, readJsonFile, readJsonl, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunSide, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunDiff, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSkillUsage, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionFactsContext, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, sessionTextSignatures, shellCommands, skippedAnalyses, span, spanRunTotals, stampEnvironmentAttrs, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, totalFindingRejections, traceAgenticKinds, traceCitationsInText, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, verdictExitCode, verifyFindingsInSandbox, verifySafe, verifySessionBundle, watchRunTarget, watchSessions, withSessionFactsContext, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };

package/dist/index.js

@@ -1,5 +1,6 @@
 import {
   ACTOR_ATTR,
+  ANSWERED_TEXT_CAP,
   ATTR,
   AmpAdapter,
   BLOBS_DIR,
@@ -43,6 +44,7 @@ import {
   REACTIONS,
   RESULT_FILE,
   RULE,
+  SESSION_CWD_ATTR,
   SESSION_FACTS_MEASUREMENT_VERSION,
   SESSION_FACTS_VERSION_SUFFIX,
   SESSION_TOKEN_TOTAL_ATTR,
@@ -100,6 +102,7 @@ import {
   countSkillRunsJsonl,
   createBundleSourceReader,
   createFindingRejectionTally,
+  createSessionFactsReportBuilder,
   cwdMatchesSelection,
   cwdMatchesSelectionResolved,
   defaultSkillCatalogRoots,
@@ -167,6 +170,7 @@ import {
   parseJsonAnswer,
   parseSession,
   parseSince,
+  parseTimeBound,
   planTraceAgenticRoute,
   planUpload,
   primeAnalyzer,
@@ -283,7 +287,7 @@ import {
   writeTraceQuestionsArtifacts,
   zaiChatCaller,
   zeroPricedCost
-} from "./chunk-DON6NQ7H.js";
+} from "./chunk-COSWFESO.js";
 
 // src/adapters/factory.ts
 import { readdir, stat } from "fs/promises";
@@ -936,6 +940,7 @@ async function parseRetainedSession(input) {
 }
 export {
   ACTOR_ATTR,
+  ANSWERED_TEXT_CAP,
   ATTR,
   AmpAdapter,
   AnalystRegistry,
@@ -983,6 +988,7 @@ export {
   RESULT_FILE,
   RETAINED_SESSION_READER_VERSION,
   RULE,
+  SESSION_CWD_ATTR,
   SESSION_FACTS_MEASUREMENT_VERSION,
   SESSION_FACTS_VERSION_SUFFIX,
   SESSION_TOKEN_TOTAL_ATTR,
@@ -1044,6 +1050,7 @@ export {
   createBundleSourceReader,
   createFindingRejectionTally,
   createHostedClient,
+  createSessionFactsReportBuilder,
   cwdMatchesSelection,
   cwdMatchesSelectionResolved,
   defaultSkillCatalogRoots,
@@ -1112,6 +1119,7 @@ export {
   parseRetainedSession,
   parseSession,
   parseSince,
+  parseTimeBound,
   planTraceAgenticRoute,
   planUpload,
   primeAnalyzer,

package/docs/trace-analysts.md

@@ -198,7 +198,8 @@ The sheet is that extraction, made part of the tool.
 | `subagentToolSpans` | TOOL spans excluded because a subagent, not this agent, made the call |
 | `subagents` | every subagent-spawning call, with the task name the call recorded |
 | `pullRequests` | pull requests the commands created and merged, each named by number or head branch, with the command span and the join evidence |
-| `humanTurns` | `user.prompt` turns a person typed into this session, in order, with timestamps |
+| `cwd` | the working directory the harness recorded for the session, or `null` with the reason |
+| `humanTurns` | `user.prompt` turns a person typed into this session, in order, with timestamps, each with the agent message it `answered` |
 | `excludedTurns` | every `user.prompt` turn `humanTurns` left out, grouped by the reason, with the span ids |
 | `turnsByActor` | every `user.prompt` turn by actor, so the human filter is checkable |
 | `finalMessages` | the last message of the session's own agent, and of each subagent task, separately |
@@ -242,7 +243,7 @@ It reaches the built-in kinds run by `analyze --llm`, `investigate`, and `improv
 
 - The sheet is bounded at `PREPARED_CONTEXT_BYTE_CEILING` (30,000 bytes), a fifth of the `perCallByteCeiling` of 150,000 the trace tools work to, so the rest of the budget stays available for the tool calls the model still makes.
 - When the sheet does not fit, fields are shed from the largest downward and the shed is listed in `omitted_fields`. The tool-call counts are the last facts to go.
-- Receiving the sheet changes an analyst's behavior, so its version carries `+session-facts.2`. `createTraceAnalyst` records `prepare_context` in the exact-run identity, and a changed prepared context must not hide behind an unchanged version.
+- Receiving the sheet changes an analyst's behavior, so its version carries `SESSION_FACTS_VERSION_SUFFIX` (`+session-facts.` and the sheet's `measurementVersion`). `createTraceAnalyst` records `prepare_context` in the exact-run identity, and a changed prepared context must not hide behind an unchanged version.
 - The sheet is not evidence. Citations still resolve against the raw spans, which is why every fact names its span ids rather than asking the model to trust the sheet.
 
 Pass `sessionFactsContext: false` to `analyzeSpans` to run an analyst without it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, \u2026) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite \u2014 observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
@@ -65,7 +65,7 @@
     "@tangle-network/agent-interface": "5.2.0",
     "@tangle-network/agent-runtime": "0.318.0",
     "@tangle-network/agent-trace-contract": "2.0.0",
-    "@tangle-network/harness-sessions": "0.1.0",
+    "@tangle-network/harness-sessions": "0.1.2",
     "@tangle-network/sandbox": "0.60.49"
   },
   "devDependencies": {