Problem
Large artifact and diagnostic collections are currently bounded by truncation. Agents can see that data was omitted but cannot retrieve later entries without clearing state or changing unrelated limits.
Split from #54 G3.
Contract
- Add an architecture decision defining cursor opacity, scope, ordering, expiry, mutation behavior, bounds, and error codes.
- Introduce one reusable pagination model for
artifacts list, console list, and network list.
- Support a bounded
--limit and opaque --cursor; reject unknown, malformed, expired, cross-command, cross-session, and tampered cursors.
- Keep ordering deterministic and prevent duplicates or skips for an unchanged collection.
- Bind diagnostic cursors to the session and command filters. Bind artifact cursors to the artifact store.
- Never encode filesystem paths, secrets, cookie or storage values, page-controlled text, or unbounded state into cursors.
- Keep every page below the 1 MiB frame and report
nextCursor, returned, total or available where it is truthful, and truncation or mutation state.
- Preserve safe backward compatibility for callers that omit pagination options.
Acceptance criteria
- All three list commands can traverse collections larger than one page.
- Stable collections produce complete, ordered, duplicate-free traversal.
- Collection mutation has an explicit tested contract and never silently returns misleading data.
- Cursor misuse fails closed with typed recovery guidance.
- Limits are validated consistently by CLI and protocol layers.
- Cursors and responses remain bounded and redact sensitive data.
- CLI, protocol schema, SDK generation, MCP, unit, and both-engine E2E coverage pass.
- Documentation explains cursor lifetime and restart behavior.
Problem
Large artifact and diagnostic collections are currently bounded by truncation. Agents can see that data was omitted but cannot retrieve later entries without clearing state or changing unrelated limits.
Split from #54 G3.
Contract
artifacts list,console list, andnetwork list.--limitand opaque--cursor; reject unknown, malformed, expired, cross-command, cross-session, and tampered cursors.nextCursor,returned,totaloravailablewhere it is truthful, and truncation or mutation state.Acceptance criteria