feat(drive): changes serve — receive Drive push notifications and trigger callbacks

[sebsnyk]

Motivation

gog drive changes watch already registers an HTTPS webhook channel against the Drive Changes API. The receiving side — the HTTPS endpoint Google posts to — is left as an exercise for the user. Meanwhile, the Gmail side ships a complete push handler at gog gmail watch serve (see internal/cmd/gmail_watch_server.go). The Drive equivalent is missing, which means anyone wanting real-time change events has to roll their own HTTPS receiver, deal with cert/tunnel setup, parse X-Goog-Channel-* headers, persist the pageToken between events, and renew the channel before its TTL expires.

This is the missing half of drive changes watch. With it, end-to-end automation ("fire a script every time something changes on this doc") works out of the box.

Pairs with

• feat(comments): add --since=<RFC3339> filter on docs/drive comments list #688 comments list --since=<RFC3339> — Drive's changes.watch fires on file mutations but does not carry which comment changed. The canonical pattern is changes.watch → on event, call comments.list?startModifiedTime=<last-seen> to enumerate new/edited comments. Without feat(comments): add --since=<RFC3339> filter on docs/drive comments list #688, the on-change handler has to list-all-and-filter-client-side, which is wasteful at scale.
• feat(docs comments): add locate subcommand to resolve a comment to a body range #687 docs comments locate — once a comment event fires, the consumer typically wants to act on the comment's anchor text. comments locate is the resolver that turns the event into an actionable (startIndex, endIndex) for the next batchUpdate.
• feat(drive/docs): add poll subcommand with state-file for changes + comments #690 drive changes poll — strict alternative to serve for environments that cannot host an HTTPS endpoint (firewalls, ephemeral laptops). Both subcommands share state-file semantics and the --on-change callback shape.

Together these four close the comment-driven edit loop: serve (or poll) detects the change, comments list --since enumerates what is new, comments locate resolves the anchor, and an existing surgical command (delete / format / insert-person etc.) acts on the resolved range.

Repro

# Today:
gog drive changes watch --token=... --webhook-url=https://my-server.example.com/hook
# Now the user has to:
#   1. Run an HTTPS server on https://my-server.example.com/hook
#   2. Parse X-Goog-Channel-ID, X-Goog-Channel-Token, X-Goog-Resource-State
#   3. Call `gog drive changes list --token=<saved>` on each notification
#   4. Persist the next pageToken
#   5. Re-call `gog drive changes watch` before the channel expires (max 7d)

Proposed surface

gog drive changes serve [flags]
  --listen=:8443                Local listen address
  --cert=PATH --key=PATH        TLS cert + key (Google requires HTTPS)
  --channel-token=STRING        Expected channel token (rejects mismatched POSTs)
  --state-file=PATH             Where to persist the next pageToken between notifications
  --on-change="<cmd>"           Shell command invoked per notification; JSON payload on stdin
  --filter-file=<id>            Only fire on-change when the change touches this file id
  --auto-renew                  Re-call changes.watch before the channel expires
  --renew-before=10m            How long before expiration to renew (default 10m)
  --drive=STRING                Shared-drive ID for shared-drive change logs
  --foreground                  Stay in the terminal (default; pair with systemd / launchd otherwise)

Payload format for --on-change:

{
  "channelId": "...",
  "resourceState": "change",
  "messageNumber": 17,
  "resourceUri": "...",
  "changes": [{"fileId":"...","time":"...","removed":false}]
}

Mirrors gog gmail watch serve structure: ServeHTTP authenticates by X-Goog-Channel-Token, calls changes.list, optionally invokes the user callback, persists the new token.

Acceptance criteria

• Validates X-Goog-Channel-Token; returns 401 on mismatch.
• Returns 200 on success (Google docs accept 200, 201, 202, 204, 102).
• Persists the next pageToken atomically (no half-writes on crash).
• --on-change is invoked once per notification with the JSON payload on stdin.
• --auto-renew re-issues changes.watch at least --renew-before ahead of expiration and rolls over the channel id cleanly.
• --filter-file=<id> short-circuits before calling on-change when the changes list does not include the target file.

References

• Drive push notifications guide (TTL, X-Goog headers, channel renewal): https://developers.google.com/workspace/drive/api/guides/push
• changes.watch reference: https://developers.google.com/workspace/drive/api/reference/rest/v3/changes/watch
• changes.list reference: https://developers.google.com/workspace/drive/api/reference/rest/v3/changes/list
• Existing prior art in the repo: internal/cmd/gmail_watch_server.go (Pub/Sub push handler), internal/cmd/drive_changes.go (watch + stop)

