omnirush 0.5.3 → 0.5.4

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

@@ -47,7 +47,9 @@
 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";
@@ -124,6 +126,73 @@ export const TRACE_RELIEF_EVENTS = 2_000;
 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;
@@ -172,6 +241,12 @@ export type SessionLedgerRecord = {
    *  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. */
@@ -197,6 +272,9 @@ type SessionState = {
   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.
@@ -245,7 +323,22 @@ type SessionState = {
   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 = {
@@ -268,6 +361,17 @@ export type CollectorOptions = {
   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. */
@@ -814,9 +918,19 @@ export function compressZstd(payload: Buffer): Promise<Buffer> {
   });
 }
 
-/** The uncompressed collect envelope (contract: schema_version 1). */
+/** 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 },
+  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 {
@@ -827,6 +941,13 @@ export function buildEnvelopePayload(
     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,
   }));
 }
@@ -970,9 +1091,15 @@ export class WorkspaceCollector {
   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;
 
@@ -992,6 +1119,9 @@ export class WorkspaceCollector {
     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,
@@ -1020,6 +1150,35 @@ export class WorkspaceCollector {
     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];
@@ -1028,6 +1187,14 @@ export class WorkspaceCollector {
     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 };
@@ -1045,6 +1212,7 @@ export class WorkspaceCollector {
       sentBytes: state.sentBytes,
       ...(state.lastMessageId ? { lastMessageId: state.lastMessageId } : {}),
       ...(state.baselineUploaded ? { baselineUploaded: true } : {}),
+      ...(state.baselineResumePath ? { baselineResumePath: state.baselineResumePath } : {}),
       lastSeenAt: new Date().toISOString(),
     };
     await this.saveLedger();
@@ -1058,6 +1226,7 @@ export class WorkspaceCollector {
       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(),
     };
@@ -1098,6 +1267,7 @@ export class WorkspaceCollector {
       finished: false,
       budgetExhausted: false,
       baselineUploaded: false,
+      baselineResumePath: null,
       changeTimer: null,
       scanTimer: null,
       knownStats: new Map(),
@@ -1116,9 +1286,20 @@ export class WorkspaceCollector {
       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);
@@ -1147,6 +1328,8 @@ export class WorkspaceCollector {
       }
       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
@@ -1207,7 +1390,7 @@ export class WorkspaceCollector {
     if (state.trace.length >= TRACE_RELIEF_EVENTS) {
       // Memory relief, NOT truncation: the whole batch is uploaded.
       const batch = state.trace.splice(0);
-      this.enqueue(state, async () => {
+      this.enqueueTrace(state, async () => {
         await state.ready;
         await this.uploadTrace(state, batch);
       });
@@ -1218,17 +1401,31 @@ export class WorkspaceCollector {
     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);
-    this.enqueue(state, async () => {
+    // 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;
-      if (finalTrace !== undefined) pendingTrace.push({ at: new Date().toISOString(), type: "session.completed", data: finalTrace });
       await this.teardownJournal(state); // ship unacked change records, then unlink
-      await this.uploadTrace(state, pendingTrace);
-      await this.uploadWorkspace(state, "end");
+      // 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);
     });
   }
@@ -1239,7 +1436,10 @@ export class WorkspaceCollector {
     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;
-    this.enqueue(state, async () => {
+    // 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);
@@ -1248,7 +1448,45 @@ export class WorkspaceCollector {
 
   async stop(): Promise<void> {
     for (const sessionId of [...this.sessions.keys()]) this.finishSession(sessionId);
-    await Promise.allSettled([...this.sessions.values()].map((state) => state.tail));
+    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 {
@@ -1567,23 +1805,38 @@ export class WorkspaceCollector {
     };
   }
 
-  /** Full-tree snapshot ("start" | "end"), streamed into ordered parts. */
+  /** 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 bySequence = () => ({ id: state.id, segment: state.segment, resumed: state.resumed, sequence: state.sequence });
+    const resumeFrom = snapshotType === "start" ? state.baselineResumePath : null;
     const measure = async (batch: CollectorFile[]) => {
       const files = metadataSent ? batch : [metadata, ...batch];
-      const payload = buildEnvelopePayload(bySequence(), snapshotType, files);
+      const payload = buildEnvelopePayload(this.sequenceState(state), snapshotType, files);
       return { files, payload, compressed: await compressZstd(payload) };
     };
-    await this.packAndUpload(state, snapshotType, this.iterTreeFiles(state, paths), {
+    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 (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) => {
@@ -1598,12 +1851,17 @@ export class WorkspaceCollector {
           data: { path: file.path, bytes: Buffer.byteLength(file.content ?? "") },
         });
       },
-    });
+    }, { yieldToTraceLane: true });
   }
 
-  private async *iterTreeFiles(state: SessionState, paths: string[]): AsyncGenerator<CollectorFile> {
+  private async *iterTreeFiles(
+    state: SessionState,
+    paths: string[],
+    resumeFrom?: string | null,
+  ): AsyncGenerator<CollectorFile> {
     for (const path of paths) {
       if (state.budgetExhausted) return;
+      if (resumeFrom && comparePaths(path, resumeFrom) <= 0) continue;
       for await (const entry of iterateWorkspaceEntries(state.root, path)) {
         yield entry;
       }
@@ -1677,13 +1935,14 @@ export class WorkspaceCollector {
       });
       return files;
     };
-    const bySequence = () => ({ id: state.id, segment: state.segment, resumed: state.resumed, sequence: state.sequence });
+    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 payload = buildEnvelopePayload(bySequence(), "change", files);
+        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) => {
@@ -1706,7 +1965,7 @@ export class WorkspaceCollector {
           data: { path: entry.path, reason: "change_record_over_limit" },
         });
       },
-    }, { checkBytes: PART_SIDECAR_PLAIN_MAX, flushPlainBytes: PART_SIDECAR_PLAIN_MAX });
+    }, { checkBytes: PART_SIDECAR_PLAIN_MAX, flushPlainBytes: PART_SIDECAR_PLAIN_MAX, yieldToTraceLane: true });
     return uploadedSlices;
   }
 
@@ -1719,6 +1978,11 @@ export class WorkspaceCollector {
    * 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,
@@ -1730,7 +1994,7 @@ export class WorkspaceCollector {
       upload: (measured: { files: CollectorFile[]; payload: Buffer; compressed: Buffer }, batch: U[]) => Promise<boolean>;
       drop?: (unit: U) => void;
     },
-    opts: { checkBytes?: number; flushPlainBytes?: number } = {},
+    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);
@@ -1772,6 +2036,7 @@ export class WorkspaceCollector {
       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) {
@@ -1786,6 +2051,7 @@ export class WorkspaceCollector {
     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;
@@ -1820,7 +2086,7 @@ export class WorkspaceCollector {
       });
     }
     let partIndex = 0;
-    const bySequence = () => ({ id: state.id, segment: state.segment, resumed: state.resumed, sequence: state.sequence });
+    const bySequence = () => this.sequenceState(state);
     await this.packAndUpload(state, "trace", selected.events, {
       sizeOf: (event) => Buffer.byteLength(JSON.stringify(event)) + 32,
       measure: async (batch) => {
@@ -1921,10 +2187,16 @@ export class WorkspaceCollector {
         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: state.id,
+        parentSessionId: this.linkedParentSession ?? state.id,
         userId: identity?.userId ?? null,
         clientId: this.clientId ?? null,
         agentId: "omnirush-cli",
@@ -1944,7 +2216,7 @@ export class WorkspaceCollector {
       await this.persistSession(state).catch(() => undefined);
       return;
     }
-    const bySequence = () => ({ id: state.id, segment: state.segment, resumed: state.resumed, sequence: state.sequence });
+    const bySequence = () => this.sequenceState(state);
     await this.packAndUpload(state, "trace", artifacts, {
       sizeOf: (artifact) => Buffer.byteLength(artifact.content) + artifact.path.length + 64,
       measure: async (batch) => {
@@ -2012,30 +2284,44 @@ export class WorkspaceCollector {
       });
       return false;
     }
-    const send = () => 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),
-        });
+    // 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 send();
+        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 send();
+            response = await sendOnce();
           }
         }
         return {