Agent Observability for Credential Expiry: Build an Access Lease

An agent should not begin protected work merely because its credential succeeded five minutes ago. The safer preflight is an access lease : compare the credential’s remaining lifetime with the planned work duration plus a renewal margin, verify that its granted scope still covers the task, and confirm that the approved renewal path is healthy. If any of those facts is missing, agent observability should report uncertainty instead of a green check. This catches a common operational failure before it becomes a half finished run. A tool can be reachable at startup, accept several calls, and then reject the write that matters after a short lived token expires. A broad retry may make the situation worse: it cannot restore missing authority, and it may repeat an earlier side effect whose response was lost. The practical default is to keep only non secret lease metadata: issuer or provider, observed expiry, a digest or names of required scopes, granted scopes, last renewal result, intended work duration, and observation time. Never put the token itself in traces, prompts, article fixtures, or dashboards. Treat access as a changing operational dependency Credential health is not a permanent property of an integration. It is a time bounded and scope bounded dependency of a particular run. OAuth 2.0 defines expires in as the access token lifetime in seconds and describes a refresh token as an optional credential used to obtain new access tokens. That gives a client two useful facts, but not a complete health verdict. A token with 3,600 seconds left is adequate for a ten minute lookup and inadequate for a 50 minute export when the system also needs a 15 minute safety margin. Provider contracts make the timing concrete. GitHub documents that a GitHub App installation access token response includes its expiry and that the token expires after one hour. GitHub’s SDKs can regenerate installation tokens, but an operator still needs to know whether the runtime uses that renewal path and whether it is working. Scope is a separate axis. RFC 6750 distinguishes an expired, revoked, malformed, or otherwise invalid token ( invalid token , normally HTTP 401) from a token that lacks sufficient privileges ( insufficient scope , normally HTTP 403). Requesting a new token may resolve the first condition. Repeating the same call cannot manufacture authority for the second. Keep these facts separate: Lease fact Question it answers Unsafe inference expiresAt When does the observed access window end? The issuer cannot revoke it earlier plannedWorkSeconds How long should the protected phase take? Every run will finish inside that estimate renewalMarginSeconds How much room is reserved for delay and renewal? One margin fits every provider requiredScopes What authority does this task need? The provider interprets names identically forever grantedScopes What authority was observed? The grant was not changed after observation lastRefreshResult Did the configured renewal path last work? The next renewal must work An access lease is therefore evidence with a freshness time, not a copy of a credential and not a promise from the provider. Calculate runway before the first protected action Use a small inequality for the time check: Calculate remaining lifetime from the issuer’s expiry and the observation clock. Use a high percentile duration for the protected part of the task, not the fastest recent run. The margin should cover normal queueing, clock skew, provider delay, and the time required to renew and recheck access. The values are operational policy, not constants supplied by OAuth. The accompanying fixture fixes the observation time and evaluates six synthetic leases: The run produced: The export worker token has 3,600 seconds of runway. That sounds healthy until the preflight adds 3,000 seconds of planned work and a 900 second renewal margin. The required runway is 3,900 seconds, so the classifier returns renewal due before the export starts. scope reduced has four hours before expiry, yet it is not healthy. The task requires records:read and records:write ; only the read scope was observed. Its state is scope drift , and the safe action is an explicit authority review. Silently requesting a wider grant would cross the operator’s approval boundary. legacy static token has the required scope but no inspectable expiry. The classifier returns unknown . “Static” is not evidence for “never expires”: the credential may be revoked, rotated manually, or governed by a provider policy the adapter did not collect. The decision order matters: 1. Compare required and granted authority. Missing scope is not a timing problem. 2. Require an inspectable expiry or an explicit bounded rotation policy. 3. Stop work when the observed lease has expired. 4. Surface a failed renewal path before attempting protected work. 5. Compare remaining lifetime with work plus margin. 6. Mark the lease healthy only when all required evidence passes. This order prevents a long expiry time from hiding missing scope and prevents a successful past call from hiding a broken refresher. Observe renewal without collecting secrets A useful lease event does not need the access token, refresh token, client secret, request body, prompt, response, or absolute credential path. Collect the smallest record that can change the operational verdict: credentialRef should be a local opaque reference or keyed digest, not a token prefix that makes correlation easier for an attacker. If scope names themselves disclose sensitive structure, store a policy identifier and a keyed digest, then keep the human readable mapping on the host. Observe the lease at three boundaries: Before a run: reject or route work that lacks sufficient runway or authority. After renewal: re read expiry and granted scope; command success alone is not renewal proof. After an authorization failure: retain the non secret status, provider error class, observation time, and affected task, then invalidate the earlier healthy verdict. Do not turn a preflight failure into an automatic permission escalation. A refresher may renew an already approved grant; it should not add repositories, broaden scopes, replace credentials, or request human authority without a visible decision. For irreversible or externally visible work, also retain the task’s idempotency key and destination verifier. Credential health proves access, not the outcome. Handle revocation, clock error, and mid run expiry honestly The lease model has limits. An issuer can revoke a token before expiresAt . A provider may omit expiry. Local clocks can drift. Scope can be reduced after observation. A renewal endpoint can succeed while returning a token for the wrong resource. These conditions make the evidence stale or incomplete; they do not justify a healthy state. Use the provider’s server time when available, record the collector’s observation time, and reject impossible negative ages. Recheck close to the protected action rather than once at process startup. Long runs should split work at safe checkpoints and renew before the lease falls below the remaining work estimate. If access fails after a side effecting request was sent, do not blindly retry. The provider may have committed the effect before the response disappeared. Reconcile through an idempotency key or an independent destination lookup, then decide whether another attempt is safe. The reusable operating rule is narrow: start protected agent work only when observed lifetime covers planned work plus margin, required scope is present, and the approved renewal path is healthy. Treat missing evidence as unknown, and keep secret material out of observability. Sidewisp is currently in private preview. Its public site and article library are live, but production agent health collection, runtime adapters, credential monitoring, and recovery are not generally shipped. Sidewisp is intended to work alongside existing runtimes and keep human authority visible. If credential lease health is one of the failures you need surfaced before work begins, you can join the private preview waitlist without treating this article as a claim of deployed monitoring.