feat(drive/docs): add poll subcommand with state-file for changes + comments

[sebsnyk]

Motivation

Not every consumer can host an HTTPS endpoint (corporate firewalls, ephemeral laptops). A polling alternative — interval-based changes.list + comments diff — is the no-infra path. It is straightforward to script today but bookkeeping the page token between runs is tedious; baking a poll subcommand with a state file makes it one command.

Pairs with (but does not replace) a future gog drive changes serve push-notification receiver — poll is for the no-infra case, serve is for real-time.

Depends on

• feat(comments): add --since=<RFC3339> filter on docs/drive comments list #688 --since=<RFC3339> filter on comments list. The gog docs comments poll surface proposed below reduces to: persist last-seen modifiedTime in the state file, call comments list --since=<last-seen> each tick, fire --on-new per result, advance the watermark. Without --since the polling loop has to either list-all-and-filter-client-side (wasteful, and pagination-heavy on large docs) or maintain a per-comment-ID seen-set (state explosion). With --since it is a trivial wrapper. The drive changes poll half is self-contained (it uses changes.list pageToken semantics, which are already complete in v0.21).

Repro

# Today, polling:
TOKEN=$(cat ~/.gogcli-state/token || gog drive changes start-token | jq -r .startPageToken)
while sleep 30; do
  RESP=$(gog drive changes list --token "$TOKEN" -j)
  echo "$RESP" | jq '.changes'
  TOKEN=$(echo "$RESP" | jq -r .newStartPageToken)
  echo "$TOKEN" > ~/.gogcli-state/token
done

# Wanted:
gog drive changes poll --state-file ~/.gogcli-state/drive.json --interval 30s --on-change ./handle.sh

Proposed surface

gog drive changes poll [flags]
  --state-file=PATH       Persist pageToken (created on first call from changes.startPageToken)
  --interval=DUR          Poll interval (default 60s)
  --on-change="<cmd>"     Shell command per non-empty result
  --filter-file=<id>      Short-circuit when changes do not touch this file
  --drive=STRING          Shared-drive id
  --max-iterations=INT    Stop after N iterations (default 0 = forever)

gog docs comments poll <docId> [flags]
  --state-file=PATH       Persist last-seen modifiedTime (consumes --since from #688)
  --interval=DUR
  --include-resolved
  --on-new="<cmd>"        Shell command per new comment; comment JSON on stdin

Acceptance criteria

• State file atomically updated (write to .tmp, rename).
• First invocation with a missing/empty state-file calls changes.startPageToken automatically.
• --on-change / --on-new invocations are sequential (no overlap).
• Graceful shutdown on SIGINT/SIGTERM persists state before exiting.
• docs comments poll reuses the --since implementation from feat(comments): add --since=<RFC3339> filter on docs/drive comments list #688; no separate listing path.

References

• changes.list: https://developers.google.com/workspace/drive/api/reference/rest/v3/changes/list
• comments.list with startModifiedTime: https://developers.google.com/workspace/drive/api/reference/rest/v3/comments/list

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 4, 2026, 8:29 AM ET / 12:29 UTC.

Summary
Keep open: current main exposes the underlying Drive changes and comments primitives, but it does not provide the requested state-file polling loop or docs comments poll command. The request is a new long-running automation surface with subprocess hooks, and the comments half depends on the still-open #688 prerequisite.

Reproducibility: not applicable. this is a feature request, not a bug report. Source inspection gives a high-confidence absence check for the requested poll commands and --since prerequisite on current main.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
Maintainers need to decide the long-running polling, state persistence, and shell-hook contract before this is suitable for an automatic fix-PR lane.

Review details

Best possible solution:

Decide the supported polling and shell-hook contract first, land or account for #688, then implement the commands with focused unit coverage, generated docs, and live Google API proof.

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

Not applicable: this is a feature request, not a bug report. Source inspection gives a high-confidence absence check for the requested poll commands and --since prerequisite on current main.

Is this the best way to solve the issue?

Unclear: the requested surface is plausible, but long-running shell-hook polling is not automatically the best permanent contract until maintainers decide the safety, output, and state-file semantics. The comments polling path should reuse the related --since work rather than introduce a separate listing strategy.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The docs comments poll half depends on feat(comments): add --since=<RFC3339> filter on docs/drive comments list #688; implementing this first would either force inefficient list-all filtering or a larger per-comment seen-set design.
• The proposed --on-change/--on-new shell hooks, atomic state file, and signal behavior are user-visible automation contracts that need maintainer safety and UX direction before implementation.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label changes:

• remove clawsweeper:fix-shape-clear: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is a useful but speculative automation feature, not a broken existing workflow or urgent regression.
• impact:other: The issue affects no-infra Drive/docs automation ergonomics, which is maintainer-visible but outside the specific owned impact categories.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; it reinforces read-only PR review flow, parseable stdout, and stderr for human hints, which matters for any future command design. (AGENTS.md:1, 3d5c9cef65fa)
• Vision requires discussion: VISION.md fits small supported-area primitives, but explicitly calls out new API surfaces and long-running/background machinery as discuss-first areas. (VISION.md:10, 3d5c9cef65fa)
• Drive changes has no poll subcommand: DriveChangesCmd currently registers only start-token, list, watch, and stop; there is no poll command or state-file option. (internal/cmd/drive_changes.go:21, 3d5c9cef65fa)
• Existing Drive changes primitive is token-listing only: DriveChangesListCmd accepts token/page/max/all/include-removed/drive/fail-empty and calls Changes.List, returning nextPageToken; it does not own a loop, signal handling, shell hook, or atomic state file. (internal/cmd/drive_changes.go:55, 3d5c9cef65fa)
• Docs comments has no poll or since flag: DocsCommentsCmd registers list/get/add/reply/resolve/reopen/delete, and DocsCommentsListCmd has include-resolved/max/page/all/fail-empty only. (internal/cmd/docs_comments.go:12, 3d5c9cef65fa)
• Shared comment listing lacks startModifiedTime: The shared fetchDriveCommentsPage helper calls svc.Comments.List(fileID) with IncludeDeleted, PageSize, Fields, and optional PageToken only; no startModifiedTime path exists on current main. (internal/cmd/comment_ops.go:109, 3d5c9cef65fa)

Likely related people:

• steipete: Available blame/history attributes the current Drive changes and shared comments command surfaces to the v0.21.0 release commit authored by Peter Steinberger; the shallow checkout does not expose earlier per-PR authorship. (role: recent area contributor; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/drive_changes.go, internal/cmd/docs_comments.go, internal/cmd/comment_ops.go)
• sebsnyk: The issue author also appears in release notes as the credited contributor for adjacent Drive/docs comments resolve/reopen behavior, making them a useful domain-context contact for this polling request. (role: adjacent contributor and reporter; confidence: low; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/drive_comments.go, internal/cmd/docs_comments.go)

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.