feat(poll): add persisted Drive and Docs polling

[steipete]

Closes #690.

Summary

• add gog drive changes poll with atomic persisted page-token state, optional file filtering, bounded iterations, and sequential batch hooks
• add gog docs comments poll with an inclusive-safe modified-time watermark, sequential per-comment hooks, and resolved-comment filtering
• emit NDJSON in JSON mode, keep hook output on stderr, and advance state only after output/hooks succeed
• document polling state, hook trust, retry semantics, generated command references, and examples
• fix drive changes list --all so terminal newStartPageToken is returned instead of followed as another page

Behavior decisions

• missing/empty Drive state starts from changes.startPageToken; missing/empty Docs state starts at the current time, avoiding existing-history replay
• hook payloads are JSON on stdin; Google content is never interpolated into the trusted local shell command
• hook/output failure retains the prior cursor, giving at-least-once delivery
• Docs state tracks IDs delivered at the inclusive timestamp watermark, preserving comments that share a modified time
• excluded resolved comments still advance the Docs watermark, avoiding repeated refetches

Verification

• make ci
• focused polling/API tests covering pagination termination, atomic state, mode 0600, filtering, NDJSON, deterministic hook order, inclusive timestamps, excluded resolved comments, hook retry, and cancellation
• autoreview: clean after fixing its resolved-comment cursor finding
• built binary dry-run smoke for both new command surfaces

A real Google smoke with clawdbot@gmail.com was attempted using the configured file keyring and --no-input. The account could not be unlocked because GOG_KEYRING_PASSWORD is unavailable in this shell. No GUI/keychain prompt was triggered. The local HTTP API tests exercise the real Drive client request/response path and hook/state behavior.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 11, 2026, 10:29 PM ET / 02:29 UTC.

Summary
Adds persisted Drive change and Docs comment polling commands with atomic cursor state, sequential JSON-on-stdin hooks, NDJSON output, documentation, focused tests, and corrected Drive terminal-token pagination.

Reproducibility: not applicable. as a bug reproduction; this feature has focused API-path tests and an exact-head live Google E2E report covering delivery, hooks, persistence, and duplicate suppression.

Review metrics: 3 noteworthy metrics.

• Change surface: 17 files, +1430/-32. The PR adds two commands, shared persistence and hook primitives, generated documentation, and focused tests.
• Poll coverage: 432 test lines added. Focused tests cover pagination termination, atomic state, permissions, filtering, output, hook order and retry, inclusive timestamps, resolved comments, and cancellation.
• Generated commands: 2 added; 631 total. Both new command surfaces are represented in schema-derived command documentation.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] Merging establishes a versioned local state-file format and an explicit unsandboxed operator shell-hook interface; these become user-facing compatibility and trust contracts that unit tests cannot fully settle.
• [P1] The related receiver PR at feat(drive): add secure changes push receiver #753 is stacked on these shared helpers, so later changes to the polling primitives may also affect that branch.

Maintainer options:

1. Accept the polling contract (recommended)
   Merge after required exact-head checks complete, consciously owning the versioned state format and trusted local shell-hook interface.
2. Pause for interface changes
   Hold the PR if maintainers want a different state-versioning, concurrency, or shell-execution policy before these public surfaces ship.

Next step before merge

• No automated repair is indicated; maintainers should accept or revise the new persistent-state and trusted-hook contracts and let required exact-head checks gate the merge.

Security
Cleared: The hook is explicitly operator controlled, Google payloads stay on stdin, state uses restrictive atomic writes, and the diff adds no dependency, workflow, permission, or supply-chain changes.

Review details

Best possible solution:

Ship the focused polling commands with their current atomic versioned state, at-least-once delivery, sequential stdin hooks, and explicit single-writer and trusted-command documentation once maintainers accept those interfaces and exact-head required checks complete.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction; this feature has focused API-path tests and an exact-head live Google E2E report covering delivery, hooks, persistence, and duplicate suppression.

Is this the best way to solve the issue?

