feat: add read_markers so the agent can see human markers

[ribdsp]

What

Adds a seventeenth WebMCP tool, read_markers, and updates every claim in the repo that said sixteen.

annotate gave the agent a way to write markers onto the timeline. There was no way to read one back
— not its own, and not the human's. ask_human_visual lands the human's answer on the timeline as a
marker precisely so it is evidence anyone can click; until now "anyone" excluded the agent. A session
resumed after a reload, or picked up by a second agent, started blind to the moments a person had
already pointed at.

Shape

read_markers({ from?, to? })
  -> { fromMs, toMs,
       markers: [{ id, atMs, label, severity, author, rejected? }],
       totalMatched, humanCount, agentCount, truncated, note? }

Copied in shape from read_network: the shared { from?, to? } window via optionalWindow, a
currentRecording() guard, a 40-entry budget with totalMatched counted before the cap, and the
rank-then-restore-chronological pattern. Read-only, no human gate, no new type — it reuses the frozen
Marker from types/domain.ts, which is untouched.

Three decisions worth flagging:

• Rejected markers come back flagged, not filtered. rejectMarker keeps them so undo works, and
  an agent that cannot see the rejection re-proposes what a human already dismissed. rejected is
  omitted rather than false when the marker stands, so it is not noise on every entry.
• The human's markers survive the cap first. The agent already holds the ids of everything it
  pinned itself, from annotate's replies.
• A loaded recording is still required. Answering "no markers" with nothing loaded would read as
  "the human marked nothing", which is a different and more misleading fact.

Registered last in the read group rather than first: it is the only read tool that answers a
question about the investigation rather than about the recording, and a model scanning for "read the
page" must not land on it.

Tests

Six new cases in read-search-errors.test.ts, in that file's existing style: the empty-window note,
both authors returned in timeline order regardless of insertion order, a rejected marker flagged, the
rejected field absent when the marker stands, markers outside the requested window excluded with
totalMatched scoped to the window, and the cap keeping the human's marker while staying
chronological. read_markers also joins READ_AND_SEARCH_TOOLS, so it is covered by the existing
no-recording and pre-mount assertions.

registry.test.ts moves from toHaveLength(16) to 17. That is the only assertion changed.

Doc sweep

docs/tools.md gains a full §17 entry and an at-a-glance row. Existing entries are not
renumbered: anchors #1–#10 and #12 are referenced from source comments, and the doc's numbering
already differs from allTools order. Every other "16"/"sixteen" tool-count claim updated across
README.md, CLAUDE.md, docs/architecture.md, next.config.mjs, webmcp.d.ts,
register-tools.ts, tool-surface.tsx, agent-lane.tsx, stage-empty-state.tsx and
webmcp-badge.tsx. CLAUDE.md's test count moves 303 -> 309. The "sixteen seconds" prose in bugbait
is a different fact and was left alone.

Verification

npx tsc --noEmit    exit 0
npx vitest run      25 files, 309 tests, all passing
npm run lint        0 errors, 8 pre-existing warnings, none from the new file

Not verifiable locally: the header pill reading WebMCP │ 17 against the live deploy, which needs a
browser with WebMCP.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
traces	Ready	Preview	Aug 31, 2026 8:29am