[clawsweeper]

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

Summary
Keep open: current main and the latest release have Drive changes start-token/list/watch/stop, but no Drive-side HTTPS receiver, callback runner, page-token state file, file filter, or auto-renew flow. The request is plausible for supported Drive automation, but it needs maintainer product and security review because it adds long-running server behavior and externally triggered local command execution.

Reproducibility: not applicable. this is a request for a new Drive receiver command, not a report that existing documented behavior is broken. Source inspection confirms the requested command surface is absent.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
This needs maintainer product/security review before a repair lane because it introduces a long-running HTTPS receiver and externally triggered local command execution.

Security
Needs attention: The issue itself is security-sensitive because it proposes an externally reachable webhook receiver that can trigger local callback execution.

Review details

Best possible solution:

Design a maintainer-approved Drive push receiver that reuses existing watch/server/state patterns, validates channel tokens, persists page tokens atomically, documents callback safety, and includes focused unit coverage plus live Google proof.

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

Not applicable: this is a request for a new Drive receiver command, not a report that existing documented behavior is broken. Source inspection confirms the requested command surface is absent.

Is this the best way to solve the issue?

Unclear: serve is a plausible shape because Gmail has prior art, but the callback execution, state persistence, TLS/listen defaults, and auto-renew behavior need maintainer product/security decisions first.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The proposed --on-change callback would execute local commands in response to externally triggered webhook traffic, so the trust boundary and invocation semantics need maintainer security review.
• Auto-renew creates overlap and rollover behavior for Drive channels; maintainers should decide how channel IDs, resource IDs, expiration, and state-file updates behave before implementation.
• VISION.md asks for discussion and live Google proof for new long-running machinery and live-provider behavior, so this should not enter an autonomous fix lane yet.

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

Label changes

Label changes:

• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority Drive automation feature in a supported area, but it needs design and security review rather than emergency handling.
• impact:security: The requested webhook server would validate external push traffic and run local callback commands, so security boundaries are central to the issue.

Evidence reviewed

Security concerns:

• [medium] Define the webhook-to-command trust boundary
  --on-change would run a local command from Drive notification traffic; maintainers should require channel-token validation, safe command invocation semantics, redaction guidance, and tests before implementation.
  Confidence: 0.86
• [medium] Review receiver state and renewal safety
  The receiver would store page tokens and roll over channels; token comparison, TLS/listen defaults, file permissions, and atomic state writes need an explicit design.
  Confidence: 0.78

What I checked:

• Current Drive changes surface: DriveChangesCmd currently registers only start-token, list, watch, and stop; there is no serve subcommand in the current command tree. (internal/cmd/drive_changes.go:21, 3d5c9cef65fa)
• Watch only registers a webhook channel: DriveChangesWatchCmd accepts --webhook-url, --channel-token, and --expiration-ms, then calls svc.Changes.Watch; it does not implement inbound POST handling, token persistence, callbacks, filtering, or renewal. (internal/cmd/drive_changes.go:135, 3d5c9cef65fa)
• Generated docs also omit serve: The generated Drive changes docs list list, start-token, stop, and watch, with no serve page or subcommand. (docs/commands/gog-drive-changes.md:17, 3d5c9cef65fa)
• No implementation keywords found: A source/docs search for drive changes serve, on-change, state-file, filter-file, auto-renew, and Drive push header names returned no Drive receiver implementation. (3d5c9cef65fa)
• Gmail prior art exists: GmailWatchCmd includes Serve, and the Gmail server authorizes POST requests and processes push payloads, so the issue correctly points at existing prior art rather than an existing Drive implementation. (internal/cmd/gmail_watch_cmds.go:28, 3d5c9cef65fa)
• External API behavior supports the request shape: Google Drive push notifications require an HTTPS callback receiver, include X-Goog-* headers such as channel token/resource state, require explicit channel replacement for renewal, and accept 200/201/202/204/102 success responses. (developers.google.com)

Likely related people:

• Peter Steinberger: The grafted checkout attributes the Drive changes command file and Gmail watch prior-art files to the v0.21.0 release commit by this author, making this the strongest local routing signal. (role: feature-history and release provenance; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/drive_changes.go, internal/cmd/gmail_watch_cmds.go, internal/cmd/gmail_watch_server.go)
• salmonumbrella: CHANGELOG.md credits this handle for multiple Gmail watch serve refinements, which are directly relevant prior art for a Drive push receiver design. (role: adjacent Gmail watch contributor; confidence: low; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/gmail_watch_cmds.go, internal/cmd/gmail_watch_server.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.