Yes. The PR reuses established Drive and Docs API primitives and adds a narrow persistence and orchestration layer rather than creating a competing provider path; maintainer acceptance of the public state and hook contracts remains appropriate.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 3f653c724656.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The exact-head live Google E2E demonstrates Drive and Docs events, matching hook payloads, persisted version-1 state, and no repeated delivery or hook execution on subsequent polls.

Label justifications:

• P3: This is an optional automation feature rather than an urgent regression or broken existing workflow.
• merge-risk: 🚨 other: Merging establishes persistent state and unsandboxed operator-hook contracts whose long-term compatibility and trust implications are not fully resolved by green CI.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The exact-head live Google E2E demonstrates Drive and Docs events, matching hook payloads, persisted version-1 state, and no repeated delivery or hook execution on subsequent polls.
• proof: sufficient: Contributor real behavior proof is sufficient. The exact-head live Google E2E demonstrates Drive and Docs events, matching hook payloads, persisted version-1 state, and no repeated delivery or hook execution on subsequent polls.

Evidence reviewed

Acceptance criteria:

• [P1] Confirm all required checks complete successfully on b1e5d49.
• [P1] Confirm maintainers accept state version 1, single-writer semantics, at-least-once delivery, and unsandboxed trusted shell hooks as public contracts.

What I checked:

• Exact-head live behavior proof: The collaborator reports a live Google E2E on head b1e5d49 covering Drive and Docs delivery, matching hook JSON, no repeated output or hook execution on later polls, version-1 state validation, and disposable document cleanup. (b1e5d49d33fc)
• Atomic restricted state: The shared helper creates the state directory with mode 0700 and uses the repository atomic writer with mode 0600; state readers reject malformed JSON and command-specific readers reject unsupported versions or missing cursors. (internal/cmd/poll_helpers.go:121, b1e5d49d33fc)
• Retry-safe Drive cursor: Drive output and its sequential hook complete before the next page token is persisted, so either failure retains the previous cursor for at-least-once retry behavior. (internal/cmd/drive_changes_poll.go:123, b1e5d49d33fc)
• Inclusive Docs watermark: Docs polling orders comments by timestamp and ID, remembers IDs delivered at the inclusive timestamp, and advances state from all fresh comments so excluded resolved comments do not repeat indefinitely. (internal/cmd/docs_comments_poll.go:195, b1e5d49d33fc)
• Output and hook boundary: JSON events are compacted to one stdout line, while the explicitly operator-provided shell hook receives Google data only through JSON stdin and sends both output streams to stderr. (internal/cmd/poll_helpers.go:58, b1e5d49d33fc)
• Current-main foundation: Current main already contains the Drive change-list and Docs comment-list primitives, including modified-time filtering, so this PR composes established clients instead of introducing a parallel provider implementation. (internal/cmd/comment_ops.go:121, 3f653c724656)

Likely related people:

• steipete: Authored the existing Drive/Docs command foundation, both polling commits, the stacked Drive receiver work, and the exact-head live verification. (role: feature owner and recent area contributor; confidence: high; commits: 6a2290c90a6b, 06a958eb7024, b1e5d49d33fc; files: internal/cmd/drive_changes.go, internal/cmd/docs_comments.go, internal/cmd/poll_helpers.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Maintainer verification on rebased head b1e5d49d:

• Structured Codex autoreview: clean, no accepted/actionable findings.
• Local gate: make ci passed, including all tests, 631 generated command pages, docs site build, and docs coverage.
• Live E2E with clawdbot@gmail.com:
  • initialized isolated Drive and Docs state files;
  • created a disposable Google Doc;
  • Drive polling emitted one filtered batch and passed matching JSON to the sequential hook;
  • the next Drive poll emitted nothing and did not rerun the hook;
  • Docs polling emitted the new comment and a later modification once each, passing matching JSON to the hook;
  • subsequent Docs polls emitted nothing and did not rerun hooks;
  • both persisted state files validated at version 1;
  • disposable Doc moved to trash.

Waiting for exact-head GitHub CI before merge.