feat(oauth): an assistant's tokens may last as long as its grant, up to a year

[frahlg]

Problem

Fredrik, 17 October 2026: an assistant's access should be able to last longer than 30 days, up to a year. srcfl/ftw#1686 raises the box's limit. FTW Cloud must offer the longer length, and an assistant's tokens must last as long as the grant the box sets, never longer.

Change

• The offer asks for a year. buildOffer already takes ttlS from protocol.AgentMaxMs, which feat(agents): an assistant's grant may last a year, and agent.list says so ftw#1686 raises to 365 days. FTW Cloud makes the offer before the owner picks a home, so it cannot ask each box what it takes. The app and the box page cap the length at what the box says it takes (longestMs in agent.list and in the box page's facts) and offer 30 days at most to a box that says nothing. Apps and box pages already out offer 30 days at most whatever the offer asks.
• RefreshTTL is now protocol.AgentMaxMs, a year. The access token stays at ten minutes.
• A refresh token is not clamped to the grant. Before, a refresh passed the old token's end on, so a family died at the end it had when the code was swapped, even after the owner renewed the grant. Clamping each refresh row to the grant's end at issue would still fail an idle assistant: last used on day 10, renewed for a year on day 29, it would get 400 on day 31. Now a refresh token lasts RefreshTTL from issue. An agent past its end in the box's newest roster is refused at every refresh and every call (agentGone) and swept with its tokens, so a refresh token is never usable past the grant. The access token stays within ten minutes and never past the grant's end. Rotation and reuse detection are unchanged.
• No roster end past a year. grantOf cuts an end past now + protocol.AgentMaxMs.
• Comments on the spent-code memory and the offer say what changed.

Tests

• TestARefreshTokenFollowsTheGrantTheBoxSets: an assistant idle since day 0, whose 30-day grant is renewed for a year on day 29, refreshes with its day-0 refresh token on day 31. Cut to five minutes, the next access token lasts at most 300 s and fails after the cut, and so does the refresh. With a refresh row clamped to the grant, it fails ("an idle assistant lost a renewed grant at its first end").
• TestARosterEndPastAYearIsCut: a roster end two years out is stored as at most a year from now.
• TestTheOfferIsSignedAndCarriesTheConsent now pins ttlS at 365 × 86,400.
• go vet ./..., go test -race ./..., go test -tags ftwclouddev ./..., scripts/check-imports.sh: pass. On one full -race run under heavy load, TestRostersAreNotDropped, TestUnsupportedVersionsAndTheRateLimit and later TestAPurgedHomeLosesItsAgents each failed once on a wait. Each passed on its own (-count=3 and -count=4), and two more full -race runs passed on this branch and on main.

Pairs

• feat(agents): an assistant's grant may last a year, and agent.list says so ftw#1686 (go/protocol): AgentMaxMs a year, longestMs in agent.list and the box page's facts. Merged; this PR pins go/protocol at its merge commit, 8a7bd9c6e597c4396deb05a5b7cd728f6619f97b on srcfl/ftw master.
• feat(access): let an assistant in for up to a year where the box takes it ftw-app#82: choices up to a year, a start at 30 days, 30 days for a box that says nothing.
• privacy: what FTW Cloud sees and keeps when an assistant has access ftw-web#21: the privacy page says access lasts up to a year.

Deploy this before the Core beta with srcfl/ftw#1686 and before srcfl/ftw-app#82. New grants are safe in any order, but renewals are not: the newer box page and app offer to renew for a year from the box's longestMs alone, and an older cloud ends every refresh family 30 days after the code swap. Deploying this first is safe: older apps and box pages still give 30 days at most, and a newer box with this cloud's year-long offer gives what the owner picks.

Nothing here is deployed. Deploying is the owner's step.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-17T06:38:33.397583Z	49d450e	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 49d450e48f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Retain reuse markers for the sliding family lifetime

When a grant is repeatedly renewed and this line keeps the token family alive for more than a year, store.sweep deletes the original spent_codes entry and each rotated refresh-token row at that credential's own expires_ms, even though newer descendants remain valid. Replaying an authorization code or refresh token older than a year is then treated as an unknown credential rather than reuse, so revokeFamily is not called and the still-live family remains usable; retain these reuse markers until the family actually ends, or keep an absolute family expiry.

Useful? React with 👍 / 👎.