Skip to content

Renew environment links before their 30-day credential expires - #106

Merged
nullStack65 merged 2 commits into
release/native-0.1.10from
feat/native-0.1.10-link-renewal
Nov 19, 2026
Merged

nullStack65 merged 2 commits into
release/native-0.1.10from
feat/native-0.1.10-link-renewal

Conversation

@nullStack65

@nullStack65 nullStack65 commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

What

Links between environments renew their own credential before it expires. Today a link's credential is a 30-day MCP client session on the peer, there is no refresh grant, and nothing renews it, so every link in the fleet mesh lapses about 30 days after it was made (around Dec 18–19, 2026) and cross-machine delegation and the shared inbox stop without warning.

  • Peer side, a new link-only t3_link_renew tool. It is offered only to a linked environment, never to an agent. The handler also refuses outside agents, local agent threads and a link's call made for one of its agent threads. It signs the calling link's same session again with a new 30-day expiry and moves that session row's expires_at (SessionStore.renew, AuthSessionRepository.extend, EnvironmentAuth.renewMcpClientSession). Because the session id does not change, the link fence (client:<sessionId>), idempotency keys and the peer's Connections entry stay the same. Only live bearer peer-link sessions renew; a revoked, expired or DPoP session returns capability_denied. A revocation between the read and the update wins.
  • Linking side, an hourly sweep (PeerLinkRenewal). It starts two minutes after startup and then runs hourly. A link with 20 days or fewer left whose peer advertises the new linkRenewal capability calls t3_link_renew. The new token is stored under the same secret name (PeerLinks.renewed), so the link's incarnation does not change and in-flight work bound to it stays bound. If the link was linked again meanwhile, the stale token is not kept.
  • One alert per link (watcher outbox, ModelAlertReactor). A new peer-link-renewal watcher alert uses the existing durable outbox, destinations, retry and backoff. Dedupe is keyed by the linked environment and the link's session here in the persisted reported map, so linking again starts fresh. A failing link alerts once and stays quiet through later hourly failures while that alert is queued or once it was delivered; it alerts again after a renewal, after linking again, or if the alert left the outbox undelivered. Nothing counts as reported until something was queued. A transient failure (the peer is off or unreachable, or a storage error) is retried quietly and alerts only in the link's last 7 days. A permanent one alerts at once: a revoked session or an older peer without linkRenewal. An expired link is not retried; it alerts once that it needs linking again. One link's failure never stops the sweep for the others. An alert that is still queued when its link renews is dropped.
  • Docs: docs/user/remote-access.md and docs/internals/remote.md.

No setting is added. Renewal is always on, so there is no default to flip in packages/contracts/src/settings.ts.

Tradeoffs

  • A stolen link token can now be renewed indefinitely, like a refresh token, instead of dying within 30 days. The kill switch is unchanged: revoke the link in the peer's Settings → Sharing & access, and it stops renewing and stops working. The old token stays valid until its own expiry; this PR adds no revocation-on-renew. There is deliberately no renewal cap: a cap would bring back a periodic pairing step, which this change exists to remove. Note also that t3_link_renew is offered to sessions marked as peer links, and that mark comes from the software_id the client declared when it registered over MCP OAuth. Any client that completed a pairing exchange at full trust could therefore renew its own session. Pairing itself is the trust boundary, and revocation on the peer remains the kill switch.
  • Both ends need this build. A link to or from a machine on an older build, such as the Air or a desktop without the fork build, cannot renew. That link raises one alert once it is inside its last 20 days.
  • If the failing link is the one to the watcher's own machine, the watcher delivery can fail over that same link. The outbox keeps retrying it, and the webhook destination, when one is set, still receives the alert.

Verification

  • PeerLinkRenewal.test.ts, end to end against a real peer on a socket under TestClock:
    • At 21 days left nothing happens.
    • At 19 days left the link renews. Its expiry moves from day 30 to day 41, the peer has the same single session with expiry day 41, the incarnation is unchanged, and a call on day 36 succeeds on the renewed token.
    • A peer without linkRenewal, and a session revoked on the peer, each produce one failed outcome and leave the expiry unchanged.
    • The handler refuses outside agents, agent threads and a link's sender thread.
  • ModelAlertReactor.test.ts: three failures queue one alert per destination, a renewal clears it, a later failure alerts again, and another link alerts on its own. With no destination nothing is marked; an undelivered alert that left the outbox alerts again; a delivered one stays quiet past the outbox week; linking again (a new session) alerts fresh.
  • PeerLinkRenewal.test.ts: an expired link is not tried against the peer and raises one "link it again" alert naming its session.
  • effect-tsgo typecheck of apps/server, vp lint and vp fmt --check on the touched files, plus the peer, auth, mcp, environment, persistence and model-alert suites.

Deploy: fleet

🤖 Generated with Claude Code

nullStack65 and others added 2 commits November 19, 2026 17:55
A link's credential is a 30-day MCP client session on the peer with no
refresh path, so every link lapsed 30 days after pairing. The linking
side now sweeps hourly and, inside a link's last 20 days, calls the new
link-only t3_link_renew tool. The peer signs the same session again with
a later expiry, so the link fence, idempotency keys and incarnation stay
the same and no pairing code is needed. A link that cannot renew sends
the watcher one alert, through the model alert outbox, until it renews.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion

- Key a link's renewal alert by its session here, so linking again alerts fresh.
- Count an alert as reported only once queued; a delivered one keeps the link
  quiet, and one that left the outbox undelivered lets the next failure alert.
- An expired link is not retried; it alerts once that it needs linking again.
- One link's defect no longer stops the sweep; a replaced link's renewal logs
  as not kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nullStack65

Copy link
Copy Markdown
Owner Author

Review findings from the single bot review round (Fable 5.2), and what head b080c563d2 does about each:

  1. A relinked link inherited the old alert key. Fixed. The key now includes the link's session here (linkSession), so linking again alerts fresh.
  2. The key was set when nothing was queued, and never re-armed after an undelivered alert expired. Fixed. The key is set only when something was queued. A delivered alert is marked as delivered. A link whose alert left the outbox undelivered alerts again.
  3. The token can be renewed forever, and plk is self-declared. Kept by design, with no cap, because a cap would bring back periodic pairing. The reasoning is now in the PR Tradeoffs. Revoking on the peer remains the kill switch.
  4. Expired and legacy links were retried and warned about every hour. Fixed. An expired link is no longer tried and raises one "link it again" alert. A legacy peer alerts once, through the dedupe above.
  5. Key eviction. Accepted. It is bounded by MAX_REPORTED.
  6. A superseded renewal was logged as renewed, and one defect aborted the sweep. Fixed. A renewal that was not kept now logs as such, and each link runs under its own catchCause.

Tests were added for each fix. Typecheck, lint and fmt are clean, and src/peer, src/mcp and ModelAlertReactor.test.ts pass: 38 files, 588 tests. This is the repair for that one round, not a second review round.

@nullStack65
nullStack65 merged commit a327eae into release/native-0.1.10 Nov 19, 2026
4 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant