fix(network): keep unnamed-request identities out of the response

`unnamedRequestIds` collected every unresolved task in the scan window and
was spread straight into the response, so `network dump 1` could answer
with thousands of task ids: an output whose size tracked the log rather
than the requested entry limit.

The identities exist to reconcile two scan windows, which is a step that
finishes before a dump is returned. Keep them there. `NetworkDump` carries
`unnamedRequests` as a count again, bounded by construction; the identities
ride `ScannedNetworkDump`, the internal widening that the reader and the
merge speak, and the Apple runtime projects them away with
`withoutScanIdentities` on the way out.

Reconciliation is unchanged: overlapping windows still collapse to one
request and disjoint windows still sum, because the merge still sees the
identities and recomputes the count from them.

Regression: five unnameable tasks against `maxEntries: 1` reports all five
and exposes no identity list.

Author: boorad

CHANGELOG.md

@@ -19,10 +19,10 @@
   was called" check read as a definite fail. Such a request is now reported against the origin its
   connection was opened for, with `pathUnavailable` set, its status, and its timing. A reused
   request whose connection was opened before the scanned window cannot be named at all; those are
-  listed in the dump's `unnamedRequestIds`, so an empty result still reports that traffic was
-  observed. Identities rather than a count, so the app-log and recovery windows reconcile to the
-  requests actually seen instead of double-counting overlapping traffic or under-reporting
-  disjoint traffic. The notes say absence of an endpoint does not prove it was not called.
+  counted in the dump's `unnamedRequests`, so an empty result still reports that traffic was
+  observed. The identities behind that count reconcile the app-log and recovery windows internally
+  — so overlapping traffic is not double-counted and disjoint traffic is not under-reported — but
+  the response carries only the count, which stays bounded however large the scan window was. The notes say absence of an endpoint does not prove it was not called.
 - Fixed: a URL logged as a delimited `url: <value>,` field no longer keeps the separator the log
   format put after it, so an entry's `url` compares equal to the endpoint under test. A bare URL
   elsewhere is left alone, since nothing there establishes that trailing punctuation is not part of

packages/capture-kit/src/index.ts

@@ -29,4 +29,9 @@ export {
   appLogSessionArtifactsMatch,
   assertAppLogSessionArtifacts,
 } from './app-log-session-artifacts.ts';
-export { mergeNetworkDumps, readRecentNetworkTrafficFromText } from './network-traffic.ts';
+export {
+  mergeNetworkDumps,
+  readRecentNetworkTrafficFromText,
+  withoutScanIdentities,
+  type ScannedNetworkDump,
+} from './network-traffic.ts';

packages/capture-kit/src/network-traffic.test.ts

@@ -65,7 +65,7 @@ test('keeps missing canonical app-log text distinct and merges recovery first',
     scannedLines: 0,
     matchedLines: 0,
     entries: [],
-    unnamedRequestIds: [],
+    unnamedRequests: 0,
     include: 'summary',
     limits: { maxEntries: 2, maxPayloadChars: 2048, maxScanLines: 100 },
   });
@@ -234,20 +234,20 @@ test('android dumps do not pay for CFNetwork correlation', () => {
     dump.entries.map((entry) => entry.url),
     ['http://localhost:3040/v4/messages/en_US'],
   );
-  assert.equal(dump.unnamedRequestIds?.length, 0);
+  assert.equal(dump.unnamedRequests, 0);
 });
 
 test('a reused request whose connection opened before the window is counted, not dropped', () => {
   const dump = iosDump([REUSED_SUMMARY]);
 
   assert.deepEqual(dump.entries, []);
-  assert.equal(dump.unnamedRequestIds?.length, 1);
+  assert.equal(dump.unnamedRequests, 1);
 });
 
 test('a resolved reused request is named, not counted as unnamed', () => {
   const dump = iosDump([CONNECTION_START, OPENING_SUMMARY, REUSED_SUMMARY]);
 
-  assert.equal(dump.unnamedRequestIds?.length, 0);
+  assert.equal(dump.unnamedRequests, 0);
   assert.equal(dump.entries.filter((entry) => entry.pathUnavailable).length, 1);
 });
 
@@ -268,7 +268,7 @@ test('a recycled connection number does not inherit the origin of a previous pro
     dump.entries.filter((entry) => entry.pathUnavailable),
     [],
   );
-  assert.equal(dump.unnamedRequestIds?.length, 1);
+  assert.equal(dump.unnamedRequests, 1);
 });
 
 test('a connection number is resolved within the process that opened it', () => {
@@ -291,7 +291,7 @@ test('a line with no readable process identity leaves its traffic unnamed', () =
     dump.entries.filter((entry) => entry.pathUnavailable),
     [],
   );
-  assert.equal(dump.unnamedRequestIds?.length, 1);
+  assert.equal(dump.unnamedRequests, 1);
 });
 
 test('a URL whose path ends in punctuation is not truncated into a different endpoint', () => {
@@ -320,7 +320,7 @@ test('two windows over disjoint unnamed traffic report both requests, not the la
 
   const merged = mergeNetworkDumps(recovery, appLog, 200);
 
-  assert.equal(merged.unnamedRequestIds?.length, 2);
+  assert.equal(merged.unnamedRequests, 2);
 });
 
 test('two windows over the same unnamed request report it once', () => {
@@ -329,18 +329,18 @@ test('two windows over the same unnamed request report it once', () => {
 
   const merged = mergeNetworkDumps(recovery, appLog, 200);
 
-  assert.equal(merged.unnamedRequestIds?.length, 2);
+  assert.equal(merged.unnamedRequests, 2);
 });
 
 test('a request one window named is not still counted as unnamed from the other', () => {
   const appLog = iosDump([REUSED_SUMMARY]);
   const recovery = iosDump([CONNECTION_START, REUSED_SUMMARY]);
 
-  assert.equal(appLog.unnamedRequestIds?.length, 1);
-  assert.equal(recovery.unnamedRequestIds?.length, 0);
+  assert.equal(appLog.unnamedRequests, 1);
+  assert.equal(recovery.unnamedRequests, 0);
 
   const merged = mergeNetworkDumps(recovery, appLog, 200);
 
-  assert.deepEqual(merged.unnamedRequestIds, []);
+  assert.equal(merged.unnamedRequests, 0);
   assert.equal(merged.entries.filter((entry) => entry.pathUnavailable).length, 1);
 });

packages/capture-kit/src/network-traffic.ts

@@ -41,11 +41,24 @@ type CfNetworkConnectionIndex = ReadonlyMap<
   readonly Readonly<{ lineIndex: number; origin: string }>[]
 >;
 
+/**
+ * A dump plus the identities behind its `unnamedRequests`. Reconciling two scan
+ * windows needs those identities; a caller returning a dump to its requester
+ * does not, and an unbounded list of them has no place in a response.
+ */
+export type ScannedNetworkDump = NetworkDump & Readonly<{ unnamedRequestIds?: readonly string[] }>;
+
+/** The public projection: identities dropped, their count kept. */
+export function withoutScanIdentities(dump: ScannedNetworkDump): NetworkDump {
+  const { unnamedRequestIds: _identities, ...rest } = dump;
+  return Object.freeze(rest);
+}
+
 export function mergeNetworkDumps(
-  primary: NetworkDump,
-  secondary: NetworkDump,
+  primary: ScannedNetworkDump,
+  secondary: ScannedNetworkDump,
   maxEntries = primary.limits.maxEntries,
-): NetworkDump {
+): ScannedNetworkDump {
   const entries = [...primary.entries];
   const seen = new Set(entries.map(networkEntryKey));
   for (const entry of secondary.entries) {
@@ -70,14 +83,15 @@ export function mergeNetworkDumps(
     ...primary,
     matchedLines: entries.length,
     entries: Object.freeze(entries),
+    unnamedRequests: unnamedRequestIds.length,
     unnamedRequestIds: Object.freeze(unnamedRequestIds),
   });
 }
 
 export function readRecentNetworkTrafficFromText(
   content: string,
   options: NetworkDumpParserOptions,
-): NetworkDump {
+): ScannedNetworkDump {
   const maxEntries = clampInt(options.maxEntries, 25, 1, 200);
   const include = options.include ?? 'summary';
   const maxPayloadChars = clampInt(options.maxPayloadChars, 2048, 64, 16_384);
@@ -90,7 +104,7 @@ export function readRecentNetworkTrafficFromText(
       scannedLines: 0,
       matchedLines: 0,
       entries: Object.freeze([]),
-      unnamedRequestIds: Object.freeze([]),
+      unnamedRequests: 0,
       include,
       limits: Object.freeze({ maxEntries, maxPayloadChars, maxScanLines }),
     });
@@ -102,6 +116,9 @@ export function readRecentNetworkTrafficFromText(
   const cfNetworkConnections = isAppleBackend(options.backend)
     ? indexCfNetworkConnections(lines)
     : undefined;
+  const unnamedRequestIds = cfNetworkConnections
+    ? collectUnnamedCfNetworkTasks(lines, cfNetworkConnections)
+    : [];
   for (let i = lines.length - 1; i >= 0 && entries.length < maxEntries; i -= 1) {
     if (!lines[i]?.trim()) continue;
     const parsed = parseNetworkLine(
@@ -121,9 +138,8 @@ export function readRecentNetworkTrafficFromText(
     scannedLines: lines.length,
     matchedLines: entries.length,
     entries: Object.freeze(entries),
-    unnamedRequestIds: Object.freeze(
-      cfNetworkConnections ? collectUnnamedCfNetworkTasks(lines, cfNetworkConnections) : [],
-    ),
+    unnamedRequests: unnamedRequestIds.length,
+    unnamedRequestIds: Object.freeze(unnamedRequestIds),
     include,
     limits: Object.freeze({ maxEntries, maxPayloadChars, maxScanLines }),
   });

packages/contracts/src/network-traffic.ts

@@ -21,13 +21,13 @@ export type NetworkDump = Readonly<{
   matchedLines: number;
   entries: readonly NetworkEntry[];
   /**
-   * Identities of requests the reader observed but could not name at all, so
-   * they are absent from `entries`: an empty dump with a non-empty list is a
-   * failed capture, not evidence that nothing was requested. Identities rather
-   * than a count, so two scan windows over overlapping traffic reconcile to the
-   * requests actually seen instead of double-counting or under-reporting them.
+   * How many requests the reader observed but could not name at all, so they
+   * are absent from `entries`: an empty dump with a non-zero count is a failed
+   * capture, not evidence that nothing was requested. A count rather than the
+   * identities behind it, so the response stays bounded however many lines the
+   * scan window held.
    */
-  unnamedRequestIds?: readonly string[];
+  unnamedRequests?: number;
   include: NonNullable<NetworkDumpParserOptions['include']>;
   limits: Readonly<{ maxEntries: number; maxPayloadChars: number; maxScanLines: number }>;
 }>;

packages/platform-apple/src/network/runtime.test.ts

@@ -250,7 +250,7 @@ test('a keep-alive request whose connection predates the window keeps the dump f
 
   if (result.source !== 'app-log') throw new Error('expected app-log result');
   expect(result.dump.entries).toEqual([]);
-  expect(result.dump.unnamedRequestIds).toHaveLength(1);
+  expect(result.dump.unnamedRequests).toBe(1);
   expect(result.notes).toEqual([
     expect.stringContaining('1 opened before this scan window'),
     expect.stringContaining('No HTTP(s) entries were found'),
@@ -273,7 +273,7 @@ test('simulator recovery keeps traffic it saw but could not name', async () => {
 
   if (result.source !== 'app-log') throw new Error('expected app-log result');
   expect(result.dump.entries).toEqual([]);
-  expect(result.dump.unnamedRequestIds).toHaveLength(1);
+  expect(result.dump.unnamedRequests).toBe(1);
   expect(result.notes).toEqual([
     expect.stringContaining('1 opened before this scan window'),
     expect.stringContaining('No HTTP(s) entries were found'),
@@ -295,10 +295,34 @@ test('recovery-only traffic that cannot be named is still reported, not called e
   );
 
   if (result.source !== 'app-log') throw new Error('expected app-log result');
-  expect(result.dump.unnamedRequestIds).toHaveLength(1);
+  expect(result.dump.unnamedRequests).toBe(1);
   expect(result.notes).toEqual([
     expect.stringContaining('1 opened before this scan window'),
     expect.stringContaining('No HTTP(s) entries were found'),
   ]);
   expect(result.notes.join(' ')).not.toContain('none looked like HTTP traffic');
 });
+
+test('a response bounded to one entry still reports every unnamed request, without their ids', async () => {
+  // Five reused tasks, none resolvable: far more than the requested entry limit.
+  const summaries = Array.from({ length: 5 }, (_, index) =>
+    REUSED_SUMMARY.replace('Task <2FAEF670>.<2>', `Task <2FAEF670>.<${index + 10}>`),
+  );
+  const result = await dumpAppleNetworkTraffic(
+    host({
+      text: `${summaries.join('\n')}\n`,
+      runSimctl: vi.fn(async () => ({ stdout: '', stderr: '', exitCode: 1 })),
+    }),
+    simulator,
+    input({ maxEntries: 1, appLogSnapshot: { state: 'active', startedAt: 1_000 } }),
+    new AbortController().signal,
+  );
+
+  if (result.source !== 'app-log') throw new Error('expected app-log result');
+  expect(result.dump.entries).toEqual([]);
+  expect(result.dump.unnamedRequests).toBe(5);
+  // The identities are a reconciliation detail and must not reach the response,
+  // where their number is bounded by the scan window rather than by maxEntries.
+  expect(result.dump).not.toHaveProperty('unnamedRequestIds');
+  expect(result.notes[0]).toContain('5 requests reused a keep-alive connection');
+});

packages/platform-apple/src/network/runtime.ts

@@ -1,7 +1,12 @@
 import type { NetworkDump } from '@agent-device/contracts/network-traffic';
 import type { NetworkDumpInput, NetworkDumpResult } from '@agent-device/contracts/network-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
-import { mergeNetworkDumps, readRecentNetworkTrafficFromText } from '@agent-device/capture-kit';
+import {
+  mergeNetworkDumps,
+  readRecentNetworkTrafficFromText,
+  withoutScanIdentities,
+  type ScannedNetworkDump,
+} from '@agent-device/capture-kit';
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { backendForAppleDevice } from '../logs/backend.ts';
 
@@ -28,7 +33,12 @@ export async function dumpAppleNetworkTraffic(
   appendLifecycleNote(notes, device, input);
   appendUnnamedRequestNote(notes, dump);
   if (dump.entries.length === 0) notes.push(noEntriesNote(device));
-  return Object.freeze({ source: 'app-log', backend, dump, notes: Object.freeze(notes) });
+  return Object.freeze({
+    source: 'app-log',
+    backend,
+    dump: withoutScanIdentities(dump),
+    notes: Object.freeze(notes),
+  });
 }
 
 /**
@@ -38,12 +48,12 @@ export async function dumpAppleNetworkTraffic(
  */
 function mergeRecoveredTraffic(
   notes: string[],
-  dump: NetworkDump,
-  recovery: { dump: NetworkDump; lineCount: number },
+  dump: ScannedNetworkDump,
+  recovery: { dump: ScannedNetworkDump; lineCount: number },
   maxEntries: number,
-): NetworkDump {
+): ScannedNetworkDump {
   const recovered = recovery.dump.entries.length;
-  if (recovered === 0 && (recovery.dump.unnamedRequestIds ?? []).length === 0) {
+  if (recovered === 0 && (recovery.dump.unnamedRequests ?? 0) === 0) {
     if (recovery.lineCount > 0) {
       notes.push(
         `Recovered ${recovery.lineCount} recent iOS simulator app log lines from simctl log show, but none looked like HTTP traffic. This app may not emit request URLs, status, or timing into Unified Logging for this repro window.`,
@@ -78,7 +88,7 @@ async function recoverSimulatorTraffic(
   input: NetworkDumpInput,
   appLogPath: string,
   signal: AbortSignal,
-): Promise<{ dump: NetworkDump; lineCount: number } | undefined> {
+): Promise<{ dump: ScannedNetworkDump; lineCount: number } | undefined> {
   const args = [
     ...(device.simulatorSetPath ? ['--set', device.simulatorSetPath] : []),
     'spawn',
@@ -139,7 +149,7 @@ function buildPredicate(appBundleId: string): string {
  */
 function appendUnnamedRequestNote(notes: string[], dump: NetworkDump): void {
   const againstOrigin = dump.entries.filter((entry) => entry.pathUnavailable).length;
-  const unresolved = (dump.unnamedRequestIds ?? []).length;
+  const unresolved = dump.unnamedRequests ?? 0;
   const observed = againstOrigin + unresolved;
   if (observed === 0) return;
   const parts = [

website/docs/docs/commands.md

@@ -991,7 +991,7 @@ agent-device network dump 25 --include headers --platform web # Browser requests
 - iOS simulator log capture now streams from inside the simulator with `simctl spawn <udid> log ...`, and `network dump` can recover recent simulator log history with `simctl log show` when the live app-log window is sparse.
 - iOS log capture still relies on Unified Logging signals (for example `os_log`); plain stdout/stderr output may be limited depending on app/runtime.
 - On iOS, `network dump` can return zero HTTP entries for real app activity when the app does not emit request metadata into Unified Logging. The response notes now distinguish between an empty repro window and a non-network app log window.
-- On iOS, CFNetwork logs a request URL only on the line that opens a connection, so a request that reused a keep-alive connection has no URL anywhere in the log. Those requests are reported against the origin their connection was opened for, with `pathUnavailable: true`, their status, and their timing; ones whose connection was opened before the scanned window are listed in `unnamedRequestIds` instead, since they cannot be named at all. Treat a missing endpoint in an iOS dump as unproven rather than as evidence it was not called.
+- On iOS, CFNetwork logs a request URL only on the line that opens a connection, so a request that reused a keep-alive connection has no URL anywhere in the log. Those requests are reported against the origin their connection was opened for, with `pathUnavailable: true`, their status, and their timing; ones whose connection was opened before the scanned window are counted in `unnamedRequests` instead, since they cannot be named at all. Treat a missing endpoint in an iOS dump as unproven rather than as evidence it was not called.
 - Retention knobs: set `AGENT_DEVICE_APP_LOG_MAX_BYTES` and `AGENT_DEVICE_APP_LOG_MAX_FILES` to override rotation limits.
 - Optional write-time redaction patterns: set `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS` to a comma-separated regex list.