docs(stalker): record the cached-token revalidation trade-off

Codex flagged that the static path no longer self-heals a retired token, since
`ensureToken` returns a same-identity cache entry without a network call —
whereas `create_link` used to refresh it through `makeAuthenticatedRequest`'s
auth-failure retry.

The mechanism it posits does not exist on stock Stalker: per the 4.9.35
reference, handshake tokens have no TTL, and not sending the watchdog does not
invalidate auth (it only clears the admin panel's "online" flag). The real
residual vector is another device calling `get_profile` on the same MAC, which
is common enough on shared subscriptions to be worth naming.

Revalidating on every static playback would cost exactly the round trip this
change removes, so it is deliberately not done. Recorded as a known trade-off
with its mitigation (a running watchdog still self-heals within a ping cycle)
and handed to PR 6, where a refresh on an OBSERVED playback authorization
failure belongs.

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

docs/architecture/stalker-portal.md

@@ -393,6 +393,23 @@ The call is best-effort: a static URL may point at a CDN needing no credentials
 at all, so a failed handshake degrades to the token-less header set rather than
 costing the user their playback.
 
+**Known trade-off: a cached token is not revalidated.** `ensureToken` returns a
+same-identity cache entry without touching the network, so the static path no
+longer self-heals a token the server has retired — something `create_link`
+used to do for free, since `makeAuthenticatedRequest` retires and re-auths on
+an authorization failure. This is narrower than it sounds: per the 4.9.35
+reference, handshake tokens have **no TTL**, and failing to send the watchdog
+does **not** invalidate auth (it only clears the admin panel's "online"
+status). The one real vector left is another device performing `get_profile`
+on the same MAC — common enough on shared subscriptions. Where a watchdog is
+running it still self-heals within a ping cycle, because the ping goes through
+`makeAuthenticatedRequest`.
+
+Revalidating on every static playback would cost exactly the round trip this
+section exists to remove, so it is deliberately not done here. The right home
+for a fix is the auth lifecycle (PR 6): refresh on an observed playback
+authorization failure, rather than pre-emptively on every play.
+
 **Downloads are the exception, and cannot use this.** A download request cannot
 carry portal credentials at all — the main-process stored-header allowlist is
 `User-Agent` / `Origin` / `Referer` only