omnirush 0.7.1 → 0.8.0

package/assets/extensions/omnirush/collector-lib.ts

@@ -1,2433 +0,0 @@
-// Omnirush workspace collector — CLI port of the GUI reference
-// implementation (gui-reference/apps/server/src/workspace-collector.ts),
-// rebuilt 2026-09-23 around the "reproducible environment" spec:
-//
-//   1. Whole project BEFORE — full-tree "start" snapshot at session start.
-//   2. Replayable change log — ordered per-file journal records
-//      (at, path, status, content) uploaded as change snapshots; replaying
-//      start + the ordered records reproduces the end state.
-//   3. Whole project AFTER — full-tree "end" snapshot at session close.
-//   4. Fat traces — no truncation of trace events (trace_truncated only at
-//      the session budget wall).
-//   5. No file-count / journal caps. The only limit is the 100 GiB
-//      per-session budget (collection stops, loudly, never silent mid-file
-//      truncation). The backend's original 4 MiB per-file limit was
-//      removed server-side, so big files SHIP: content is sliced into
-//      <= 8 MiB entries (`<path>.__agent_part<i>`) with a
-//      `<path>.__agent_manifest.json` record (slice count, per-slice
-//      sha256) for deterministic reassembly. Parts target <= 15 MiB
-//      compressed (body rail live-verified >= 31.5 MiB), are ordered by
-//      sequence, and file content is never split across parts.
-//   6. FULL-WALK enumeration: every file in the workspace tree ships —
-//      node_modules, build outputs, .git (full reproducibility) — with
-//      ONLY the secrets denylist (.env*, keys, credentials, private
-//      keys) excluded. Binaries are captured (base64), symlinks are
-//      stored as {path, content: <target>, encoding: "symlink"} so the
-//      backend's text-content validation accepts them and replay
-//      recreates them, and
-//      the POSIX mode/executable bit rides each file entry for replay
-//      (stored-and-ignored on Windows). Redaction also scrubs
-//      credentials embedded in URLs (e.g. .git/config remotes).
-//      In-workspace journal files and stored trace/schema ids carry
-//      generic "agent" branding: __agent__/, agent.trace.v1.
-//
-// Deviations from the original port, forced by the CLI runtime:
-//   - The internal gitignore-style matcher was REMOVED together with
-//     .gitignore honoring: build outputs and node_modules are typically
-//     gitignored, so the walker no longer applies ignore rules at all
-//     (the secrets denylist still applies).
-//   - Uploads go straight to the manager /collect endpoint with the
-//     device access token; an optional `refresh` callback gives the
-//     broker's on-401 single-flight refresh + retry-once behavior.
-//
-// Runs under the bundled bun (which provides node:zlib zstdCompress;
-// plain Node needs >= 22.15). All helpers used by node:test are pure or
-// injectable, so the suite exercises them on any runtime.
-
-import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
-
-import { readFileSync } from "node:fs";
-import { lstat, mkdir, readFile, readdir, readlink, writeFile } from "node:fs/promises";
-import os from "node:os";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { promisify } from "node:util";
-import { zstdCompress as zstdCompressCb } from "node:zlib";
-
-import { isRetryableStatus, retryAttempts, withRetries } from "./retry";
-import { buildTraceArtifact, parsePiSession } from "./trace-format";
-
-const execFileAsync = promisify(execFile);
-
-// --- limits ---------------------------------------------------------------
-// Session budget: collection stops (with a warning) once this much
-// uncompressed payload has been sent for a session. There are no other
-// policy caps — no file-count cap, no journal cap.
-export const MAX_SESSION_BYTES = 100 * 1024 * 1024 * 1024;
-// Per-content-entry slice size. The backend's original 4 MiB per-file
-// limit was REMOVED server-side (2026-09-23), so big files no longer get
-// skipped: their content is sliced into <= MAX_SLICE_BYTES entries with
-// sequential virtual paths (`<path>.__agent_part<i>`) plus a
-// `<path>.__agent_manifest.json` record (path, slice count, per-slice
-// byte size + sha256) so replay reassembles the original deterministically.
-export const MAX_SLICE_BYTES = 4 * 1024 * 1024;
-// Whole-read ceiling. Files up to this size are read and processed as
-// one string; bigger files stream in fixed raw chunks and slice.
-// Deliberately tiny (issue #6): a whole read holds buffer + utf8 string
-// + redaction copy + base64 simultaneously (~4-5x file size), so even a
-// modest ceiling spikes RSS by that multiple per file. 8 MiB bounds the
-// worst case to ~40 MiB; anything bigger takes the streaming path with
-// identical output.
-const WHOLE_READ_BYTES = 8 * 1024 * 1024;
-// Text-segment cap for newline-less files (see the streaming reader).
-const PENDING_TEXT_CAP_BYTES = 32 * 1024 * 1024;
-// Change-journal memory ceiling (issue #6, Windows 8-9 GiB OOM): the
-// journal holds every changed file's content between debounced change
-// uploads. At HIGH_WATER an upload is forced immediately (normal
-// backpressure); at the HARD ceiling — a backend down for a long time —
-// the OLDEST records are dropped, loudly (warn + journal.dropped trace),
-// because losing replay data beats crashing the whole session.
-// Soft disk cap for the on-disk change journal: when unacked journal
-// bytes exceed it (a backend down for a very long time), capture stops
-// loudly instead of filling the disk. The end snapshot still ships.
-export const JOURNAL_DISK_CAP_BYTES = 1024 * 1024 * 1024;
-/**
- * Non-enumerable per-record field carrying the raw serialized line
- * length (for journal ack accounting) — invisible to JSON.stringify so
- * the changes.json sidecar never includes it.
- */
-export const RAW_BYTES_FIELD = Symbol("omnirushJournalRawBytes");
-// Multi-file parts target this compressed size (the backend body rail
-// was live-verified at >= 31.5 MiB compressed, so 15 MiB leaves ample
-// headroom for any ingress in front of the manager).
-export const MAX_PART_COMPRESSED_BYTES = 15 * 1024 * 1024;
-// Absolute rail for any single request body (client-side backstop well
-// above the validated 31.5 MiB; single-file parts may use it).
-export const MAX_PART_COMPRESSED_HARD = 32 * 1024 * 1024;
-// Accumulate this many uncompressed bytes before a compress-and-check.
-export const PART_UNCOMPRESSED_STEP = 8 * 1024 * 1024;
-// Flush a part when a check shows at least this much compressed payload.
-export const PART_READY_COMPRESSED_BYTES = 12 * 1024 * 1024;
-// Absolute uncompressed ceiling for one part batch — bounds resident
-// memory even for highly-compressible content (incompressible batches
-// never hit the compressed-size thresholds, so this is what actually
-// stops accumulation; the payload build doubles it transiently).
-export const PART_BATCH_UNCOMPRESSED_MAX = 24 * 1024 * 1024;
-// Change/trace parts flush by PLAIN size so their __agent__/changes.json
-// / trace.json entries (single file entries whose content grows with the
-// batch) stay small and parts upload promptly.
-export const PART_SIDECAR_PLAIN_MAX = 1024 * 1024;
-// Soft in-memory relief for trace events (they are uploaded, never
-// dropped — this only bounds resident memory between flushes).
-export const TRACE_RELIEF_EVENTS = 2_000;
-
-// Generic in-workspace journal directory + stored schema id (branding
-// neutral — the traces are the product).
-export const AGENT_DIR = "__agent__";
-export const AGENT_TRACE_SCHEMA = "agent.trace.v1";
-
-let cachedClientVersion: string | null | undefined;
-
-/**
- * The CLI's package.json version, resolved once relative to this module
- * (repo checkout and installed npm layout both keep package.json three
- * levels up). Empty when it cannot be read — the envelope field is
- * optional and the backend tolerates its absence.
- */
-export function detectClientVersion(): string {
-  if (cachedClientVersion !== undefined) return cachedClientVersion ?? "";
-  cachedClientVersion = null;
-  try {
-    const parsed = JSON.parse(
-      readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),
-    ) as { version?: unknown };
-    if (parsed && typeof parsed.version === "string") cachedClientVersion = parsed.version;
-  } catch {
-    cachedClientVersion = null;
-  }
-  return cachedClientVersion ?? "";
-}
-
-/** "linux/x64"-style platform tag for the envelope metadata. */
-export function detectClientPlatform(): string {
-  try {
-    return `${os.platform()}/${os.arch()}`;
-  } catch {
-    return "";
-  }
-}
-
-/**
- * Per-session transport gate: serializes envelope sends while giving
- * trace parts priority over baseline (start/change/end) parts. Two
- * upload lanes (the serial session tail and the trace tail) share the
- * transport through this gate; a release always wakes a waiting trace
- * acquisition before a background one, and the background lane
- * additionally yields while trace work is pending (see
- * `yieldToTrace`), so a trace part is never delayed by more than the
- * one baseline part already in flight.
- */
-export class PriorityGate {
-  private held = false;
-  private readonly queue: Array<{ priority: boolean; wake: () => void }> = [];
-
-  async acquire(priority: boolean): Promise<void> {
-    if (!this.held) {
-      this.held = true;
-      return;
-    }
-    await new Promise<void>((resolveWake) => {
-      this.queue.push({ priority, wake: resolveWake });
-    });
-  }
-
-  release(): void {
-    const index = this.queue.findIndex((waiter) => waiter.priority);
-    const next = index >= 0 ? this.queue.splice(index, 1)[0] : this.queue.shift();
-    if (next) next.wake();
-    else this.held = false;
-  }
-
-  get waiting(): number {
-    return this.queue.length;
-  }
-}
-
-export const CHANGE_DEBOUNCE_MS = 2_000;
-export const FALLBACK_SCAN_MS = 10_000;
-export const MAX_SESSION_LEDGER_ENTRIES = 512;
-export const SESSION_LEDGER_FILE = "omnirush-collector-sessions.json";
-
-type SnapshotType = "start" | "change" | "trace" | "end";
-
-export type CollectorFile = {
-  path: string;
-  /** utf8 text by default. For binaries: base64. For symlinks: the link
-   *  target verbatim (the backend requires text content on every file
-   *  entry, so symlink records are text entries with a marker). */
-  content: string;
-  /** Absent = utf8 text. "base64" for binary content, "symlink" for
-   *  symlink records (content = link target). */
-  encoding?: "base64" | "symlink";
-  /** POSIX mode bits (octal string, e.g. "755"). Absent for symlinks. */
-  mode?: string;
-};
-
-type TraceEvent = {
-  at: string;
-  type: string;
-  data?: unknown;
-};
-
-export type ChangeJournalEntry = {
-  at: string;
-  path: string;
-  status: "present" | "deleted";
-  content?: string;
-  encoding?: "base64" | "symlink";
-  mode?: string;
-  /** Present when the record carries one slice of a bigger file. */
-  slice?: { index: number; total: number; bytes: number; sha256: string };
-};
-
-export type SessionLedgerRecord = {
-  segment: number;
-  nextSequence: number;
-  sentBytes?: number;
-  lastMessageId?: string;
-  /** True once the session's full-tree start baseline shipped. A resumed
-   *  session must NOT re-upload it — a restart-heavy session would
-   *  otherwise re-burn the entire baseline (and starve traces) on every
-   *  restart. Observed live: 846 start snapshots / multiple GB for one
-   *  session. */
-  baselineUploaded?: boolean;
-  /** Part-level baseline resume cursor: every sorted path <= this has
-   *  shipped in the session's start snapshot. Set after each acked
-   *  baseline part, cleared once the baseline completes. A resumed
-   *  session whose baseline never finished skips those paths (the first
-   *  unacked part onward) instead of re-burning them. */
-  baselineResumePath?: string;
-  lastSeenAt: string;
-  /** Per-session-FILE transcript capture state (issue: trace format spec).
-   *  Keys are absolute .jsonl paths; a size/mtime change re-captures. */
-  traces?: Record<string, { size: number; mtimeMs: number }>;
-};
-
-export type SessionLedger = {
-  version: 1;
-  sessions: Record<string, SessionLedgerRecord>;
-};
-
-type SessionState = {
-  id: string;
-  root: string;
-  workspaceId: string;
-  sentBytes: number;
-  segment: number;
-  sequence: number;
-  resumed: boolean;
-  lastMessageId?: string;
-  lastSignature: string;
-  started: boolean;
-  finished: boolean;
-  budgetExhausted: boolean;
-  baselineUploaded: boolean;
-  /** Resume cursor for an interrupted start baseline (see
-   *  SessionLedgerRecord.baselineResumePath); null once it completed. */
-  baselineResumePath: string | null;
-  changeTimer: ReturnType<typeof setTimeout> | null;
-  scanTimer: ReturnType<typeof setInterval> | null;
-  /** Known per-path stat snapshot (mtimeMs + size) for change detection.
-   *  fs.watch is deliberately NOT used: its recursive handle keeps the
-   *  event loop alive even after close()/unref() on every runtime, which
-   *  hung sessions at exit (issue: process never exits after the reply).
-   *  The scan loop diffs these snapshots instead. */
-  knownStats: Map<string, { mtimeMs: number; size: number }>;
-  /** True while a change scan is in flight (scans self-serialize). */
-  scanning: boolean;
-  /** Set once the per-path stat snapshot has been seeded (post-baseline
-   *  walk) — the scan gate, deliberately independent of the start
-   *  UPLOAD succeeding so capture keeps working when the backend is
-   *  down (that is when the journal must absorb changes). */
-  baselineSeeded: boolean;
-  /** Paths the session knows exist(ed): the baseline walk plus every
-   *  captured present record. Deletion records require membership —
-   *  macOS FSEvents leaks parent-directory events (e.g. the previous
-   *  tmpdir's removal) into a freshly created watch, which must not
-   *  fabricate deletions inside the workspace. */
-  knownPaths: Set<string>;
-  trace: TraceEvent[];
-  /**
-   * The change journal lives ON DISK (ndjson sidecar, one JSON record
-   * per line) — never as an in-memory array (issue #6: the array held
-   * every changed file's content string and grew to multiple GB).
-   * Captures APPEND to the file; change uploads stream the unacked
-   * region and compact the acked prefix away. Appends during an upload
-   * simply land past the read window (bounded by `journalUploadEof`) —
-   * no gating, no memory growth.
-   */
-  journalPath: string | null;
-  /** File offset of the first not-yet-uploaded record. */
-  journalAckOffset: number;
-  /** Bytes appended so far (soft disk cap accounting). */
-  journalAppendedBytes: number;
-  /** Serializes journal appends. */
-  journalAppendTail: Promise<void>;
-  /** Set while a change upload reads the journal. */
-  journalUploadEof: number | null;
-  /** True once the soft disk cap stopped captures (warned once). */
-  journalCaptureStopped: boolean;
-  /** Last journal signature per path (consecutive-duplicate suppression). */
-  journalLastByPath: Map<string, string>;
-  /** Transcript capture state carried across runs via the ledger. */
-  transcripts: Record<string, { size: number; mtimeMs: number }>;
-  changeCaptureTail: Promise<void>;
-  ready: Promise<void>;
-  /** Baseline/change/end lane: serialized, background priority. */
-  tail: Promise<void>;
-  /** Trace lane: serialized within itself, priority over `tail` at the
-   *  transport gate. Trace parts must never queue behind baseline
-   *  parts. */
-  traceTail: Promise<void>;
-  /** Trace operations enqueued but not settled (queued or running). */
-  tracePending: number;
-  /** Resolves whenever `tracePending` returns to 0; re-armed by
-   *  `enqueueTrace`. The background lane waits on it before starting
-   *  another baseline part. */
-  traceDrain: Promise<void>;
-  resolveTraceDrain: () => void;
-  /** Serializes envelope sends across both lanes; trace acquisitions
-   *  jump ahead of queued background ones. */
-  gate: PriorityGate;
-};
-
-export type CollectorOptions = {
-  gatewayUrl?: string;
-  accessToken?: string;
-  /** pi agent config dir (~/.pi/agent): session transcripts live under
-   *  <agentDir>/sessions/<cwd-slug>/. Required for trace capture. */
-  agentDir?: string;
-  /** Resolves the signed-in user id for trace headers (best effort). */
-  identityProvider?: () => Promise<{ userId: string | null }>;
-  /** Stable client identifier for trace headers (e.g. hostname). */
-  clientId?: string;
-  fetch?: typeof fetch;
-  /** Returns the rotated access token, or null when refresh failed. */
-  refresh?: (tokenUsed: string) => Promise<string | null>;
-  upload?: (sessionId: string, compressed: Uint8Array) => Promise<Response>;
-  stateDir?: string;
-  log?: (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
-  changeDebounceMs?: number;
-  fallbackScanMs?: number;
-  /** Per-session collection budget. Default MAX_SESSION_BYTES (100 GiB). */
-  sessionBudgetBytes?: number;
-  /** Client version reported in every envelope (additive metadata the
-   *  backend tolerates). Default: detectClientVersion(). */
-  clientVersion?: string;
-  /** Client platform tag. Default: detectClientPlatform(). */
-  clientPlatform?: string;
-  /** Linked/child mode: this process is a SUBAGENT of an existing
-   *  session (spawn_agents sets OMNIRUSH_PARENT_SESSION). The collector
-   *  then ships only trace events + this session's own transcript
-   *  artifact, stamped parent_session_id — never a second workspace
-   *  baseline/change/end collection. */
-  linkedParentSession?: string;
-  /** Multi-file part compressed target. Default MAX_PART_COMPRESSED_BYTES. */
-  partCompressedBytes?: number;
-  /** Uncompressed accumulation step between compress checks. */
-  partCheckBytes?: number;
-};
-
-// .git is deliberately NOT denied: full reproducibility includes the
-// repository metadata. Credentials inside it (e.g. remote URLs with
-// embedded passwords in .git/config) are covered by the URL redaction
-// pattern below and the credential-name denylist.
-const DENIED_EXACT_NAMES = new Set([
-  ".ssh",
-  "keys",
-  "secrets",
-  ".npmrc",
-  ".pypirc",
-  "credentials",
-  "credentials.json",
-  "id_rsa",
-  "id_ed25519",
-]);
-
-const DENIED_SUFFIXES = [".pem", ".key", ".p12", ".pfx", ".jks", ".keystore"];
-const DENIED_CREDENTIAL_NAME = /(^|[._-])(?:credentials?|secrets?|private[_-]?keys?)([._-]|$)/i;
-const SECRET_PATTERNS: Array<[RegExp, string]> = [
-  [/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, "[REDACTED]"],
-  [/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED]"],
-  [/\b(?:sk|rk|pk)-(?:proj-)?[A-Za-z0-9_-]{16,}\b/g, "[REDACTED]"],
-  [/^([A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY)\s*=\s*)([^\s#]{6,})$/gim, "$1[REDACTED]"],
-  // Credentials embedded in URLs (git remotes in .git/config, pip
-  // indexes, ...): https://user:password@host -> https://user:[REDACTED]@host
-  [/\b(https?:\/\/[^\s\/@:#]+:)([^\s\/@]+)(@)/gi, "$1[REDACTED]$3"],
-];
-const PII_PATTERNS: Array<[RegExp, string]> = [
-  [/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[REDACTED_PII]"],
-  [/(?<!\w)(?:\+\d{1,3}[\s.-]?)?(?:\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4})(?!\w)/g, "[REDACTED_PII]"],
-  [/(?<!\w)\d{3}-\d{2}-\d{4}(?!\w)/g, "[REDACTED_PII]"],
-  [/(?<![\d.])(?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}(?!\d)/g, "[REDACTED_PII]"],
-];
-
-export function resolveCollectUrl(rawGatewayUrl: string | undefined): string | null {
-  const value = rawGatewayUrl?.trim();
-  if (!value) return null;
-  try {
-    const url = new URL(value);
-    if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "::1"].includes(url.hostname))) {
-      return null;
-    }
-    url.pathname = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "") + "/collect";
-    url.search = "";
-    url.hash = "";
-    return url.toString();
-  } catch {
-    return null;
-  }
-}
-
-function portablePath(root: string, path: string): string {
-  return relative(root, path).split(sep).join("/");
-}
-
-export function isCollectorPathDenied(path: string): boolean {
-  const parts = path.replaceAll("\\", "/").split("/").filter(Boolean);
-  return parts.some((part) => {
-    const lower = part.toLowerCase();
-    return lower.startsWith(".env")
-      || DENIED_EXACT_NAMES.has(lower)
-      || DENIED_SUFFIXES.some((suffix) => lower.endsWith(suffix))
-      || DENIED_CREDENTIAL_NAME.test(lower);
-  });
-}
-
-export function redactCollectorText(input: string): { text: string; count: number } {
-  let text = input;
-  let count = 0;
-  for (const [pattern, replacement] of SECRET_PATTERNS) {
-    pattern.lastIndex = 0;
-    const matches = text.match(pattern);
-    count += matches?.length ?? 0;
-    pattern.lastIndex = 0;
-    text = text.replace(pattern, replacement);
-  }
-  for (const [pattern, replacement] of PII_PATTERNS) {
-    pattern.lastIndex = 0;
-    const matches = text.match(pattern);
-    count += matches?.length ?? 0;
-    pattern.lastIndex = 0;
-    text = text.replace(pattern, replacement);
-  }
-  return { text, count };
-}
-
-function isBinary(buffer: Buffer): boolean {
-  const sample = buffer.subarray(0, Math.min(buffer.length, 8_192));
-  if (sample.includes(0)) return true;
-  let suspicious = 0;
-  for (const byte of sample) {
-    if (byte < 7 || (byte > 13 && byte < 32)) suspicious += 1;
-  }
-  return sample.length > 0 && suspicious / sample.length > 0.1;
-}
-
-function comparePaths(left: string, right: string): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
-
-export async function readSessionLedger(path: string | null): Promise<SessionLedger> {
-  if (!path) return { version: 1, sessions: {} };
-  try {
-    const parsed = JSON.parse(await readFile(path, "utf8")) as Partial<SessionLedger>;
-    if (parsed.version !== 1 || !parsed.sessions || typeof parsed.sessions !== "object") {
-      return { version: 1, sessions: {} };
-    }
-    const sessions = Object.fromEntries(
-      Object.entries(parsed.sessions as Record<string, unknown>).flatMap(([sessionId, value]) => {
-        if (!value || typeof value !== "object") return [];
-        const record = value as Partial<SessionLedgerRecord>;
-        if (typeof record.segment !== "number" || !Number.isSafeInteger(record.segment) || record.segment < 1
-          || typeof record.nextSequence !== "number" || !Number.isSafeInteger(record.nextSequence) || record.nextSequence < 0
-          || (record.sentBytes !== undefined && (!Number.isSafeInteger(record.sentBytes) || record.sentBytes < 0))
-          || typeof record.lastSeenAt !== "string") return [];
-        return [[sessionId, record as SessionLedgerRecord] as const];
-      }),
-    );
-    return { version: 1, sessions };
-  } catch {
-    return { version: 1, sessions: {} };
-  }
-}
-
-export function boundedTracePayload(
-  state: Pick<SessionState, "id" | "workspaceId" | "segment" | "resumed">,
-  events: TraceEvent[],
-  maxBytes = MAX_SESSION_BYTES,
-): Buffer {
-  const encode = (selected: TraceEvent[], truncated: boolean, includedCount = selected.length) => Buffer.from(redactCollectorText(JSON.stringify({
-    schema_version: 1,
-    schema: AGENT_TRACE_SCHEMA,
-    session_id: state.id,
-    workspace_id: state.workspaceId,
-    session_segment: state.segment,
-    session_resumed: state.resumed,
-    trace_truncated: truncated,
-    dropped_event_count: Math.max(0, events.length - includedCount),
-    events: selected,
-  })).text);
-
-  const selected: TraceEvent[] = [];
-  for (const event of events) {
-    const candidate = encode([...selected, event], true);
-    if (candidate.byteLength > maxBytes) break;
-    selected.push(event);
-  }
-  let payload = encode(selected, selected.length < events.length);
-  while (payload.byteLength > maxBytes && selected.length > 0) {
-    selected.pop();
-    payload = encode(selected, true);
-  }
-  if (selected.length === 0 && events.length > 0) {
-    const marker: TraceEvent = {
-      at: new Date().toISOString(),
-      type: "trace.truncated",
-      data: { dropped_event_count: events.length },
-    };
-    const marked = encode([marker], true, 0);
-    if (marked.byteLength <= maxBytes) return marked;
-  }
-  return payload;
-}
-
-/**
- * Select the longest prefix of events whose JSON fits maxBytes — the
- * budget-wall behavior for traces. With the default 100 GiB budget this
- * only fires at the wall; traces are otherwise never truncated.
- */
-export function selectTraceEvents(
-  events: TraceEvent[],
-  maxBytes: number,
-): { events: TraceEvent[]; truncated: boolean; droppedCount: number } {
-  if (events.length === 0) return { events: [], truncated: false, droppedCount: 0 };
-  const fits = (candidate: TraceEvent[]) => Buffer.byteLength(JSON.stringify(candidate)) <= maxBytes;
-  if (fits(events)) return { events, truncated: false, droppedCount: 0 };
-  const selected: TraceEvent[] = [];
-  for (const event of events) {
-    if (!fits([...selected, event])) break;
-    selected.push(event);
-  }
-  return { events: selected, truncated: true, droppedCount: events.length - selected.length };
-}
-
-/**
- * FULL-WALK enumeration: every path in the workspace tree — regular
- * files, symlinks (including links to directories; links are recorded,
- * never followed, so cycles are impossible), and .git internals. The
- * ONLY exclusions are the secrets-denylist paths. Git-aware listing was
- * removed on purpose: `git ls-files` drops anything .gitignored (build
- * outputs, node_modules), which broke the whole-project guarantee.
- */
-export async function listWorkspaceFiles(root: string): Promise<string[]> {
-  return walkWorkspace(root);
-}
-
-async function walkWorkspace(root: string, directory = root, output: string[] = []): Promise<string[]> {
-  let entries;
-  try {
-    entries = await readdir(directory, { withFileTypes: true });
-  } catch {
-    return output;
-  }
-  for (const entry of entries) {
-    const fullPath = resolve(directory, entry.name);
-    const path = portablePath(root, fullPath);
-    if (!path || isCollectorPathDenied(path)) continue;
-    if (entry.isDirectory()) await walkWorkspace(root, fullPath, output);
-    else output.push(path); // regular files AND symlinks (files or dirs)
-  }
-  return output;
-}
-
-async function gitMetadata(root: string): Promise<Record<string, string | null>> {
-  const git = async (...args: string[]) => {
-    try {
-      const { stdout } = await execFileAsync("git", ["-C", root, ...args], { timeout: 5_000, maxBuffer: 64 * 1024 });
-      return String(stdout).trim() || null;
-    } catch {
-      return null;
-    }
-  };
-  const [commit, branch, status] = await Promise.all([
-    git("rev-parse", "HEAD"),
-    git("branch", "--show-current"),
-    git("status", "--porcelain", "--untracked-files=no"),
-  ]);
-  return { commit, branch, dirty: status ? "true" : "false" };
-}
-
-async function workspaceSignature(root: string): Promise<string> {
-  const hash = createHash("sha256");
-  for (const path of await listWorkspaceFiles(root)) {
-    try {
-      const file = await lstat(resolve(root, path));
-      if (file.isFile()) {
-        hash.update(path).update("\0").update(String(file.size)).update("\0").update(String(file.mtimeMs)).update("\0");
-      } else if (file.isSymbolicLink()) {
-        hash.update(path).update("\0").update("link").update("\0").update(String(file.mtimeMs)).update("\0");
-      }
-    } catch {
-      // A file can disappear while the workspace is being scanned.
-    }
-  }
-  return hash.digest("hex");
-}
-
-function sha256Hex(content: string): string {
-  return createHash("sha256").update(content).digest("hex");
-}
-
-/** Split a string into <= maxUnits slices without splitting surrogates. */
-export function sliceString(content: string, maxUnits = MAX_SLICE_BYTES): string[] {
-  if (content.length <= maxUnits) return [content];
-  const slices: string[] = [];
-  let start = 0;
-  while (start < content.length) {
-    let end = Math.min(start + maxUnits, content.length);
-    if (end < content.length) {
-      const code = content.charCodeAt(end - 1);
-      if (code >= 0xd800 && code <= 0xdbff) end -= 1;
-    }
-    slices.push(content.slice(start, end));
-    start = end;
-  }
-  return slices;
-}
-
-/** Slice entry virtual path + manifest path for a logical file path. */
-export function slicePartPath(path: string, index: number): string {
-  return `${path}.__agent_part${index}`;
-}
-export function sliceManifestPath(path: string): string {
-  return `${path}.__agent_manifest.json`;
-}
-
-/**
- * Slice one logical file's content into <= MAX_SLICE_BYTES entries plus a
- * manifest record (path, slice count, per-slice byte size + sha256) so
- * replay reassembles the original deterministically. Small files pass
- * through unchanged.
- */
-export function buildFileEntries(file: CollectorFile): CollectorFile[] {
-  const content = file.content ?? "";
-  if (Buffer.byteLength(content) <= MAX_SLICE_BYTES) return [file];
-  const slices = sliceString(content);
-  const descriptors = slices.map((slice, index) => ({
-    index,
-    bytes: Buffer.byteLength(slice),
-    sha256: sha256Hex(slice),
-  }));
-  return [
-    { path: sliceManifestPath(file.path), content: JSON.stringify(sliceManifest(file, descriptors)) },
-    ...slices.map((slice, index) => ({
-      path: slicePartPath(file.path, index),
-      content: slice,
-      ...(file.encoding ? { encoding: file.encoding } : {}),
-    })),
-  ];
-}
-
-/**
- * Manifest for a sliced file. `slice_count` is the GLOBAL count and each
- * entry carries its global `index`, so manifests arriving across
- * different parts union deterministically: a replay collects the part
- * entries by index (verifying per-slice sha256) until all
- * `slice_count` indexes are present, then reassembles.
- */
-function sliceManifest(
-  file: { path: string; encoding?: "base64"; mode?: string },
-  sliceDescriptors: Array<{ index: number; bytes: number; sha256: string }>,
-  totalCount?: number,
-): Record<string, unknown> {
-  return {
-    schema_version: 1,
-    path: file.path,
-    encoding: file.encoding ?? null,
-    mode: file.mode ?? null,
-    slice_count: totalCount ?? sliceDescriptors.length,
-    slices: sliceDescriptors,
-  };
-}
-
-type ContentChunk = { content: string; encoding?: "base64" };
-
-/**
- * Stream a regular file as <= ~8 MiB content chunks, yielding each chunk
- * the moment it is produced — a file's content is NEVER materialized as
- * one string regardless of size (issue #6: the old array version held
- * every chunk at once). Small files are a single whole read; big files
- * stream in fixed raw chunks. Binary detection happens on the first
- * chunk and applies to the whole file; text is redacted per
- * line-aligned segment.
- */
-async function* iterateContentChunks(absolute: string, size: number): AsyncGenerator<ContentChunk> {
-  if (size <= WHOLE_READ_BYTES) {
-    const buffer = await readFile(absolute);
-    if (isBinary(buffer)) {
-      yield { content: buffer.toString("base64"), encoding: "base64" };
-      return;
-    }
-    yield { content: redactCollectorText(buffer.toString("utf8")).text };
-    return;
-  }
-  const { open } = await import("node:fs/promises");
-  const handle = await open(absolute, "r");
-  try {
-    const chunkBytes = 8 * 1024 * 1024;
-    const buffer = Buffer.alloc(chunkBytes);
-    const first = await handle.read(buffer, 0, chunkBytes, null);
-    const binary = isBinary(buffer.subarray(0, first.bytesRead));
-    if (binary) {
-      // Binaries carry no redactable text: base64 each raw chunk.
-      yield { content: buffer.subarray(0, first.bytesRead).toString("base64"), encoding: "base64" };
-      let read = 0;
-      while ((read = (await handle.read(buffer, 0, chunkBytes, null)).bytesRead) > 0) {
-        yield { content: buffer.subarray(0, read).toString("base64"), encoding: "base64" };
-      }
-      return;
-    }
-    // Text: decode incrementally (StringDecoder absorbs multibyte
-    // sequences split across chunk boundaries), emit only up to the
-    // last complete line, carry the remainder, and redact each
-    // line-aligned segment. A pathological newline-less file must not
-    // grow `pending` forever: at PENDING_TEXT_CAP_BYTES the segment is
-    // flushed mid-line (line-anchored redaction weakens at that rare
-    // cut; unbounded memory is worse).
-    const { StringDecoder } = await import("node:string_decoder");
-    const decoder = new StringDecoder("utf8");
-    let pending = decoder.write(buffer.subarray(0, first.bytesRead));
-    let read = 0;
-    while ((read = (await handle.read(buffer, 0, chunkBytes, null)).bytesRead) > 0) {
-      pending += decoder.write(buffer.subarray(0, read));
-      for (;;) {
-        const lastNl = pending.lastIndexOf("\n");
-        if (lastNl >= 0) {
-          yield { content: redactCollectorText(pending.slice(0, lastNl + 1)).text };
-          pending = pending.slice(lastNl + 1);
-          continue;
-        }
-        if (pending.length >= PENDING_TEXT_CAP_BYTES) {
-          yield { content: redactCollectorText(pending).text };
-          pending = "";
-        }
-        break;
-      }
-    }
-    pending += decoder.end();
-    if (pending) yield { content: redactCollectorText(pending).text };
-  } finally {
-    await handle.close();
-  }
-}
-
-/**
- * Stream one workspace entry as CollectorFile entries. Regular files:
- * text is redacted, binaries base64-encoded ("encoding": "base64"), and
- * the POSIX mode rides along (octal string) so replay can restore the
- * executable bit (stored-and-ignored on Windows). Content bigger than
- * MAX_SLICE_BYTES is sliced on the fly — slices are yielded the moment
- * they exist while only the tiny sha256 descriptors accumulate, then
- * the manifest is yielded LAST (replay unions manifests by index, so
- * position never matters). Symlinks become text entries
- * { path, content: <target>, encoding: "symlink" } — the backend's
- * per-entry validation requires text content, and replay recreates the
- * actual link from the target. Yields nothing when the entry vanished
- * or is a special file.
- */
-async function* iterateWorkspaceEntries(root: string, path: string): AsyncGenerator<CollectorFile> {
-  let absolute = "";
-  try {
-    absolute = resolve(root, path);
-    if (portablePath(root, absolute).startsWith("../")) return;
-    const file = await lstat(absolute);
-    if (file.isSymbolicLink()) {
-      const target = await readlink(absolute);
-      yield { path, content: target, encoding: "symlink" };
-      return;
-    }
-    if (!file.isFile()) return;
-    const mode = file.mode & 0o777;
-    const modeField = mode ? { mode: mode.toString(8) } : {};
-    if (file.size <= WHOLE_READ_BYTES) {
-      // Small file: whole read, real path preserved; buildFileEntries
-      // slices (manifest + parts) when the encoded content exceeds
-      // MAX_SLICE_BYTES — same shape as always.
-      for await (const chunk of iterateContentChunks(absolute, file.size)) {
-        for (const entry of buildFileEntries({
-          path,
-          content: chunk.content,
-          ...(chunk.encoding ? { encoding: chunk.encoding } : {}),
-          ...modeField,
-        })) {
-          yield entry;
-        }
-      }
-      return;
-    }
-    // Big file (streamed): slices are yielded the moment they exist;
-    // only the tiny sha256 descriptors accumulate. The reassembly
-    // manifest is yielded LAST (replay unions manifests by index, so
-    // position never matters).
-    let index = 0;
-    const descriptors: Array<{ index: number; bytes: number; sha256: string }> = [];
-    let sawEncoding: "base64" | undefined;
-    for await (const chunk of iterateContentChunks(absolute, file.size)) {
-      sawEncoding ??= chunk.encoding;
-      for (const slice of sliceString(chunk.content)) {
-        descriptors.push({ index, bytes: Buffer.byteLength(slice), sha256: sha256Hex(slice) });
-        yield {
-          path: slicePartPath(path, index),
-          content: slice,
-          ...(sawEncoding ? { encoding: sawEncoding } : {}),
-        };
-        index += 1;
-      }
-    }
-    if (index === 0) return;
-    yield {
-      path: sliceManifestPath(path),
-      content: JSON.stringify(sliceManifest(
-        { path, ...(sawEncoding ? { encoding: sawEncoding } : {}), ...modeField },
-        descriptors,
-      )),
-    };
-    return;
-  } catch {
-    // Workspaces are live; races are expected and retried by the next snapshot.
-    return;
-  }
-}
-
-/**
- * Streaming file collection: yields workspace files (metadata entry
- * first) one at a time so the one-shot path never holds the whole tree's
- * content in memory (issue #6). Same order, denylist, and byte budget
- * as the compat collectFiles drain below.
- */
-export async function* iterateCollectFiles(
-  root: string,
-  byteLimit: number,
-  workspaceId: string,
-  session?: Pick<SessionState, "id" | "segment" | "resumed">,
-): AsyncGenerator<CollectorFile> {
-  let used = 0;
-  const metadata = JSON.stringify({
-    workspace_id: workspaceId,
-    ...(session ? {
-      session_id: session.id,
-      session_segment: session.segment,
-      session_resumed: session.resumed,
-    } : {}),
-    root_name: root.split(sep).filter(Boolean).at(-1) ?? "workspace",
-    git: await gitMetadata(root),
-  });
-  yield { path: `${AGENT_DIR}/workspace.json`, content: metadata };
-  used += Buffer.byteLength(metadata);
-
-  const paths = (await listWorkspaceFiles(root)).sort(comparePaths);
-  for (const path of paths) {
-    if (used >= byteLimit) break;
-    for await (const file of iterateWorkspaceEntries(root, path)) {
-      const size = Buffer.byteLength(file.content ?? "");
-      if (used + size > byteLimit) continue;
-      yield file;
-      used += size;
-    }
-  }
-}
-
-/** Compat drain of iterateCollectFiles (tests + tooling). */
-export async function collectFiles(
-  root: string,
-  byteLimit: number,
-  workspaceId: string,
-  session?: Pick<SessionState, "id" | "segment" | "resumed">,
-): Promise<CollectorFile[]> {
-  const files: CollectorFile[] = [];
-  for await (const file of iterateCollectFiles(root, byteLimit, workspaceId, session)) {
-    files.push(file);
-  }
-  return files;
-}
-
-export function compressZstd(payload: Buffer): Promise<Buffer> {
-  return new Promise((resolvePromise, reject) => {
-    try {
-      const maybePromise = zstdCompressCb(payload, (error: unknown, result: Buffer) => {
-        if (error) reject(error);
-        else resolvePromise(result);
-      });
-      if (maybePromise && typeof (maybePromise as any).then === "function") {
-        (maybePromise as Promise<Buffer>).then(resolvePromise, reject);
-      }
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
-/** The uncompressed collect envelope (contract: schema_version 1).
- *  Additive metadata: client_version / client_platform when known and a
- *  sent_at timestamp — the backend ignores what it does not know. */
-export function buildEnvelopePayload(
-  state: Pick<SessionState, "id" | "segment" | "resumed"> & {
-    sequence?: number;
-    clientVersion?: string;
-    clientPlatform?: string;
-    /** Capture time override (change snapshots carry the time the
-     *  journal records were captured, not the time the queued upload
-     *  finally built the envelope). */
-    capturedAt?: string;
-  },
-  snapshotType: SnapshotType,
-  files: CollectorFile[],
-): Buffer {
-  return Buffer.from(JSON.stringify({
-    schema_version: 1,
-    session_id: state.id,
-    session_segment: state.segment,
-    session_resumed: state.resumed,
-    sequence: (state.sequence ?? 0) + 1,
-    snapshot_type: snapshotType,
-    ...(state.clientVersion ? { client_version: state.clientVersion } : {}),
-    ...(state.clientPlatform ? { client_platform: state.clientPlatform } : {}),
-    sent_at: new Date().toISOString(),
-    // Capture time for the backend's per-turn diff attribution (the
-    // desktop sends the same field; without it a CLI change snapshot
-    // cannot be pinned to the turn that was running).
-    captured_at: state.capturedAt ?? new Date().toISOString(),
-    files,
-  }));
-}
-
-export type EnvelopePart = {
-  files: CollectorFile[];
-  payload: Buffer;
-  compressed: Buffer;
-};
-
-/**
- * Deterministic part split for a full files array (compat drain of
- * iterateEnvelopeParts, used by the tests): sort files by path,
- * accumulate in order, keep each part <= maxCompressed compressed.
- */
-export async function buildEnvelopeParts(
-  state: Pick<SessionState, "id" | "segment" | "resumed"> & { sequence?: number },
-  snapshotType: SnapshotType,
-  files: CollectorFile[],
-  maxCompressed = MAX_PART_COMPRESSED_BYTES,
-  log?: (message: string, attributes?: Record<string, unknown>) => void,
-): Promise<EnvelopePart[]> {
-  // Slice any entry whose content exceeds MAX_SLICE_BYTES (manifest +
-  // ordered parts) BEFORE packing, so callers feeding raw file lists get
-  // the same deterministic slice layout as the tree walker.
-  const sorted = files
-    .flatMap((file) => buildFileEntries(file))
-    .sort((left, right) => comparePaths(left.path, right.path));
-  const parts: EnvelopePart[] = [];
-  for await (const part of iterateEnvelopeParts(state, snapshotType, sorted, maxCompressed, log)) {
-    parts.push(part);
-  }
-  return parts;
-}
-
-/**
- * Streaming packer for the one-shot path: yields compressed parts in
- * order so callers can upload-and-discard instead of holding the whole
- * workspace's parts (payload + compressed buffers) in memory (issue #6).
- * Same greedy algorithm as before: split at the compressed target, a
- * lone file may use the hard rail, lone-over-rail files are skipped
- * loudly. File content is never split across parts.
- */
-export async function* iterateEnvelopeParts(
-  state: Pick<SessionState, "id" | "segment" | "resumed"> & { sequence?: number },
-  snapshotType: SnapshotType,
-  sortedFiles: Iterable<CollectorFile> | AsyncIterable<CollectorFile>,
-  maxCompressed = MAX_PART_COMPRESSED_BYTES,
-  log?: (message: string, attributes?: Record<string, unknown>) => void,
-): AsyncGenerator<EnvelopePart> {
-  const hard = Math.max(maxCompressed, MAX_PART_COMPRESSED_HARD);
-  const measure = async (batch: CollectorFile[], partIndex: number): Promise<EnvelopePart> => {
-    const payload = buildEnvelopePayload({ ...state, sequence: (state.sequence ?? 0) + partIndex }, snapshotType, batch);
-    return { files: batch, payload, compressed: await compressZstd(payload) };
-  };
-  let partsYielded = 0;
-  let batch: CollectorFile[] = [];
-  const fit = async (batchToFit: CollectorFile[], partIndex: number) => {
-    let measured = await measure(batchToFit, partIndex);
-    const carry: CollectorFile[] = [];
-    // Split at the compressed target; a lone file may use the body
-    // headroom up to the hard rail, beyond which it is skipped loudly
-    // rather than split mid-content.
-    while (measured.compressed.length > maxCompressed && batchToFit.length > 1) {
-      carry.unshift(batchToFit.pop()!);
-      measured = await measure(batchToFit, partIndex);
-    }
-    if (measured.compressed.length > hard && batchToFit.length === 1) {
-      const lone = batchToFit.pop()!;
-      log?.("OmniRush file exceeds the upload limits and cannot be shipped as a single part; skipped", {
-        path: lone.path,
-        bytes: Buffer.byteLength(lone.content ?? ""),
-      });
-      return { measured: null, carry };
-    }
-    return { measured, carry };
-  };
-  for await (const file of sortedFiles) {
-    batch.push(file);
-    const partIndex = partsYielded;
-    const estimate = batch.reduce((total, f) => total + Buffer.byteLength(f.content), 0);
-    if (estimate < PART_UNCOMPRESSED_STEP) continue;
-    const { measured, carry } = await fit(batch, partIndex);
-    if (measured
-      && (measured.compressed.length >= PART_READY_COMPRESSED_BYTES || estimate >= PART_BATCH_UNCOMPRESSED_MAX)) {
-      partsYielded += 1;
-      yield measured;
-      batch = carry;
-    } else if (measured) {
-      batch = [...batch, ...carry];
-    } else {
-      batch = carry;
-    }
-  }
-  while (batch.length > 0) {
-    const { measured, carry } = await fit(batch, partsYielded);
-    if (measured) {
-      partsYielded += 1;
-      yield measured;
-    }
-    if (carry.length === 0) break;
-    batch = carry;
-  }
-}
-
-export class WorkspaceCollector {
-  /**
-   * Bounded first-chunk read of an error response body for diagnostics:
-   * at most 512 bytes, decoded and whitespace-collapsed. Never throws.
-   * Error bodies are small JSON from the manager; the bound exists so a
-   * pathological response cannot balloon a log line (or memory).
-   */
-  private static async errorBodySnippet(response: any): Promise<string> {
-    try {
-      const reader = response?.body?.getReader?.();
-      if (!reader) return "";
-      const { value } = await reader.read();
-      reader.cancel().catch(() => undefined);
-      if (!value) return "";
-      const text = Buffer.from(value).toString("utf8").replace(/\s+/g, " ").trim();
-      return text.length > 200 ? `${text.slice(0, 200)}…` : text;
-    } catch {
-      return "";
-    }
-  }
-
-  private readonly collectUrl: string | null;
-  private token: string;
-  private readonly fetcher: typeof fetch;
-  private readonly refresh?: CollectorOptions["refresh"];
-  private readonly uploader?: CollectorOptions["upload"];
-  private readonly log: NonNullable<CollectorOptions["log"]>;
-  private readonly ledgerPath: string | null;
-  private readonly stateDir: string | null;
-  private readonly agentDir: string | null;
-  private readonly identityProvider?: CollectorOptions["identityProvider"];
-  private readonly clientId?: string;
-  private identity: { userId: string | null } | null = null;
-  private identityTried = false;
-  private readonly ledgerReady: Promise<void>;
-  private ledger: SessionLedger = { version: 1, sessions: {} };
-  private ledgerWriteTail: Promise<void> = Promise.resolve();
-  private readonly sessions = new Map<string, SessionState>();
-  /** Gate for states built without one (direct uploadEnvelope callers,
-   *  tests) — per-session gates are created in startSession. */
-  private readonly defaultGate = new PriorityGate();
-  private readonly changeDebounceMs: number;
-  private readonly fallbackScanMs: number;
-  private readonly sessionBudgetBytes: number;
-  private readonly clientVersion: string;
-  private readonly clientPlatform: string;
-  private readonly linkedParentSession: string | null;
-  private readonly partCompressedBytes: number;
-  private readonly partCheckBytes: number;
-
-  constructor(options: CollectorOptions = {}) {
-    this.collectUrl = resolveCollectUrl(options.gatewayUrl ?? process.env.OMNIRUSH_GATEWAY_URL);
-    this.token = (options.accessToken ?? process.env.OMNIRUSH_ACCESS_TOKEN ?? "").trim();
-    this.fetcher = options.fetch ?? ((input: any, init?: any) => fetch(input, init));
-    this.refresh = options.refresh;
-    this.uploader = options.upload;
-    this.log = options.log ?? (() => undefined);
-    this.stateDir = options.stateDir ? resolve(options.stateDir) : null;
-    this.agentDir = options.agentDir ? resolve(options.agentDir) : null;
-    this.identityProvider = options.identityProvider;
-    this.clientId = options.clientId;
-    this.ledgerPath = options.stateDir ? join(resolve(options.stateDir), SESSION_LEDGER_FILE) : null;
-    this.ledgerReady = this.loadLedger();
-    this.changeDebounceMs = options.changeDebounceMs ?? CHANGE_DEBOUNCE_MS;
-    this.fallbackScanMs = options.fallbackScanMs ?? FALLBACK_SCAN_MS;
-    this.sessionBudgetBytes = Math.max(1024, options.sessionBudgetBytes ?? MAX_SESSION_BYTES);
-    this.clientVersion = options.clientVersion ?? detectClientVersion();
-    this.clientPlatform = options.clientPlatform ?? detectClientPlatform();
-    this.linkedParentSession = (options.linkedParentSession ?? "").trim() || null;
-    this.partCompressedBytes = Math.min(
-      Math.max(1024, options.partCompressedBytes ?? MAX_PART_COMPRESSED_BYTES),
-      MAX_PART_COMPRESSED_HARD,
-    );
-    this.partCheckBytes = Math.max(1024, options.partCheckBytes ?? PART_UNCOMPRESSED_STEP);
-  }
-
-  private async loadLedger(): Promise<void> {
-    this.ledger = await readSessionLedger(this.ledgerPath);
-  }
-
-  private async saveLedger(): Promise<void> {
-    if (!this.ledgerPath) return;
-    await this.ledgerReady;
-    const entries = Object.entries(this.ledger.sessions)
-      .sort(([, left], [, right]) => right.lastSeenAt.localeCompare(left.lastSeenAt))
-      .slice(0, MAX_SESSION_LEDGER_ENTRIES);
-    this.ledger.sessions = Object.fromEntries(entries);
-    const snapshot = JSON.stringify(this.ledger);
-    this.ledgerWriteTail = this.ledgerWriteTail
-      .catch(() => undefined)
-      .then(async () => {
-        await mkdir(dirname(this.ledgerPath!), { recursive: true, mode: 0o700 });
-        await writeFile(this.ledgerPath!, snapshot, { encoding: "utf8", mode: 0o600 });
-      });
-    await this.ledgerWriteTail;
-  }
-
-  /** The state fields every envelope builder needs, plus the additive
-   *  client metadata. `sent_at`/`captured_at` are stamped by
-   *  buildEnvelopePayload at build time. */
-  private sequenceState(
-    state: SessionState,
-    capturedAt?: string,
-  ): {
-    id: string;
-    segment: number;
-    resumed: boolean;
-    sequence: number;
-    clientVersion?: string;
-    clientPlatform?: string;
-    capturedAt?: string;
-  } {
-    return {
-      id: state.id,
-      segment: state.segment,
-      resumed: state.resumed,
-      sequence: state.sequence,
-      ...(this.clientVersion ? { clientVersion: this.clientVersion } : {}),
-      ...(this.clientPlatform ? { clientPlatform: this.clientPlatform } : {}),
-      // A change part is pinned to the capture time of its OLDEST
-      // journal record: the upload may queue behind the baseline, but
-      // the turn attribution must reflect when the edit was seen.
-      ...(capturedAt ? { capturedAt } : {}),
-    };
-  }
-
-  private async prepareSession(state: SessionState): Promise<void> {
-    await this.ledgerReady;
-    const previous = this.ledger.sessions[state.id];
-    state.segment = (previous?.segment ?? 0) + 1;
-    state.sequence = previous?.nextSequence ?? 0;
-    state.sentBytes = previous?.sentBytes ?? 0;
-    state.lastMessageId = previous?.lastMessageId;
-    state.baselineUploaded = previous?.baselineUploaded === true;
-    // An interrupted baseline resumes from its cursor; a completed one
-    // (or a fresh session) has none.
-    state.baselineResumePath =
-      previous && !state.baselineUploaded
-        ? typeof previous.baselineResumePath === "string"
-          ? previous.baselineResumePath
-          : null
-        : null;
-    state.resumed = Boolean(previous);
-    if (previous?.traces && typeof previous.traces === "object") {
-      state.transcripts = { ...previous.traces };
-    }
-    if (state.resumed) {
-      state.trace.push({
-        at: new Date().toISOString(),
-        type: "session.resumed",
-        data: { session_segment: state.segment, previous_segment: previous?.segment ?? null },
-      });
-    }
-    this.ledger.sessions[state.id] = {
-      segment: state.segment,
-      nextSequence: state.sequence,
-      sentBytes: state.sentBytes,
-      ...(state.lastMessageId ? { lastMessageId: state.lastMessageId } : {}),
-      ...(state.baselineUploaded ? { baselineUploaded: true } : {}),
-      ...(state.baselineResumePath ? { baselineResumePath: state.baselineResumePath } : {}),
-      lastSeenAt: new Date().toISOString(),
-    };
-    await this.saveLedger();
-  }
-
-  private async persistSession(state: SessionState): Promise<void> {
-    await this.ledgerReady;
-    this.ledger.sessions[state.id] = {
-      segment: state.segment,
-      nextSequence: state.sequence,
-      sentBytes: state.sentBytes,
-      ...(state.lastMessageId ? { lastMessageId: state.lastMessageId } : {}),
-      ...(state.baselineUploaded ? { baselineUploaded: true } : {}),
-      ...(state.baselineResumePath ? { baselineResumePath: state.baselineResumePath } : {}),
-      ...(Object.keys(state.transcripts).length > 0 ? { traces: state.transcripts } : {}),
-      lastSeenAt: new Date().toISOString(),
-    };
-    await this.saveLedger();
-  }
-
-  async sessionCheckpoint(sessionId: string): Promise<{ resumed: boolean; segment?: number; lastMessageId?: string }> {
-    const state = this.sessions.get(sessionId);
-    if (!state) return { resumed: false };
-    await state.ready;
-    return { resumed: state.resumed, segment: state.segment, lastMessageId: state.lastMessageId };
-  }
-
-  async setSessionCheckpoint(sessionId: string, messageId: string): Promise<void> {
-    const state = this.sessions.get(sessionId);
-    if (!state || state.finished) return;
-    await state.ready;
-    state.lastMessageId = messageId;
-    await this.persistSession(state);
-  }
-
-  get enabled(): boolean {
-    return Boolean(this.uploader || (this.collectUrl && this.token));
-  }
-
-  startSession(sessionId: string, workspaceId: string, root: string): void {
-    if (!this.enabled || this.sessions.has(sessionId) || !/^[A-Za-z0-9._:-]{8,128}$/.test(sessionId)) return;
-    const state: SessionState = {
-      id: sessionId,
-      root,
-      workspaceId,
-      sentBytes: 0,
-      segment: 1,
-      sequence: 0,
-      resumed: false,
-      lastSignature: "",
-      started: false,
-      finished: false,
-      budgetExhausted: false,
-      baselineUploaded: false,
-      baselineResumePath: null,
-      changeTimer: null,
-      scanTimer: null,
-      knownStats: new Map(),
-      scanning: false,
-      baselineSeeded: false,
-      knownPaths: new Set(),
-      trace: [],
-      journalPath: this.stateDir ? join(resolve(this.stateDir), `journal-${sessionId}.ndjson`) : null,
-      journalAckOffset: 0,
-      journalAppendedBytes: 0,
-      journalAppendTail: Promise.resolve(),
-      journalUploadEof: null,
-      journalCaptureStopped: false,
-      journalLastByPath: new Map(),
-      transcripts: {},
-      changeCaptureTail: Promise.resolve(),
-      ready: Promise.resolve(),
-      tail: Promise.resolve(),
-      traceTail: Promise.resolve(),
-      tracePending: 0,
-      traceDrain: Promise.resolve(),
-      resolveTraceDrain: () => undefined,
-      gate: new PriorityGate(),
-    };
-    state.ready = this.prepareSession(state);
-    this.sessions.set(sessionId, state);
-    if (this.linkedParentSession) {
-      // Child of a live parent session: the parent owns the workspace
-      // collection (baseline/changes/end). This collector only traces.
-      state.started = true;
-      return;
-    }
-    this.enqueue(state, async () => {
-      await state.ready;
-      const baselinePaths = await listWorkspaceFiles(root);
-      state.knownPaths = new Set(baselinePaths);
-      state.lastSignature = await workspaceSignature(root);
-      // Seed the per-path stat snapshot so the scan loop only captures
-      // files that change AFTER the start snapshot.
-      for (const relPath of baselinePaths) {
-        try {
-          const stats = await lstat(resolve(root, relPath));
-          state.knownStats.set(relPath, { mtimeMs: stats.mtimeMs, size: stats.size });
-        } catch {
-          /* raced away — the next scan re-checks */
-        }
-      }
-      state.baselineSeeded = true;
-      if (state.resumed && state.baselineUploaded) {
-        // Resume of a session whose start baseline already shipped: do
-        // NOT re-upload the full tree. A restart-heavy session would
-        // otherwise re-burn the entire baseline (and starve traces) on
-        // every restart — observed live as 846 start snapshots /
-        // multiple GB for one session. Changes + the end snapshot cover
-        // the deltas; a FAILED baseline (flag unset) still retries here.
-        state.started = true;
-        return;
-      }
-      await this.uploadWorkspace(state, "start");
-      state.baselineUploaded = true;
-      state.baselineResumePath = null;
-      await this.persistSession(state);
-      state.started = true;
-    });
-    // Change detection: signature scan (unref'd, self-serializing). No
-    // fs.watch anywhere — its recursive handle keeps the event loop
-    // alive even after close()/unref(), hanging every session at exit.
-    state.scanTimer = setInterval(() => {
-      void this.scanForChanges(state).catch(() => undefined);
-    }, this.fallbackScanMs);
-    state.scanTimer.unref?.();
-  }
-
-  /**
-   * Periodic change detection: cheap signature check first; on a real
-   * change, lstat-diff every path against knownStats and capture exactly
-   * the new/changed/deleted files into the on-disk journal.
-   */
-  private async scanForChanges(state: SessionState): Promise<void> {
-    if (state.scanning || state.finished || state.budgetExhausted) return;
-    if (!state.baselineSeeded) return;
-    state.scanning = true;
-    try {
-      const signature = await workspaceSignature(state.root);
-      if (!signature || signature === state.lastSignature) return;
-      const paths = (await listWorkspaceFiles(state.root)).sort(comparePaths);
-      const seen = new Set<string>();
-      for (const relPath of paths) {
-        seen.add(relPath);
-        let stats;
-        try {
-          stats = await lstat(resolve(state.root, relPath));
-        } catch {
-          continue;
-        }
-        if (isCollectorPathDenied(relPath)) continue;
-        const known = state.knownStats.get(relPath);
-        if (known && known.mtimeMs === stats.mtimeMs && known.size === stats.size) continue;
-        state.knownStats.set(relPath, { mtimeMs: stats.mtimeMs, size: stats.size });
-        await this.captureChangedPath(state, relPath, { force: true });
-      }
-      // Deletions: paths we knew about that vanished.
-      for (const [relPath] of state.knownStats) {
-        if (!seen.has(relPath)) {
-          state.knownStats.delete(relPath);
-          await this.captureChangedPath(state, relPath, { force: true });
-        }
-      }
-      state.lastSignature = signature;
-      this.scheduleChange(state);
-    } finally {
-      state.scanning = false;
-    }
-  }
-
-  recordTrace(sessionId: string, type: string, data?: unknown): void {
-    const state = this.sessions.get(sessionId);
-    if (!state || state.finished || state.budgetExhausted) return;
-    state.trace.push({ at: new Date().toISOString(), type, ...(data === undefined ? {} : { data }) });
-    if (state.trace.length >= TRACE_RELIEF_EVENTS) {
-      // Memory relief, NOT truncation: the whole batch is uploaded.
-      const batch = state.trace.splice(0);
-      this.enqueueTrace(state, async () => {
-        await state.ready;
-        await this.uploadTrace(state, batch);
-      });
-    }
-  }
-
-  finishSession(sessionId: string, finalTrace?: unknown): void {
-    const state = this.sessions.get(sessionId);
-    if (!state || state.finished) return;
-    const pendingTrace = state.trace.splice(0);
-    if (finalTrace !== undefined) {
-      pendingTrace.push({ at: new Date().toISOString(), type: "session.completed", data: finalTrace });
-    }
-    state.finished = true;
-    if (state.changeTimer) clearTimeout(state.changeTimer);
-    if (state.scanTimer) clearInterval(state.scanTimer);
-    // Final trace rides the PRIORITY lane: an in-flight baseline part
-    // finishes first, then the trace ships — never behind the tail of a
-    // multi-part tree upload.
-    this.enqueueTrace(state, async () => {
-      await state.ready;
-      if (state.trace.length > 0) pendingTrace.push(...state.trace.splice(0));
-      await this.uploadTrace(state, pendingTrace);
-    });
-    this.enqueue(state, async () => {
-      await state.ready;
-      await state.changeCaptureTail;
-      await this.teardownJournal(state); // ship unacked change records, then unlink
-      // The end snapshot yields to pending trace work (yieldToTrace in
-      // the packer), so the final trace lands first.
-      if (!this.linkedParentSession) {
-        // A linked child ships no end snapshot: the parent session's
-        // collection covers the workspace tree.
-        await this.uploadWorkspace(state, "end");
-      }
-      this.sessions.delete(sessionId);
-    });
-  }
-
-  flushTrace(sessionId: string, finalTrace?: unknown): void {
-    const state = this.sessions.get(sessionId);
-    if (!state || state.finished) return;
-    const pendingTrace = state.trace.splice(0);
-    if (finalTrace !== undefined) pendingTrace.push({ at: new Date().toISOString(), type: "turn.completed", data: finalTrace });
-    if (pendingTrace.length === 0) return;
-    // Per-turn flush: the complete trace artifact (events + transcript
-    // messages-so-far) ships on the priority lane, ahead of any queued
-    // baseline parts.
-    this.enqueueTrace(state, async () => {
-      await state.ready;
-      if (state.trace.length > 0) pendingTrace.push(...state.trace.splice(0));
-      await this.uploadTrace(state, pendingTrace);
-    });
-  }
-
-  async stop(): Promise<void> {
-    for (const sessionId of [...this.sessions.keys()]) this.finishSession(sessionId);
-    await Promise.allSettled(
-      [...this.sessions.values()].flatMap((state) => [state.tail, state.traceTail]),
-    );
-  }
-
-  /**
-   * Queue trace work on the priority lane and mark it pending: the
-   * background lane's `yieldToTrace` waits for `tracePending` to drain
-   * before starting another baseline part, so trace work enqueued while
-   * a baseline part was in flight goes next.
-   */
-  private enqueueTrace(state: SessionState, operation: () => Promise<void>): void {
-    if (state.tracePending === 0) {
-      let resolveDrain!: () => void;
-      state.traceDrain = new Promise<void>((resolvePromise) => {
-        resolveDrain = resolvePromise;
-      });
-      state.resolveTraceDrain = () => resolveDrain();
-    }
-    state.tracePending += 1;
-    state.traceTail = state.traceTail
-      .then(operation)
-      .catch((error: unknown) => {
-        this.log("warn", "OmniRush collection operation failed", {
-          sessionId: state.id,
-          error: error instanceof Error ? error.message : "unknown",
-        });
-      })
-      .finally(() => {
-        state.tracePending -= 1;
-        if (state.tracePending === 0) state.resolveTraceDrain();
-      });
-  }
-
-  /** Wait until no trace work is queued or running (re-arming safe). */
-  private async yieldToTrace(state: SessionState): Promise<void> {
-    while (state.tracePending > 0) {
-      await state.traceDrain;
-    }
-  }
-
-  private stopWatching(state: SessionState): void {
-    if (state.changeTimer) {
-      clearTimeout(state.changeTimer);
-      state.changeTimer = null;
-    }
-    if (state.scanTimer) {
-      clearInterval(state.scanTimer);
-      state.scanTimer = null;
-    }
-  }
-
-  private exhaustSessionBudget(state: SessionState): void {
-    if (state.budgetExhausted) return;
-    state.budgetExhausted = true;
-    this.stopWatching(state);
-    this.log("warn", "OmniRush session budget exhausted — collection stopped for this session", {
-      sessionId: state.id,
-      budgetBytes: this.sessionBudgetBytes,
-      sentBytes: state.sentBytes,
-    });
-  }
-
-  /** Run the debounced change-snapshot upload immediately. */
-  private flushChangeSnapshot(state: SessionState): void {
-    if (state.finished || state.budgetExhausted) return;
-    if (state.changeTimer) {
-      clearTimeout(state.changeTimer);
-      state.changeTimer = null;
-    }
-    this.enqueue(state, async () => {
-      if (state.budgetExhausted || state.finished) return;
-      // The JOURNAL is what holds unshipped change records: a scan
-      // captures edits and advances lastSignature in the same breath,
-      // so by the time this debounced flush runs (it can queue behind a
-      // long multi-part baseline) the workspace signature often equals
-      // lastSignature again and a signature-only guard would skip
-      // forever, stranding the journal until session end. Ship whenever
-      // unacked journal records exist; the signature is only the
-      // trigger for captures that have not been journalled yet.
-      const unackedJournal = state.journalAppendedBytes > state.journalAckOffset;
-      const signature = await workspaceSignature(state.root);
-      if (!unackedJournal && (!signature || signature === state.lastSignature)) return;
-      state.lastSignature = signature;
-      await this.uploadWorkspace(state, "change");
-    });
-  }
-
-  private scheduleChange(state: SessionState): void {
-    if (state.finished || state.budgetExhausted) return;
-    if (state.changeTimer) clearTimeout(state.changeTimer);
-    state.changeTimer = setTimeout(() => {
-      state.changeTimer = null;
-      this.flushChangeSnapshot(state);
-    }, this.changeDebounceMs);
-    state.changeTimer.unref?.();
-  }
-
-  private async captureChangedPath(
-    state: SessionState,
-    filename: string,
-    options?: { force?: boolean },
-  ): Promise<void> {
-    const absolute = resolve(state.root, filename);
-    const path = portablePath(state.root, absolute);
-    if (!path || path.startsWith("../") || isCollectorPathDenied(path)) return;
-    const records: ChangeJournalEntry[] = [];
-    let entry: ChangeJournalEntry;
-    try {
-      const file = await lstat(absolute);
-      state.knownPaths.add(path);
-      if (file.isSymbolicLink()) {
-        // Symlink record: the target as text content with the symlink
-        // encoding — replay recreates the actual link from it.
-        const target = await readlink(absolute);
-        entry = {
-          path,
-          at: new Date().toISOString(),
-          status: "present",
-          content: target,
-          encoding: "symlink",
-        };
-      } else if (!file.isFile()) {
-        return;
-      } else {
-        const at = new Date().toISOString();
-        const mode = file.mode & 0o777;
-        const modeField = mode ? { mode: mode.toString(8) } : {};
-        // STREAMED capture: each chunk becomes a journal record the
-        // moment it exists — a big file is never held in memory whole
-        // (issue #6). One record per <= MAX_SLICE_BYTES slice; slice
-        // metadata rides the records only when reassembly is needed.
-        let sliceCount = 0;
-        for await (const chunk of iterateContentChunks(absolute, file.size)) {
-          for (const content of sliceString(chunk.content)) {
-            sliceCount += 1;
-            records.push({
-              path,
-              at,
-              status: "present",
-              content,
-              ...(chunk.encoding ? { encoding: chunk.encoding } : {}),
-              ...modeField,
-            });
-          }
-        }
-        if (sliceCount > 1) {
-          records.forEach((record, index) => {
-            record.slice = {
-              index,
-              total: sliceCount,
-              bytes: Buffer.byteLength(record.content ?? ""),
-              sha256: sha256Hex(record.content ?? ""),
-            };
-          });
-        }
-        if (sliceCount === 1) {
-          entry = records.pop()!;
-        } else {
-          await this.appendJournalRecords(state, records);
-          return;
-        }
-      }
-    } catch (error) {
-      // Only a real disappearance is a deletion. Any other lstat failure
-      // (EPERM/EBUSY/... under heavy watcher load) must not fabricate a
-      // deleted record for a file that still exists — the fallback scan
-      // and the end snapshot re-check those paths.
-      if ((error as any)?.code !== "ENOENT") return;
-      // Only paths the baseline (or a captured change) saw can be
-      // deleted inside the workspace; FSEvents sibling/parent leaks
-      // reference foreign paths that must not fabricate deletions.
-      if (!state.knownPaths.has(path)) return;
-      entry = { path, at: new Date().toISOString(), status: "deleted" };
-    }
-    // Consecutive-duplicate suppression: macOS FSEvents can deliver a
-    // late event for a path that was also captured directly, and an
-    // identical re-capture adds upload fat without a state change. The
-    // replay result is identical either way. The last signature per
-    // path lives in a tiny in-memory map (path strings only — content
-    // is already on disk in the journal).
-    const journalSignature = (record: ChangeJournalEntry) =>
-      JSON.stringify([record.status, record.content, record.encoding, record.mode]);
-    const pendingRecords = [entry, ...records];
-    const accepted: ChangeJournalEntry[] = [];
-    for (const record of pendingRecords) {
-      const signature = journalSignature(record);
-      if (state.journalLastByPath.get(record.path) === signature) continue;
-      state.journalLastByPath.set(record.path, signature);
-      accepted.push(record);
-    }
-    await this.appendJournalRecords(state, accepted);
-  }
-
-  /**
-   * APPEND records to the on-disk journal (ndjson — one JSON record per
-   * line, 0600). Returns immediately when the capture hit the soft disk
-   * cap (a backend down for a very long time must stop CAPTURING loudly
-   * rather than fill the disk or RAM — the end snapshot still ships the
-   * final tree). Serialized through the per-session append chain.
-   */
-  private appendJournalRecords(state: SessionState, records: ChangeJournalEntry[]): Promise<void> {
-    if (!state.journalPath || records.length === 0) return Promise.resolve();
-    if (state.journalCaptureStopped) return Promise.resolve();
-    const unacked = state.journalAppendedBytes - state.journalAckOffset;
-    const capMb = Number(process.env.OMNIRUSH_JOURNAL_DISK_CAP_MB);
-    const capBytes = Number.isFinite(capMb) && capMb > 0 ? capMb * 1024 * 1024 : JOURNAL_DISK_CAP_BYTES;
-    if (unacked > capBytes) {
-      state.journalCaptureStopped = true;
-      this.log("warn", "OmniRush change journal hit the disk cap — change capture stopped for this session", {
-        sessionId: state.id,
-        capBytes: capBytes,
-        unackedBytes: unacked,
-      });
-      state.trace.push({
-        at: new Date().toISOString(),
-        type: "journal.capture_stopped",
-        data: { cap_bytes: capBytes, unacked_bytes: unacked },
-      });
-      return Promise.resolve();
-    }
-    const lines = records.map((record) => JSON.stringify(record) + "\n").join("");
-    const bytes = Buffer.byteLength(lines);
-    state.journalAppendTail = state.journalAppendTail
-      .catch(() => undefined)
-      .then(async () => {
-        const { appendFile, mkdir } = await import("node:fs/promises");
-        await mkdir(dirname(state.journalPath!), { recursive: true, mode: 0o700 });
-        await appendFile(state.journalPath!, lines, { encoding: "utf8", mode: 0o600 });
-        state.journalAppendedBytes += bytes;
-      });
-    return state.journalAppendTail;
-  }
-
-  /**
-   * Stream the journal's unacked records (from journalAckOffset to the
-   * upload-start EOF) as parsed entries, each tagged with its raw line
-   * bytes via a NON-enumerable property so the changes.json sidecar
-   * serialization never sees it. Records appended while the upload runs
-   * land beyond the read window and simply ship with the next snapshot.
-   */
-  private async *readJournalRecords(state: SessionState): AsyncGenerator<ChangeJournalEntry> {
-    if (!state.journalPath || state.journalAckOffset >= state.journalUploadEof) return;
-    const { createReadStream } = await import("node:fs");
-    const readline = await import("node:readline");
-    const stream = createReadStream(state.journalPath, {
-      start: state.journalAckOffset,
-      end: state.journalUploadEof! - 1,
-      encoding: "utf8",
-    });
-    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    for await (const line of rl) {
-      if (!line.trim()) continue;
-      try {
-        const record = JSON.parse(line) as ChangeJournalEntry;
-        Object.defineProperty(record, RAW_BYTES_FIELD, {
-          value: Buffer.byteLength(line) + 1,
-          enumerable: false,
-          configurable: true,
-        });
-        yield record;
-      } catch {
-        this.log("warn", "OmniRush journal line was unreadable — skipped", { sessionId: state.id });
-      }
-    }
-  }
-
-  /**
-   * Upload the journal's unacked records as change snapshots, then
-   * compact: everything acked is removed from the file; records appended
-   * during the upload (past journalUploadEof) survive untouched.
-   */
-  private async uploadChangeJournal(state: SessionState): Promise<void> {
-    if (!state.journalPath) return;
-    let fileSize = 0;
-    try {
-      fileSize = (await lstat(state.journalPath)).size;
-    } catch {
-      return; // no journal yet — nothing captured
-    }
-    if (fileSize <= state.journalAckOffset) return;
-    const ackStart = state.journalAckOffset;
-    state.journalUploadEof = fileSize;
-    try {
-      await this.uploadChangeParts(state, this.readJournalRecords(state), {
-        onAck: (batch) => {
-          for (const record of batch) {
-            const raw = (record as Record<symbol, unknown>)[RAW_BYTES_FIELD];
-            if (typeof raw === "number") state.journalAckOffset += raw;
-          }
-        },
-      });
-    } finally {
-      state.journalUploadEof = null;
-    }
-    if (state.journalAckOffset <= ackStart) return; // nothing acked — keep everything
-    await this.compactJournal(state, state.journalAckOffset);
-    state.journalAckOffset = 0;
-  }
-
-  /** Rewrite the journal without its first `dropBytes` bytes. */
-  private async compactJournal(state: SessionState, dropBytes: number): Promise<void> {
-    if (!state.journalPath) return;
-    const { createReadStream, createWriteStream } = await import("node:fs");
-    const { rename } = await import("node:fs/promises");
-    const tmpPath = `${state.journalPath}.compact`;
-    await new Promise<void>((resolvePromise, rejectPromise) => {
-      const input = createReadStream(state.journalPath!, { start: dropBytes, encoding: "utf8" });
-      const output = createWriteStream(tmpPath, { encoding: "utf8", mode: 0o600 });
-      input.on("error", rejectPromise);
-      output.on("error", rejectPromise);
-      output.on("finish", () => resolvePromise());
-      input.pipe(output);
-    });
-    await rename(tmpPath, state.journalPath);
-  }
-
-  /** Upload unacked journal records (best effort) and remove the file. */
-  private async teardownJournal(state: SessionState): Promise<void> {
-    try {
-      await this.uploadChangeJournal(state);
-    } catch {
-      /* best effort — the end snapshot still ships the final tree */
-    }
-    if (state.journalPath) {
-      const { rm } = await import("node:fs/promises");
-      await rm(state.journalPath, { force: true }).catch(() => undefined);
-    }
-  }
-
-  private enqueue(state: SessionState, operation: () => Promise<void>): void {
-    state.tail = state.tail.then(operation).catch((error: unknown) => {
-      this.log("warn", "OmniRush collection operation failed", {
-        sessionId: state.id,
-        error: error instanceof Error ? error.message : "unknown",
-      });
-    });
-  }
-
-  private async uploadWorkspace(state: SessionState, type: "start" | "change" | "end"): Promise<void> {
-    if (state.budgetExhausted) return;
-    if (type === "change") {
-      // Change snapshots carry ONLY the touched files — streamed from
-      // the on-disk journal, acked per part, then compacted. Never a
-      // full re-enumeration of the tree, never held in memory.
-      await this.uploadChangeJournal(state);
-    } else {
-      await this.uploadTreeParts(state, type);
-    }
-    state.lastSignature = await workspaceSignature(state.root);
-  }
-
-  private async workspaceMetadataFile(state: SessionState): Promise<CollectorFile> {
-    return {
-      path: `${AGENT_DIR}/workspace.json`,
-      content: JSON.stringify({
-        workspace_id: state.workspaceId,
-        session_id: state.id,
-        session_segment: state.segment,
-        session_resumed: state.resumed,
-        root_name: state.root.split(sep).filter(Boolean).at(-1) ?? "workspace",
-        git: await gitMetadata(state.root),
-      }),
-    };
-  }
-
-  /** Full-tree snapshot ("start" | "end"), streamed into ordered parts.
-   *  A start snapshot resumed after an interruption skips the paths the
-   *  previous run already shipped (`baselineResumePath` cursor — the
-   *  first unacked part onward); the end snapshot always ships whole. */
-  private async uploadTreeParts(state: SessionState, snapshotType: "start" | "end"): Promise<void> {
-    const paths = (await listWorkspaceFiles(state.root)).sort(comparePaths);
-    const metadata = await this.workspaceMetadataFile(state);
-    let metadataSent = false;
-    const resumeFrom = snapshotType === "start" ? state.baselineResumePath : null;
-    const measure = async (batch: CollectorFile[]) => {
-      const files = metadataSent ? batch : [metadata, ...batch];
-      const payload = buildEnvelopePayload(this.sequenceState(state), snapshotType, files);
-      return { files, payload, compressed: await compressZstd(payload) };
-    };
-    await this.packAndUpload(state, snapshotType, this.iterTreeFiles(state, paths, resumeFrom), {
-      sizeOf: (file) => Buffer.byteLength(file.content ?? "") + file.path.length + 64,
-      measure,
-      upload: async (measured) => {
-        const ok = await this.uploadEnvelope(state, snapshotType, measured.files, measured);
-        if (ok) {
-          metadataSent = true;
-          if (snapshotType === "start") {
-            // Advance the resume cursor to the last path of the acked
-            // part, so an interrupted run resumes at the first
-            // unacked part instead of re-burning the prefix.
-            const lastPath = measured.files[measured.files.length - 1]?.path;
-            if (typeof lastPath === "string") {
-              state.baselineResumePath = lastPath;
-              await this.persistSession(state).catch(() => undefined);
-            }
-          }
-        }
-        return ok;
-      },
-      drop: (file) => {
-        this.log("warn", "OmniRush file exceeds the upload rail and cannot be shipped as a single part; skipped", {
-          sessionId: state.id,
-          path: file.path,
-          bytes: Buffer.byteLength(file.content ?? ""),
-        });
-        state.trace.push({
-          at: new Date().toISOString(),
-          type: "file.unshippable",
-          data: { path: file.path, bytes: Buffer.byteLength(file.content ?? "") },
-        });
-      },
-    }, { yieldToTraceLane: true });
-  }
-
-  private async *iterTreeFiles(
-    state: SessionState,
-    paths: string[],
-    resumeFrom?: string | null,
-  ): AsyncGenerator<CollectorFile> {
-    // The cursor can name a slice or manifest virtual path
-    // (`<path>.__agent_partN`, `<path>.__agent_manifest.json`) when the
-    // acked part ended mid-file. Comparing a virtual cursor against the
-    // real path list would never match and `path <= cursor` would
-    // swallow the whole base file (silent data loss on resume), so
-    // paths before the cursor's base file are skipped outright and the
-    // base file's own entries are filtered against the cursor.
-    const cursor = resumeFrom ?? null;
-    const cursorBase = cursor
-      ? cursor.replace(/\.__agent(?:_part\d+|_manifest\.json)$/, "")
-      : null;
-    for (const path of paths) {
-      if (state.budgetExhausted) return;
-      if (cursorBase) {
-        const order = comparePaths(path, cursorBase);
-        if (order < 0) continue;
-        if (order === 0) {
-          for await (const entry of iterateWorkspaceEntries(state.root, path)) {
-            if (entry.path && comparePaths(entry.path, cursor!) <= 0) continue;
-            yield entry;
-          }
-          continue;
-        }
-      }
-      yield* iterateWorkspaceEntries(state.root, path);
-    }
-  }
-
-  /**
-   * Change snapshot: ordered journal slices. Each part carries the
-   * touched files for its slice (deduped last-wins, sorted by path) plus
-   * the __agent__/changes.json sidecar holding the slice's ordered
-   * records — replaying start + sidecars in sequence order reproduces the
-   * end tree.
-   */
-  private async uploadChangeParts(
-    state: SessionState,
-    units: Iterable<ChangeJournalEntry> | AsyncIterable<ChangeJournalEntry>,
-    opts: { onAck?: (batch: ChangeJournalEntry[]) => void } = {},
-  ): Promise<ChangeJournalEntry[][]> {
-    const uploadedSlices: ChangeJournalEntry[][] = [];
-    const filesForSlice = (entries: ChangeJournalEntry[]): CollectorFile[] => {
-      const lastByPath = new Map<string, CollectorFile>();
-      const slicedByPath = new Map<string, ChangeJournalEntry[]>();
-      for (const entry of entries) {
-        if (entry.status !== "present") continue;
-        if (entry.slice) {
-          const group = slicedByPath.get(entry.path) ?? [];
-          group.push(entry);
-          slicedByPath.set(entry.path, group);
-        } else if (entry.content !== undefined) {
-          lastByPath.set(entry.path, {
-            path: entry.path,
-            content: entry.content,
-            ...(entry.encoding ? { encoding: entry.encoding } : {}),
-            ...(entry.mode ? { mode: entry.mode } : {}),
-          });
-        }
-      }
-      const files = [...lastByPath.values()];
-      for (const [logicalPath, records] of slicedByPath) {
-        records.sort((left, right) => (left.slice?.index ?? 0) - (right.slice?.index ?? 0));
-        const encoding = records.find((record) => record.encoding)?.encoding;
-        const mode = records.find((record) => record.mode)?.mode;
-        for (const record of records) {
-          files.push({
-            path: slicePartPath(logicalPath, record.slice!.index),
-            content: record.content,
-            ...(encoding ? { encoding } : {}),
-          });
-        }
-        files.push({
-          path: sliceManifestPath(logicalPath),
-          content: JSON.stringify(sliceManifest(
-            {
-              path: logicalPath,
-              ...(encoding ? { encoding } : {}),
-              ...(mode ? { mode } : {}),
-            },
-            records.map((record) => ({
-              index: record.slice!.index,
-              bytes: record.slice!.bytes,
-              sha256: record.slice!.sha256,
-            })),
-            records[0].slice!.total,
-          )),
-        });
-      }
-      files.sort((left, right) => comparePaths(left.path, right.path));
-      files.push({
-        path: `${AGENT_DIR}/changes.json`,
-        content: JSON.stringify({ schema_version: 1, session_id: state.id, entries }),
-      });
-      return files;
-    };
-    const bySequence = (capturedAt?: string) => this.sequenceState(state, capturedAt);
-    await this.packAndUpload(state, "change", units, {
-      sizeOf: (entry) =>
-        Buffer.byteLength(entry.content ?? "") + entry.path.length + 96,
-      measure: async (batch) => {
-        const files = filesForSlice(batch);
-        const capturedAt = batch.find((entry) => typeof entry.at === "string")?.at;
-        const payload = buildEnvelopePayload(bySequence(capturedAt), "change", files);
-        return { files, payload, compressed: await compressZstd(payload) };
-      },
-      upload: async (measured, batch) => {
-        const ok = await this.uploadEnvelope(state, "change", measured.files, measured);
-        if (ok) {
-          uploadedSlices.push(batch);
-          opts.onAck?.(batch);
-        }
-        return ok;
-      },
-      drop: (entry) => {
-        this.log("warn", "OmniRush change record exceeds the upload limits and cannot be shipped; skipped", {
-          sessionId: state.id,
-          path: entry.path,
-          bytes: Buffer.byteLength(entry.content ?? ""),
-        });
-        state.trace.push({
-          at: new Date().toISOString(),
-          type: "file.unshippable",
-          data: { path: entry.path, reason: "change_record_over_limit" },
-        });
-      },
-    }, { checkBytes: PART_SIDECAR_PLAIN_MAX, flushPlainBytes: PART_SIDECAR_PLAIN_MAX, yieldToTraceLane: true });
-    return uploadedSlices;
-  }
-
-  /**
-   * Streaming packer shared by tree and change uploads: accumulate units
-   * in order, compress-check every partCheckBytes of uncompressed growth,
-   * flush parts targeting partCompressedBytes, and respect the hard rail
-   * (a lone unit over the rail is skipped via hooks.drop — never split).
-   * fit() mutates the batch it is given: the returned `measured` always
-   * corresponds to the (mutated) batch passed to hooks.upload, and popped
-   * units come back as `carry` to lead the next part. hooks.upload must
-   * persist sequence bookkeeping via uploadEnvelope.
-   *
-   * `yieldToTraceLane` (baseline/change/end packs): before each part
-   * upload, wait while trace work is pending or running — a trace part
-   * then never queues behind more than the one baseline part already in
-   * flight. Trace packs must NOT set it (they ARE the priority lane).
-   */
-  private async packAndUpload<U>(
-    state: SessionState,
-    snapshotType: SnapshotType,
-    units: Iterable<U> | AsyncIterable<U>,
-    hooks: {
-      sizeOf: (unit: U) => number;
-      measure: (batch: U[]) => Promise<{ files: CollectorFile[]; payload: Buffer; compressed: Buffer }>;
-      upload: (measured: { files: CollectorFile[]; payload: Buffer; compressed: Buffer }, batch: U[]) => Promise<boolean>;
-      drop?: (unit: U) => void;
-    },
-    opts: { checkBytes?: number; flushPlainBytes?: number; yieldToTraceLane?: boolean } = {},
-  ): Promise<void> {
-    const checkBytes = Math.max(1024, opts.checkBytes ?? this.partCheckBytes);
-    const flushPlainBytes = Math.max(checkBytes, opts.flushPlainBytes ?? PART_BATCH_UNCOMPRESSED_MAX);
-    const hard = MAX_PART_COMPRESSED_HARD;
-    const fit = async (batch: U[]) => {
-      let measured = await hooks.measure(batch);
-      const carry: U[] = [];
-      // Multi-file parts split at the compressed target. A lone unit
-      // (e.g. one slice entry) may use the body headroom up to the hard
-      // rail; beyond that it is dropped loudly rather than split
-      // mid-content.
-      while (measured.compressed.length > this.partCompressedBytes && batch.length > 1) {
-        carry.unshift(batch.pop()!);
-        measured = await hooks.measure(batch);
-      }
-      if (measured.compressed.length > hard && batch.length === 1) {
-        const lone = batch.pop()!;
-        hooks.drop?.(lone);
-        return { measured: batch.length > 0 ? await hooks.measure(batch) : null, carry };
-      }
-      return { measured, carry };
-    };
-
-    let batch: U[] = [];
-    let batchBytes = 0;
-    let nextCheck = checkBytes;
-    const resetBatch = (unitsToKeep: U[]) => {
-      batch = unitsToKeep;
-      batchBytes = batch.reduce((total, unit) => total + hooks.sizeOf(unit), 0);
-      nextCheck = batchBytes + checkBytes;
-    };
-    const shouldFlush = (measured: { compressed: Buffer }) =>
-      measured.compressed.length >= PART_READY_COMPRESSED_BYTES || batchBytes >= flushPlainBytes;
-
-    for await (const unit of units as AsyncIterable<U>) {
-      if (state.budgetExhausted) return;
-      batch.push(unit);
-      batchBytes += hooks.sizeOf(unit);
-      if (batchBytes < nextCheck) continue;
-      const { measured, carry } = await fit(batch);
-      if (measured && shouldFlush(measured)) {
-        if (opts.yieldToTraceLane) await this.yieldToTrace(state);
-        if (!(await hooks.upload(measured, batch))) return;
-        resetBatch(carry);
-      } else if (measured) {
-        // Under the flush thresholds — keep accumulating (carry is empty
-        // here: popping only happens above the flush levels).
-        batch = [...batch, ...carry];
-        nextCheck = batchBytes + checkBytes;
-      } else {
-        resetBatch(carry);
-      }
-    }
-    while (batch.length > 0 && !state.budgetExhausted) {
-      const { measured, carry } = await fit(batch);
-      if (measured) {
-        if (opts.yieldToTraceLane) await this.yieldToTrace(state);
-        if (!(await hooks.upload(measured, batch))) return;
-      }
-      if (carry.length === 0) break;
-      batch = carry;
-      batchBytes = batch.reduce((total, unit) => total + hooks.sizeOf(unit), 0);
-    }
-  }
-
-  /** Chunked trace upload: event subsets per part, ordered by sequence. */
-  private async uploadTrace(state: SessionState, traceEvents: TraceEvent[]): Promise<void> {
-    if (state.budgetExhausted || traceEvents.length === 0) {
-      // No lifecycle events this round — transcript artifacts may still
-      // be due (new or changed session files).
-      await this.uploadSessionTranscripts(state);
-      return;
-    }
-    const remaining = this.sessionBudgetBytes - state.sentBytes;
-    if (remaining <= 1024) {
-      this.exhaustSessionBudget(state);
-      return;
-    }
-    // Budget wall: truncate (loudly, trace_truncated=true) only here.
-    const selected = selectTraceEvents(traceEvents, remaining - 1024);
-    const meta = {
-      truncated: selected.truncated,
-      dropped: selected.droppedCount,
-    };
-    if (selected.truncated) {
-      this.log("warn", "OmniRush trace hit the session budget wall; older events dropped", {
-        sessionId: state.id,
-        droppedEventCount: selected.droppedCount,
-      });
-    }
-    let partIndex = 0;
-    const bySequence = () => this.sequenceState(state);
-    await this.packAndUpload(state, "trace", selected.events, {
-      sizeOf: (event) => Buffer.byteLength(JSON.stringify(event)) + 32,
-      measure: async (batch) => {
-        const content = JSON.stringify({
-          schema_version: 1,
-          schema: AGENT_TRACE_SCHEMA,
-          session_id: state.id,
-          session_segment: state.segment,
-          session_resumed: state.resumed,
-          trace_truncated: meta.truncated,
-          dropped_event_count: meta.dropped,
-          trace_part: { index: partIndex },
-          events: batch,
-        });
-        const files = [{ path: `${AGENT_DIR}/trace.json`, content }];
-        const payload = buildEnvelopePayload(bySequence(), "trace", files);
-        return { files, payload, compressed: await compressZstd(payload) };
-      },
-      upload: async (measured) => {
-        const ok = await this.uploadEnvelope(state, "trace", measured.files, measured);
-        if (ok) partIndex += 1;
-        return ok;
-      },
-      drop: (event) => {
-        this.log("warn", "OmniRush trace event exceeds the upload limits; skipped", {
-          sessionId: state.id,
-          type: event.type,
-          bytes: Buffer.byteLength(JSON.stringify(event)),
-        });
-      },
-    }, { checkBytes: PART_SIDECAR_PLAIN_MAX, flushPlainBytes: PART_SIDECAR_PLAIN_MAX });
-    // Full-conversation transcript artifacts (trace format spec) ride
-    // the same trace uploads — lifecycle events stay in trace.json, the
-    // transcripts land as __agent__/traces/<session>.jsonl.
-    await this.uploadSessionTranscripts(state);
-  }
-
-  /**
-   * The pi agent writes the FULL session transcript as JSONL under
-   * <agentDir>/sessions/<cwd-slug>/<ts>_<session-id>.jsonl — one file
-   * per run, SUBAGENTS as their own files in the same dir. Every file
-   * (new or changed since the last capture) becomes its own trace
-   * artifact (header + full conversation, redacted) uploaded as
-   * __agent__/traces/<session>.jsonl and linked to this session via
-   * parent_session_id. Detection state rides the persistent ledger.
-   */
-  private async uploadSessionTranscripts(state: SessionState): Promise<void> {
-    if (!this.agentDir || !state.id) return;
-    const { readdir, stat } = await import("node:fs/promises");
-    const sessionsRoot = join(this.agentDir, "sessions");
-    let sessionDir: string | null = null;
-    try {
-      for (const entry of await readdir(sessionsRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        const dir = join(sessionsRoot, entry.name);
-        const files = await readdir(dir).catch(() => [] as string[]);
-        if (files.some((f) => f.endsWith(`_${state.id}.jsonl`))) {
-          sessionDir = dir;
-          break;
-        }
-      }
-    } catch {
-      return; // no sessions dir — nothing to capture
-    }
-    if (!sessionDir) return;
-
-    const artifacts: Array<{ path: string; content: string; fileKey: string; size: number; mtimeMs: number }> = [];
-    let files: string[] = [];
-    try {
-      files = (await readdir(sessionDir)).filter((f) => f.endsWith(".jsonl")).sort();
-    } catch {
-      return;
-    }
-    for (const file of files) {
-      const filePath = join(sessionDir, file);
-      let size = 0;
-      let mtimeMs = 0;
-      try {
-        const stats = await stat(filePath);
-        size = stats.size;
-        mtimeMs = stats.mtimeMs;
-      } catch {
-        continue;
-      }
-      const known = state.transcripts[filePath];
-      if (known && known.size === size && known.mtimeMs === mtimeMs) continue;
-      let text: string;
-      try {
-        const { readFile } = await import("node:fs/promises");
-        text = await readFile(filePath, "utf8");
-      } catch {
-        continue;
-      }
-      const parsed = parsePiSession(text);
-      const artifactSessionId = parsed.sessionId ?? file.replace(/^\d{4}-\d{2}-\d{2}T[\d-]+Z_/, "").replace(/\.jsonl$/, "");
-      if (!artifactSessionId || parsed.messageRecords.length === 0) {
-        // Still mark empty/HEAD-only files seen so they are not retried.
-        state.transcripts[filePath] = { size, mtimeMs };
-        continue;
-      }
-      if (this.linkedParentSession && artifactSessionId !== state.id) {
-        // Linked child: the parent's collector already ships the other
-        // session files in this directory (linked to the parent) — a
-        // second copy from the child adds nothing.
-        continue;
-      }
-      const identity = await this.resolveIdentity();
-      const artifact = buildTraceArtifact({
-        sessionId: artifactSessionId,
-        parentSessionId: this.linkedParentSession ?? state.id,
-        userId: identity?.userId ?? null,
-        clientId: this.clientId ?? null,
-        agentId: "omnirush-cli",
-        parsed,
-        redact: (value) => redactCollectorText(value).text,
-      });
-      artifacts.push({
-        path: `${AGENT_DIR}/traces/${artifactSessionId}.jsonl`,
-        content: JSON.stringify(artifact),
-        fileKey: filePath,
-        size,
-        mtimeMs,
-      });
-    }
-    if (artifacts.length === 0) {
-      await this.persistSession(state).catch(() => undefined);
-      return;
-    }
-    const bySequence = () => this.sequenceState(state);
-    await this.packAndUpload(state, "trace", artifacts, {
-      sizeOf: (artifact) => Buffer.byteLength(artifact.content) + artifact.path.length + 64,
-      measure: async (batch) => {
-        const payload = buildEnvelopePayload(bySequence(), "trace", batch);
-        return { files: batch, payload, compressed: await compressZstd(payload) };
-      },
-      upload: async (measured) => {
-        // Mark a transcript seen only after its part is accepted — an
-        // ack-before-success let a single 503 permanently drop the
-        // transcript from every later flush (the ledger said captured).
-        const ok = await this.uploadEnvelope(state, "trace", measured.files, measured);
-        if (ok) {
-          for (const artifact of measured.files) {
-            state.transcripts[artifact.fileKey] = {
-              size: artifact.size,
-              mtimeMs: artifact.mtimeMs,
-            };
-          }
-        }
-        return ok;
-      },
-      drop: (artifact) => {
-        this.log("warn", "OmniRush transcript artifact exceeds the upload limits; skipped", {
-          sessionId: state.id,
-          path: artifact.path,
-          bytes: Buffer.byteLength(artifact.content),
-        });
-        state.transcripts[artifact.fileKey] = {
-          size: artifact.size,
-          mtimeMs: artifact.mtimeMs,
-        };
-      },
-    }, { checkBytes: PART_SIDECAR_PLAIN_MAX, flushPlainBytes: PART_SIDECAR_PLAIN_MAX });
-    await this.persistSession(state).catch(() => undefined);
-  }
-
-  /** Best-effort /device/me identity, fetched once per collector. */
-  private async resolveIdentity(): Promise<{ userId: string | null } | null> {
-    if (this.identityTried) return this.identity;
-    this.identityTried = true;
-    if (!this.identityProvider) return null;
-    try {
-      this.identity = await this.identityProvider();
-    } catch {
-      this.identity = null;
-    }
-    return this.identity;
-  }
-
-  /**
-   * Send one envelope (one part). `precompressed` skips the rebuild +
-   * recompress when the caller already measured this exact batch.
-   */
-  private async uploadEnvelope(
-    state: SessionState,
-    snapshotType: SnapshotType,
-    files: CollectorFile[],
-    precompressed?: { payload: Buffer; compressed: Buffer },
-  ): Promise<boolean> {
-    if (!this.collectUrl && !this.uploader) return false;
-    if (state.budgetExhausted) return false;
-    if (files.length === 0) {
-      // A zero-file part carries no information and would loop forever
-      // if a caller ever fed a packer an empty unit stream.
-      this.log("warn", "OmniRush refused to upload an empty envelope", {
-        sessionId: state.id,
-        snapshotType,
-      });
-      return false;
-    }
-    const payload = precompressed?.payload ?? buildEnvelopePayload(state, snapshotType, files);
-    if (state.sentBytes + payload.length > this.sessionBudgetBytes) {
-      this.exhaustSessionBudget(state);
-      return false;
-    }
-    const compressed = precompressed?.compressed ?? await compressZstd(payload);
-    if (compressed.length > MAX_PART_COMPRESSED_HARD) {
-      this.log("warn", "OmniRush part exceeded the backend body rail; not sent", {
-        sessionId: state.id,
-        snapshotType,
-        compressedBytes: compressed.length,
-        railBytes: MAX_PART_COMPRESSED_HARD,
-      });
-      return false;
-    }
-    // Two lanes (session tail + trace tail) funnel every envelope send
-    // through this gate. Trace sends acquire with priority, so after the
-    // part currently in flight finishes, the trace part goes next; the
-    // gate is held per ATTEMPT, so a retrying baseline part cannot pin
-    // the transport either.
-    const priority = snapshotType === "trace";
-    const gate = state.gate ?? this.defaultGate;
-    const sendOnce = async () => {
-      await gate.acquire(priority);
-      try {
-        return await (this.uploader
-          ? this.uploader(state.id, compressed)
-          : this.fetcher(this.collectUrl!, {
-              method: "POST",
-              headers: {
-                Authorization: `Bearer ${this.token}`,
-                "Content-Type": "application/zstd",
-                "X-Omnirush-Session-ID": state.id,
-              },
-              body: compressed.buffer.slice(compressed.byteOffset, compressed.byteOffset + compressed.byteLength) as ArrayBuffer,
-              signal: AbortSignal.timeout(120_000),
-            }));
-      } finally {
-        gate.release();
-      }
-    };
-    // Shared retry layer: 429/5xx/network ride out backend deploys with
-    // exponential backoff + jitter. 401 stays a protocol answer handled
-    // inline (single-flight refresh, retry exactly once).
-    const outcome = await withRetries(
-      async () => {
-        let response = await sendOnce();
-        if (response.status === 401 && this.refresh) {
-          // Broker pattern: single-flight refresh, retry exactly once.
-          const rotated = await this.refresh(this.token).catch(() => null);
-          if (rotated) {
-            this.token = rotated;
-            response = await sendOnce();
-          }
-        }
-        return {
-          response,
-          retryAfterSec: Number(response?.headers?.get?.("retry-after")) || undefined,
-        };
-      },
-      {
-        attempts: retryAttempts(),
-        isRetryable: ({ response }) => isRetryableStatus(response?.status),
-        onRetry: ({ attempt, attempts, delayMs }) => {
-          this.log("warn", "OmniRush upload unavailable — retrying", {
-            sessionId: state.id,
-            snapshotType,
-            attempt: `${attempt + 1}/${attempts}`,
-            delayMs,
-          });
-        },
-      },
-    );
-    const response = outcome.result?.response;
-    if (response?.ok) {
-      // Drain/cancel the body so keep-alive sockets return to the pool —
-      // an unconsumed body keeps a ref'd socket and hangs process exit.
-      await response.body?.cancel().catch(() => undefined);
-    }
-    if (!response) {
-      // Every attempt failed at the network layer.
-      throw new Error(
-        `collector upload failed: network error after ${outcome.attempts} attempt${outcome.attempts === 1 ? "" : "s"}` +
-          ` — ${outcome.error?.message ?? "unknown"} [ref ${outcome.ref}]` +
-          ` (session ${state.id}, ${snapshotType}, sequence ${state.sequence + 1})`,
-      );
-    }
-    if (!response.ok) {
-      // Diagnosable from a tester's screenshot alone: status, context,
-      // and (bounded) the server's error body. A 401 here means the
-      // refresh-retry above also failed — the caller should re-login.
-      const snippet = await WorkspaceCollector.errorBodySnippet(response);
-      throw new Error(
-        `collector upload failed: HTTP ${response.status}` +
-          `${snippet ? ` — ${snippet}` : ""}` +
-          ` [ref ${outcome.ref}]` +
-          ` (session ${state.id}, ${snapshotType}, sequence ${state.sequence + 1})`,
-      );
-    }
-    state.sentBytes += payload.length;
-    state.sequence += 1;
-    await this.persistSession(state).catch((error: unknown) => {
-      this.log("warn", "OmniRush session ledger update failed", {
-        sessionId: state.id,
-        error: error instanceof Error ? error.message : "unknown",
-      });
-    });
-    this.log("info", "OmniRush collection artifact uploaded", {
-      sessionId: state.id,
-      snapshotType,
-      fileCount: files.length,
-      compressedBytes: compressed.length,
-      sequence: state.sequence,
-    });
-    return true;
-  }
-}