panel: migrate scanner check-in polling to atomic POST /scan/consume

[thevladbog]

Summary

• Replaces agentClient.getLastScan() + clearLastScan() (the racy GET /scan/last + POST /scan/clear pair) with a single agentClient.consumeLastScan() calling the agent's atomic POST /scan/consume — closes the CodeRabbit-flagged race from panel PR Panel P4.1: check-in loop — idempotent check-in, station UI, launch ceremony #77, where a fast second physical scan arriving between a read and its later clear call was silently erased.
• Simplifies useScanInput.ts's scanner-mode poll: since the agent now clears atomically server-side, every non-empty poll response is guaranteed to be a scan the client has never seen before. Deletes the now-dead {code, time} dedup ref and the separate retry-the-clear-on-failure ref entirely — no client-side workaround needed anymore.
• No changes to agent/ (already shipped and merged to main separately — see docs/superpowers/plans/2026-07-18-agent-atomic-scan-consume.md) or to any consumer of useScanInput (StationPage.tsx, useCheckinFlow.ts untouched). Wedge and manual scan-input modes are unaffected.

Built via subagent-driven-development (3 tasks, each with an independent implementer + reviewer, plus a final whole-branch review — "Ready to merge: Yes", zero Critical/Important findings). One note from the review: the branch's commit list includes a "docs: agent atomic scan-consume implementation plan" housekeeping commit whose content is identical to what's already on main under a different hash (from earlier plan bookkeeping) — it's a no-op in the actual file diff below, not part of this change's real scope.

Test plan

• npm test -- --run — 1128/1128 panel tests passing
• npm run typecheck (tsc -b — the correct command for this project's solution-style tsconfig.json) — clean
• npx eslint . --max-warnings=0 — clean
• npm run build — succeeds
• Confirmed no live references to getLastScan/clearLastScan//scan/last//scan/clear remain in panel/src (only historical migration-note comments)
• Reviewer independently re-verified the agent's POST /scan/consume atomicity by reading agent/scan_buffer.go's Consume() directly, and confirmed the new MSW test mock genuinely self-clears after serving a response (mirroring the real agent) rather than passing "no double-emit" tests for the wrong reason

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added atomic scan consumption for handheld scanners, allowing scans to be read and cleared in a single operation.
  • Updated scanner polling to prevent duplicate scan entries and reduce the risk of missed scans.
  • Added the new scan-consumption endpoint to agent documentation.

• Bug Fixes

  • Improved scanner recovery when the agent is temporarily unavailable.
  • Prevented overlapping scan requests during polling.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 921a1c31-e473-4cb1-b076-5015aab7ee33

📥 Commits

Reviewing files that changed from the base of the PR and between d7d1ea5 and b9038d8.

📒 Files selected for processing (6)

• docs/superpowers/plans/2026-07-18-agent-atomic-scan-consume.md
• panel/src/features/checkin/ScanInput.test.tsx
• panel/src/features/checkin/useScanInput.test.tsx
• panel/src/features/checkin/useScanInput.ts
• panel/src/shared/agent/agentClient.test.ts
• panel/src/shared/agent/agentClient.ts

---

📝 Walkthrough

Walkthrough

The change defines and adopts an atomic POST /scan/consume flow. The panel client and scanner hook use it instead of separate read-and-clear requests, while tests and documentation are updated for the new contract.

Changes

Atomic scan consumption

Layer / File(s)	Summary
Agent buffer and route design docs/superpowers/plans/...	The plan defines a mutex-protected scan buffer, reusable routes, main wiring, and compatibility behavior for existing scan endpoints.
Endpoint documentation and verification docs/superpowers/plans/...	The plan documents /scan/consume, updates endpoint descriptions and README content, and lists verification commands.
Panel atomic client contract panel/src/shared/agent/agentClient.ts, panel/src/shared/agent/agentClient.test.ts	The client replaces separate read and clear methods with consumeLastScan, normalizes empty responses, and tests request and error handling.
Scanner polling integration and coverage panel/src/features/checkin/useScanInput.ts, panel/src/features/checkin/useScanInput.test.tsx, panel/src/features/checkin/ScanInput.test.tsx	Scanner polling consumes scans directly while retaining degraded-state and in-flight handling; tests cover emission, failures, recovery, concurrency, and manual mode.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant useScanInput
  participant agentClient
  participant Agent
  useScanInput->>agentClient: consumeLastScan()
  agentClient->>Agent: POST /scan/consume
  Agent-->>agentClient: ScanData or empty sentinel
  agentClient-->>useScanInput: Normalized scan data
  useScanInput-->>useScanInput: Emit code when present

Loading

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: panel scanner check-in polling now uses atomic POST /scan/consume.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch panel/scan-consume-migration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}