@askalf/dario 6.0.25 → 6.0.26

package/README.md

@@ -20,7 +20,7 @@
 
 <sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~30k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
-<sub>Part of <a href="#own-your-stack"><strong>Own Your Stack</strong></a> — 12 open tools for owning your AI infra: <a href="https://github.com/askalf/truecopy">truecopy</a> · <a href="https://github.com/askalf/strongroom">strongroom</a> · <a href="https://github.com/askalf/fieldpass">fieldpass</a> · <a href="https://github.com/askalf/plumbline">plumbline</a> · <a href="#own-your-stack">full family ↓</a></sub>
+<sub>Part of <a href="#own-your-stack"><strong>Own Your Stack</strong></a> — 11 open tools for owning your AI infra: <a href="https://github.com/askalf/redstamp">redstamp</a> · <a href="https://github.com/askalf/truecopy">truecopy</a> · <a href="https://github.com/askalf/fieldpass">fieldpass</a> · <a href="https://github.com/askalf/plumbline">plumbline</a> · <a href="#own-your-stack">full family ↓</a></sub>
 
 </div>
 
@@ -456,16 +456,16 @@ dario is the routing layer of **[Own Your Stack](https://github.com/askalf)**
 
 - **[dario](https://github.com/askalf/dario)** — own your routing _(you are here)_
 - **[hybrid](https://github.com/askalf/hybrid)** — own your inference
-- **[deepdive](https://github.com/askalf/deepdive)** — own your research
-- **[hands](https://github.com/askalf/hands)** — own your computer-use
 - **[browser-bridge](https://github.com/askalf/browser-bridge)** — own your browser
 - **[redstamp](https://github.com/askalf/redstamp)** — own your agent security
 - **[truecopy](https://github.com/askalf/truecopy)** — own your agent skills
-- **[strongroom](https://github.com/askalf/strongroom)** — own your agent secrets
-- **[cordon](https://github.com/askalf/cordon)** — own your prompts
+- **[agent-security-stack](https://github.com/askalf/agent-security-stack)** — own your agent security stack: redstamp + truecopy + strongroom leases, one MCP server
+- **[cordon](https://github.com/askalf/cordon)** — own your prompts · [pair it with dario](./docs/integrations/cordon.md)
 - **[fieldpass](https://github.com/askalf/fieldpass)** — own your agent browser
 - **[plumbline](https://github.com/askalf/plumbline)** — own your agent oversight
 - **[amnesia](https://github.com/askalf/amnesia)** — own your search
+- **[pgflex](https://github.com/askalf/pgflex)** — own your Postgres
+- **[redisflex](https://github.com/askalf/redisflex)** — own your Redis
 - **[askalf](https://askalf.org)** — own your operation: the AI operation that runs Sprayberry Labs
 
 ---

package/dist/accounts.d.ts

@@ -6,6 +6,8 @@ export interface AccountCredentials {
     scopes: string[];
     deviceId: string;
     accountUuid: string;
+    /** Epoch ms of the OAuth grant; see OAuthTokens.grantedAt / refresh-grant.ts. */
+    grantedAt?: number;
 }
 export declare function listAccountAliases(): Promise<string[]>;
 export declare function loadAccount(alias: string): Promise<AccountCredentials | null>;

package/dist/accounts.js

@@ -373,6 +373,7 @@ export async function addAccountViaOAuth(alias) {
                     scopes: tokens.scope?.split(' ') ?? cfg.scopes.split(' '),
                     deviceId: identity.deviceId,
                     accountUuid: identity.accountUuid,
+                    grantedAt: Date.now(),
                 };
                 await saveAccount(creds);
                 resolve(creds);
@@ -508,6 +509,7 @@ export async function completeAddAccount(alias, code, codeVerifier, state) {
         scopes: tokens.scope?.split(' ') ?? cfg.scopes.split(' '),
         deviceId: identity.deviceId,
         accountUuid: identity.accountUuid,
+        grantedAt: Date.now(),
     };
     await saveAccount(creds);
     return creds;
@@ -582,6 +584,7 @@ export async function addAccountFromKeychain(alias, target) {
         scopes: oauth.scopes ?? ['user:inference'],
         deviceId: identity.deviceId,
         accountUuid: identity.accountUuid,
+        grantedAt: oauth.grantedAt,
     };
     await saveAccount(creds);
     return creds;
@@ -641,6 +644,7 @@ export async function ensureLoginCredentialsInPool(alias = MIGRATED_LOGIN_ALIAS)
         scopes: tok.scopes ?? [],
         deviceId: identity.deviceId,
         accountUuid: identity.accountUuid,
+        grantedAt: tok.grantedAt,
     });
     return alias;
 }
@@ -719,6 +723,7 @@ export async function resyncLoginFromCredentialsIfStale() {
         scopes: tok.scopes ?? loginAcc.scopes ?? [],
         deviceId: loginAcc.deviceId,
         accountUuid: loginAcc.accountUuid,
+        grantedAt: tok.grantedAt ?? loginAcc.grantedAt,
     });
     return 'resynced';
 }
@@ -769,6 +774,7 @@ export async function mirrorLoginToCredentials(refreshed) {
         refreshToken: refreshed.refreshToken,
         expiresAt: refreshed.expiresAt,
         scopes: refreshed.scopes ?? creds?.claudeAiOauth?.scopes ?? [],
+        grantedAt: refreshed.grantedAt ?? creds?.claudeAiOauth?.grantedAt,
     });
     return 'mirrored';
 }

package/dist/admin-api.d.ts

@@ -72,6 +72,8 @@ export interface AdminAccountRecord {
     alias: string;
     scopes: string[];
     expiresAt: number;
+    /** Epoch ms of the OAuth grant (refresh-grant.ts); undefined when unknown. */
+    grantedAt?: number;
 }
 /** Live per-account pool status keyed by alias — see `AdminDeps.poolStatus`. */
 export interface AdminAccountLive {

package/dist/admin-api.js

@@ -1,6 +1,7 @@
 import { timingSafeEqual } from 'node:crypto';
 import { startAddAccount, completeAddAccount, removeAccount, listAccountAliases, loadAccount, } from './accounts.js';
 import { parseManualPaste } from './oauth.js';
+import { grantAge } from './refresh-grant.js';
 const PENDING_TTL_MS = 10 * 60_000;
 const MAX_PENDING = 64; // backstop against unbounded growth (distinct aliases)
 const ACCOUNTS_PREFIX = '/admin/accounts/';
@@ -98,7 +99,7 @@ async function defaultListAccounts() {
     const aliases = await listAccountAliases();
     const loaded = await Promise.all(aliases.map(async (alias) => {
         const a = await loadAccount(alias);
-        return a ? { alias: a.alias, scopes: a.scopes, expiresAt: a.expiresAt } : null;
+        return a ? { alias: a.alias, scopes: a.scopes, expiresAt: a.expiresAt, ...(a.grantedAt !== undefined ? { grantedAt: a.grantedAt } : {}) } : null;
     }));
     return loaded.filter((a) => a !== null);
 }
@@ -345,10 +346,15 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
             const live = deps.poolStatus?.() ?? null;
             const accounts = records.map((r) => {
                 const l = live?.get(r.alias);
+                const grant = grantAge(r.grantedAt, now);
                 return {
                     alias: r.alias,
                     scopes: r.scopes,
                     expires_in_ms: Math.max(0, r.expiresAt - now),
+                    granted_at: r.grantedAt ?? null,
+                    grant_age_days: grant.ageDays,
+                    grant_level: grant.level,
+                    refresh_wall_at: grant.wallAt,
                     // Inline the running pool's live status when this account is in it.
                     ...(l ? {
                         util5h: l.util5h,

package/dist/cli.js

@@ -24,6 +24,7 @@ import { pathToFileURL } from 'node:url';
 import { startAutoOAuthFlow, startManualOAuthFlow, detectHeadlessEnvironment, getStatus, refreshTokens, loadCredentials, readLineFromStdin } from './oauth.js';
 import { startProxy, sanitizeError, parseModelAliasSpecs } from './proxy.js';
 import { VALID_EFFORT_VALUES } from './cc-template.js';
+import { grantAge, describeGrantAge } from './refresh-grant.js';
 import { listAccountAliases, loadAllAccounts, addAccountViaOAuth, addAccountViaManualOAuth, addAccountFromKeychain, KeychainImportError, removeAccount, ensureLoginCredentialsInPool, resyncLoginFromCredentialsIfStale, MIGRATED_LOGIN_ALIAS } from './accounts.js';
 import { listCodexAccountAliases, loadAllCodexAccounts, startAddCodexAccount, completeAddCodexAccount, removeCodexAccount, parseCodexManualPaste } from './codex-accounts.js';
 import { listBackends, saveBackend, removeBackend } from './openai-backend.js';
@@ -916,6 +917,7 @@ async function accounts() {
             const mins = Math.floor((msLeft % 3600000) / 60000);
             const expiry = msLeft > 0 ? `${hours}h ${mins}m` : 'expired';
             console.log(`    ${a.alias.padEnd(20)} token expires in ${expiry}`);
+            console.log(`    ${''.padEnd(20)} ${describeGrantAge(grantAge(a.grantedAt, now))}`);
         }
         console.log('');
         return;

package/dist/doctor-core.d.ts

@@ -10,6 +10,7 @@
  * rest of the report down — every check is wrapped so a broken sub-
  * system surfaces as `fail` instead of crashing the CLI.
  */
+import { type GrantThresholds } from './refresh-grant.js';
 export type CheckStatus = 'ok' | 'warn' | 'fail' | 'info';
 export interface Check {
     /** 'ok' passes; 'warn' is advisory; 'fail' blocks (exit code 1); 'info' is neutral. */
@@ -125,6 +126,21 @@ export declare function oauthCheckRow(input: {
     poolHealthy: number;
     poolTotal: number;
 }): Check;
+/**
+ * The refresh-token grant row (refresh-grant.ts), as a pure decision. A token
+ * refresh keeps the access token fresh; it does not move the ~28-day wall on
+ * the grant. Worst seat decides the row: urgent → fail, warn → warn, unknown
+ * (unstamped) → info, all ok → ok. Every seat is listed so the operator sees
+ * which one to re-grant.
+ */
+export declare function checkRefreshGrant(input: {
+    accounts: Array<{
+        alias: string;
+        grantedAt?: number | null;
+    }>;
+    now: number;
+    thresholds?: GrantThresholds;
+}): Check[];
 export declare function checkIdentityDrift(input: IdentityDriftInput): Check[];
 export declare function probeNpmLatestCC(): string | null;
 /**

package/dist/doctor-core.js

@@ -10,6 +10,7 @@
  * rest of the report down — every check is wrapped so a broken sub-
  * system surfaces as `fail` instead of crashing the CLI.
  */
+import { grantAge, grantThresholds, worstGrantLevel, describeGrantAge } from './refresh-grant.js';
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -172,6 +173,25 @@ export function oauthCheckRow(input) {
         detail: legacyStatus === 'none' ? 'not authenticated — run `dario login`' : legacyStatus,
     };
 }
+/**
+ * The refresh-token grant row (refresh-grant.ts), as a pure decision. A token
+ * refresh keeps the access token fresh; it does not move the ~28-day wall on
+ * the grant. Worst seat decides the row: urgent → fail, warn → warn, unknown
+ * (unstamped) → info, all ok → ok. Every seat is listed so the operator sees
+ * which one to re-grant.
+ */
+export function checkRefreshGrant(input) {
+    if (input.accounts.length === 0)
+        return [];
+    const t = input.thresholds ?? grantThresholds();
+    const ages = input.accounts.map((a) => ({ alias: a.alias, age: grantAge(a.grantedAt, input.now, t) }));
+    const worst = worstGrantLevel(ages.map((a) => a.age.level));
+    const status = worst === 'urgent' ? 'fail' : worst === 'warn' ? 'warn' : worst === 'unknown' ? 'info' : 'ok';
+    const perSeat = ages.map((a) => `${a.alias}: ${describeGrantAge(a.age, t)}`).join('; ');
+    const fix = worst === 'ok' ? '' : REGRANT_FIX;
+    return [{ status, label: 'Refresh grant', detail: `${perSeat}${fix}` }];
+}
+const REGRANT_FIX = " — re-grant with `dario accounts add <alias>` (or `dario login --force-reauth` for the login seat); the new grant restarts the clock";
 export function checkIdentityDrift(input) {
     const { live, poolAccounts } = input;
     // Short-prefix for surfaced IDs — 64-char userIDs and 36-char UUIDs are
@@ -905,6 +925,7 @@ export async function runChecks(opts = {}) {
                     (expired > 0 ? `, ${expired} expired` : '') +
                     (aliases.length === 1 ? ' (a pool of one — `dario accounts add <alias>` to load-balance)' : ''),
             });
+            checks.push(...checkRefreshGrant({ accounts: loaded.map((a) => ({ alias: a.alias, grantedAt: a.grantedAt })), now }));
             // Next-account-in-rotation surfacing. The proxy's per-request
             // selector picks by max headroom (with 7d_<family> per-model
             // bucket considered when a request's model family is known);

package/dist/health-response.d.ts

@@ -14,7 +14,15 @@
  * The HTTP status (200 healthy / 503 degraded) is identical either way, so external
  * uptime monitoring that keys on the status code is unaffected.
  */
+/** Pool-wide refresh-token grant age (refresh-grant.ts), internal-only. */
+export interface RefreshGrantSummary {
+    level: 'ok' | 'warn' | 'urgent' | 'unknown';
+    oldestAgeDays: number | null;
+    daysToWall: number | null;
+    seats: Record<string, 'ok' | 'warn' | 'urgent' | 'unknown'>;
+}
 export interface HealthStatusLike {
+    refreshGrant?: RefreshGrantSummary;
     status: string;
     canRefresh?: boolean;
     /**
@@ -25,6 +33,18 @@ export interface HealthStatusLike {
      * buildHealthResponse.
      */
     upstreamApiKeyMode?: boolean;
+    /**
+     * A stored Codex account is serving in place of the Claude pool: the proxy
+     * runs `--no-claude-auth` (pool deliberately empty) AND at least one Codex
+     * account is present, per the same presence check the codex router asks.
+     * Same reasoning as upstreamApiKeyMode — OAuth state is not evidence about
+     * serving, so an empty pool must not read as 503 (found by
+     * codex-drift-watch.yml: its --no-claude-auth proxy never passed /health).
+     * The flag ALONE is not evidence: `--no-claude-auth` with no account and no
+     * API key starts fine and can serve nothing — that stays 503 (review on
+     * #1224), which is why the caller, not this function, resolves presence.
+     */
+    codexServes?: boolean;
     expiresIn?: string;
     refreshFailures?: number;
     lastRefreshError?: string;

package/dist/health-response.js

@@ -99,7 +99,10 @@ export function buildHealthResponse(s, requestCount, includeInternal, now = Date
     // even though the suite's own traffic was being served by the API key.) The
     // probe below stays authoritative in BOTH modes, so a real failed round-trip
     // still degrades — this narrows the structural guess, not the measurement.
+    // The same holds when a Codex account serves under --no-claude-auth: the
+    // pool is empty BY DESIGN, so OAuth 'none' says nothing about liveness.
     const structurallyDead = s.upstreamApiKeyMode !== true &&
+        s.codexServes !== true &&
         (s.status === 'broken' ||
             s.status === 'none' ||
             (s.status === 'expired' && s.canRefresh === false));
@@ -131,6 +134,7 @@ export function buildHealthResponse(s, requestCount, includeInternal, now = Date
             ...(s.queue ? { queue: withStalledFor(s.queue, now) } : {}),
             ...(s.probe ? { probe: { ...s.probe, ageMs: Math.max(0, now - s.probe.checkedAt) } } : {}),
             ...(s.refreshFailures ? { refreshFailures: s.refreshFailures } : {}),
+            ...(s.refreshGrant ? { refreshGrant: s.refreshGrant } : {}),
         }
         : liveness;
     return { httpStatus, body };

package/dist/oauth.d.ts

@@ -18,6 +18,14 @@ export interface OAuthTokens {
     refreshToken: string;
     expiresAt: number;
     scopes: string[];
+    /**
+     * Epoch ms of the OAuth grant this refresh-token family descends from.
+     * Set by the login flows, preserved across refreshes (a rotation does not
+     * extend Anthropic's ~28-day refresh-token lifetime — see refresh-grant.ts).
+     * Absent on credentials minted before this field existed or imported from a
+     * Claude Code keychain, which never recorded it.
+     */
+    grantedAt?: number;
 }
 export interface CredentialsFile {
     claudeAiOauth: OAuthTokens;

package/dist/oauth.js

@@ -597,6 +597,7 @@ async function exchangeCodeWithRedirect(code, codeVerifier, state, port) {
         refreshToken: data.refresh_token,
         expiresAt: Date.now() + data.expires_in * 1000,
         scopes: data.scope?.split(' ') || ['user:inference'],
+        grantedAt: Date.now(),
     };
     await saveCredentials({ claudeAiOauth: tokens });
     return tokens;
@@ -739,6 +740,7 @@ async function exchangeCodeManual(code, codeVerifier, state) {
         refreshToken: data.refresh_token,
         expiresAt: Date.now() + data.expires_in * 1000,
         scopes: data.scope?.split(' ') || ['user:inference'],
+        grantedAt: Date.now(),
     };
     await saveCredentials({ claudeAiOauth: tokens });
     return tokens;
@@ -854,6 +856,7 @@ async function doRefreshTokens() {
             refreshToken: data.refresh_token,
             expiresAt: Date.now() + data.expires_in * 1000,
             scopes: oauth.scopes,
+            grantedAt: oauth.grantedAt,
         };
         await saveCredentials({ claudeAiOauth: tokens });
         consecutiveRefreshFailures = 0;

package/dist/pool.d.ts

@@ -73,6 +73,8 @@ export interface PoolAccount {
     identity: AccountIdentity;
     rateLimit: RateLimitSnapshot;
     requestCount: number;
+    /** Epoch ms of the OAuth grant (refresh-grant.ts); undefined when unknown. */
+    grantedAt?: number;
     /**
      * Auth-failure cool-down (dario#234). Set when an upstream returns
      * 401/403 or an `authentication_error` / `permission_error` /
@@ -198,6 +200,7 @@ export declare class AccountPool {
         expiresAt: number;
         deviceId: string;
         accountUuid: string;
+        grantedAt?: number;
     }): void;
     remove(alias: string): boolean;
     get size(): number;
@@ -288,6 +291,7 @@ export interface ReconcilableAccount {
     expiresAt: number;
     deviceId: string;
     accountUuid: string;
+    grantedAt?: number;
 }
 /**
  * Reconcile a live pool against the current on-disk account set: add or refresh

package/dist/pool.js

@@ -277,6 +277,7 @@ export class AccountPool {
             accessToken: opts.accessToken,
             refreshToken: opts.refreshToken,
             expiresAt: opts.expiresAt,
+            grantedAt: opts.grantedAt ?? existing?.grantedAt,
             identity: existing?.identity ?? {
                 deviceId: opts.deviceId,
                 accountUuid: opts.accountUuid,
@@ -626,6 +627,7 @@ export function reconcilePoolAccounts(pool, accounts) {
             expiresAt: a.expiresAt,
             deviceId: a.deviceId,
             accountUuid: a.accountUuid,
+            grantedAt: a.grantedAt,
         });
     }
     for (const existing of pool.all()) {

package/dist/proxy.js

@@ -16,6 +16,7 @@ import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCo
 import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS, CODEX_CLAIM } from './analytics.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
+import { grantAge, grantThresholds, worstGrantLevel, describeGrantAge } from './refresh-grant.js';
 import { loadAllAccounts, loadAccount, saveAccount, refreshAccountToken, resyncLoginFromCredentialsIfStale, ensureLoginCredentialsInPool, mirrorLoginToCredentials } from './accounts.js';
 import { handleAdminRequest } from './admin-api.js';
 import { createTokenBucket } from './rate-limit.js';
@@ -1393,6 +1394,7 @@ export async function startProxy(opts = {}) {
                 expiresAt: acc.expiresAt,
                 deviceId: acc.deviceId,
                 accountUuid: acc.accountUuid,
+                grantedAt: acc.grantedAt,
             });
         }
         // Startup self-heal (dario#790): eagerly refresh any account whose access
@@ -1428,10 +1430,37 @@ export async function startProxy(opts = {}) {
             }));
         }
     }
+    // Refresh-token grant watch (refresh-grant.ts). The access-token refresh
+    // below cannot save a seat whose GRANT is at the ~28-day wall — the family
+    // dies mid-refresh with invalid_grant and every request on it fails over.
+    // Say so before it happens: once per level per seat, repeated daily while it
+    // stays there, on stderr and as an OS notification.
+    const grantWatch = new Map();
+    const GRANT_NAG_MS = 24 * 60 * 60 * 1000;
+    const watchGrants = () => {
+        const now = Date.now();
+        const t = grantThresholds();
+        for (const acc of pool.all()) {
+            const age = grantAge(acc.grantedAt, now, t);
+            const prev = grantWatch.get(acc.alias);
+            if (age.level !== 'warn' && age.level !== 'urgent') {
+                grantWatch.delete(acc.alias);
+                continue;
+            }
+            if (prev && prev.level === age.level && now - prev.at < GRANT_NAG_MS)
+                continue;
+            grantWatch.set(acc.alias, { level: age.level, at: now });
+            console.warn(`[dario] refresh-token grant ${age.level.toUpperCase()} for account "${acc.alias}": ${describeGrantAge(age, t)}`);
+            osNotify(`dario: seat "${acc.alias}" refresh-token grant ${age.level}`, describeGrantAge(age, t));
+        }
+    };
+    if (!opts.noClaudeAuth)
+        watchGrants();
     // Background refresh — keep every account's token fresh without blocking requests
     const refreshInterval = setInterval(async () => {
         if (opts.noClaudeAuth)
             return; // never touch the Claude token in OpenAI-only mode
+        watchGrants();
         for (const acc of pool.all()) {
             if (acc.expiresAt < Date.now() + 45 * 60 * 1000) {
                 try {
@@ -1482,6 +1511,7 @@ export async function startProxy(opts = {}) {
                     expiresAt: acc.expiresAt,
                     deviceId: acc.deviceId,
                     accountUuid: acc.accountUuid,
+                    grantedAt: acc.grantedAt,
                 });
             }
         }
@@ -1994,10 +2024,25 @@ export async function startProxy(opts = {}) {
                     upstreamApiKey: upstreamApiKey || undefined,
                 })
                 : undefined;
+            const grantNow = Date.now();
+            const grantAges = pool.all().map((a) => ({ alias: a.alias, age: grantAge(a.grantedAt, grantNow) }));
+            const refreshGrant = grantAges.length === 0 ? undefined : {
+                level: worstGrantLevel(grantAges.map((g) => g.age.level)),
+                oldestAgeDays: grantAges.reduce((m, g) => g.age.ageDays === null ? m : Math.max(m ?? -1, g.age.ageDays), null),
+                daysToWall: grantAges.reduce((m, g) => g.age.daysToWall === null ? m : Math.min(m ?? Number.MAX_SAFE_INTEGER, g.age.daysToWall), null),
+                seats: Object.fromEntries(grantAges.map((g) => [g.alias, g.age.level])),
+            };
             const { httpStatus, body } = buildHealthResponse({
                 ...s,
+                ...(refreshGrant ? { refreshGrant } : {}),
                 version: darioVersion(),
                 upstreamApiKeyMode: !!upstreamApiKey,
+                // --no-claude-auth: the empty Claude pool is deliberate — but only a
+                // present Codex account is evidence something serves. Same presence
+                // check the codex router asks per request (#1138), so an account
+                // added or removed mid-run is reflected without a restart. Skipped
+                // entirely outside that mode so the Claude path never stats the dir.
+                codexServes: opts.noClaudeAuth === true && await hasAnyCodexAccount(),
                 ...(probe ? { probe } : {}),
                 // pool.size === 0 is single-account mode (session-id registry drives
                 // the SESSION_ID slot); a loaded pool routes via sticky bindings.
@@ -2147,6 +2192,7 @@ export async function startProxy(opts = {}) {
                 // timestamp at all. `updatedAt` was already on the snapshot; it was
                 // simply never surfaced. null means "never observed" (no response has
                 // been served on this account yet) rather than "observed at epoch 0".
+                const grant = grantAge(a.grantedAt, now);
                 return {
                     alias: a.alias,
                     util5h: a.rateLimit.util5h,
@@ -2156,6 +2202,13 @@ export async function startProxy(opts = {}) {
                     status: inCooldown ? 'auth-cooldown' : a.rateLimit.status,
                     requestCount: a.requestCount,
                     expiresInMs: Math.max(0, a.expiresAt - now),
+                    // Refresh-token grant age (refresh-grant.ts): the wall a token
+                    // refresh cannot move. null fields = grant date unknown.
+                    grantedAt: a.grantedAt ?? null,
+                    grantAgeDays: grant.ageDays,
+                    grantLevel: grant.level,
+                    refreshWallAt: grant.wallAt,
+                    daysToWall: grant.daysToWall,
                     ...(inCooldown
                         ? {
                             lastAuthFailureAt: a.lastAuthFailureAt,

package/dist/refresh-grant.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Refresh-token grant age.
+ *
+ * Anthropic's OAuth refresh token has a hard lifetime measured from the
+ * ORIGINAL grant, not from the last rotation. A seat that refreshed every 8h
+ * for four weeks still died with `invalid_grant "Refresh token expired"`
+ * 28 days 10 hours after its grant (observed 2026-09-05; the only data point,
+ * hence the conservative defaults below). The token itself is opaque and the
+ * token endpoint reports no refresh expiry, so the calendar is the only
+ * signal — and until this module existed dario did not keep the calendar:
+ * `grantedAt` is recorded by every code path that performs a grant and
+ * preserved across refreshes, and every surface (`/health`, `/accounts`,
+ * `dario accounts list`, `dario doctor`, the background refresh loop) reads
+ * the age through here.
+ *
+ * Levels:
+ *   ok      age < warn
+ *   warn    warn ≤ age < urgent   — re-grant this week
+ *   urgent  urgent ≤ age          — re-grant today; the wall is ~lifetime
+ *   unknown no grantedAt          — seat minted before this field existed
+ *                                   (or hand-installed); re-grant to start
+ *                                   the clock
+ *
+ * All three thresholds are env-tunable so an operator who observes a
+ * different wall can move them without a release:
+ *   DARIO_REFRESH_GRANT_LIFETIME_DAYS (28)
+ *   DARIO_REFRESH_GRANT_WARN_DAYS     (21)
+ *   DARIO_REFRESH_GRANT_URGENT_DAYS   (26)
+ */
+export type GrantLevel = 'ok' | 'warn' | 'urgent' | 'unknown';
+export interface GrantThresholds {
+    lifetimeDays: number;
+    warnDays: number;
+    urgentDays: number;
+}
+export interface GrantAge {
+    level: GrantLevel;
+    /** Whole days since the grant; null when unknown. */
+    ageDays: number | null;
+    /** Epoch ms of the projected wall (grantedAt + lifetime); null when unknown. */
+    wallAt: number | null;
+    /** Whole days until the wall (negative once past it); null when unknown. */
+    daysToWall: number | null;
+}
+/** Thresholds from the environment, with the documented defaults. Ordering is
+ *  enforced (warn ≤ urgent ≤ lifetime) so a misconfigured pair can never make
+ *  a seat skip a level or page after the wall. */
+export declare function grantThresholds(env?: NodeJS.ProcessEnv): GrantThresholds;
+/** Age a single grant. `grantedAt` undefined/null/non-finite → unknown. */
+export declare function grantAge(grantedAt: number | null | undefined, now: number, t?: GrantThresholds): GrantAge;
+/** The level a pool reports as a whole: the worst seat wins. `unknown` ranks
+ *  between ok and warn — a pool whose seats are all unstamped is not healthy
+ *  knowledge, but it is not a page either. */
+export declare function worstGrantLevel(levels: readonly GrantLevel[]): GrantLevel;
+/** One-line human summary, shared by `accounts list` and doctor. */
+export declare function describeGrantAge(a: GrantAge, t?: GrantThresholds): string;

package/dist/refresh-grant.js

@@ -0,0 +1,80 @@
+/**
+ * Refresh-token grant age.
+ *
+ * Anthropic's OAuth refresh token has a hard lifetime measured from the
+ * ORIGINAL grant, not from the last rotation. A seat that refreshed every 8h
+ * for four weeks still died with `invalid_grant "Refresh token expired"`
+ * 28 days 10 hours after its grant (observed 2026-09-05; the only data point,
+ * hence the conservative defaults below). The token itself is opaque and the
+ * token endpoint reports no refresh expiry, so the calendar is the only
+ * signal — and until this module existed dario did not keep the calendar:
+ * `grantedAt` is recorded by every code path that performs a grant and
+ * preserved across refreshes, and every surface (`/health`, `/accounts`,
+ * `dario accounts list`, `dario doctor`, the background refresh loop) reads
+ * the age through here.
+ *
+ * Levels:
+ *   ok      age < warn
+ *   warn    warn ≤ age < urgent   — re-grant this week
+ *   urgent  urgent ≤ age          — re-grant today; the wall is ~lifetime
+ *   unknown no grantedAt          — seat minted before this field existed
+ *                                   (or hand-installed); re-grant to start
+ *                                   the clock
+ *
+ * All three thresholds are env-tunable so an operator who observes a
+ * different wall can move them without a release:
+ *   DARIO_REFRESH_GRANT_LIFETIME_DAYS (28)
+ *   DARIO_REFRESH_GRANT_WARN_DAYS     (21)
+ *   DARIO_REFRESH_GRANT_URGENT_DAYS   (26)
+ */
+const DAY_MS = 86_400_000;
+function envDays(name, fallback, env) {
+    const raw = env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Thresholds from the environment, with the documented defaults. Ordering is
+ *  enforced (warn ≤ urgent ≤ lifetime) so a misconfigured pair can never make
+ *  a seat skip a level or page after the wall. */
+export function grantThresholds(env = process.env) {
+    const lifetimeDays = envDays('DARIO_REFRESH_GRANT_LIFETIME_DAYS', 28, env);
+    const urgentDays = Math.min(envDays('DARIO_REFRESH_GRANT_URGENT_DAYS', 26, env), lifetimeDays);
+    const warnDays = Math.min(envDays('DARIO_REFRESH_GRANT_WARN_DAYS', 21, env), urgentDays);
+    return { lifetimeDays, warnDays, urgentDays };
+}
+/** Age a single grant. `grantedAt` undefined/null/non-finite → unknown. */
+export function grantAge(grantedAt, now, t = grantThresholds()) {
+    if (grantedAt === undefined || grantedAt === null || !Number.isFinite(grantedAt) || grantedAt <= 0) {
+        return { level: 'unknown', ageDays: null, wallAt: null, daysToWall: null };
+    }
+    const ageDays = Math.floor(Math.max(0, now - grantedAt) / DAY_MS);
+    const wallAt = grantedAt + t.lifetimeDays * DAY_MS;
+    const daysToWall = Math.floor((wallAt - now) / DAY_MS);
+    const level = ageDays >= t.urgentDays ? 'urgent' : ageDays >= t.warnDays ? 'warn' : 'ok';
+    return { level, ageDays, wallAt, daysToWall };
+}
+const LEVEL_RANK = { ok: 0, unknown: 1, warn: 2, urgent: 3 };
+/** The level a pool reports as a whole: the worst seat wins. `unknown` ranks
+ *  between ok and warn — a pool whose seats are all unstamped is not healthy
+ *  knowledge, but it is not a page either. */
+export function worstGrantLevel(levels) {
+    let worst = 'ok';
+    for (const l of levels)
+        if (LEVEL_RANK[l] > LEVEL_RANK[worst])
+            worst = l;
+    return worst;
+}
+/** One-line human summary, shared by `accounts list` and doctor. */
+export function describeGrantAge(a, t = grantThresholds()) {
+    if (a.level === 'unknown' || a.ageDays === null || a.daysToWall === null) {
+        return 'grant date unknown — re-grant to start the ~' + t.lifetimeDays + 'd refresh-token clock';
+    }
+    const wall = a.daysToWall >= 0 ? `~${a.daysToWall}d to the ~${t.lifetimeDays}d wall` : `${-a.daysToWall}d PAST the ~${t.lifetimeDays}d wall`;
+    switch (a.level) {
+        case 'ok': return `grant ${a.ageDays}d old, ${wall}`;
+        case 'warn': return `grant ${a.ageDays}d old, ${wall} — re-grant this week`;
+        case 'urgent': return `grant ${a.ageDays}d old, ${wall} — re-grant TODAY or the seat dies mid-refresh`;
+    }
+}

package/docs/integrations/agent-compat.md

@@ -14,7 +14,7 @@ For a one-page status table of every tool dario supports — working / inferred
 | GitHub Copilot | `run_in_terminal`, `insert_edit_into_file`, `semantic_search`, `codebase_search`, `list_dir`, `fetch_webpage` |
 | OpenHands | `execute_bash`, `str_replace_editor` |
 | OpenClaw | `exec`, `process`, `web_search`, `web_fetch`, `browser`, `message` |
-| hands ([askalf/hands](https://github.com/askalf/hands)) | Anthropic beta computer-use tools (`computer`, `bash`, `str_replace_based_edit_tool`) — auto-preserved via system-prompt identity match (v3.33.0) |
+| hands ([askalf/hands](https://github.com/askalf/hands), archived 2026-09-06) | Anthropic beta computer-use tools (`computer`, `bash`, `str_replace_based_edit_tool`) — auto-preserved via system-prompt identity match (v3.33.0) |
 | Hermes Agent (Nous Research) | `terminal`, `process`, `read_file`, `write_file`, `patch`, `search_files`, `web_search`, `web_extract`, `todo` mapped directly. Hermes-specific tools (`browser_*`, `vision_analyze`, `image_generate`, `skill_*`, `memory`, `session_search`, `cronjob`, `send_message`, `ha_*`, `mixture_of_agents`, `delegate_task`, `execute_code`, `text_to_speech`) have no CC equivalent and auto-preserve through the identity detector. Also consider `--max-tokens=client` so Hermes's 64k/128k per-model caps survive dario's outbound pin. |
 
 Text-tool clients (Cline / Kilo Code / Roo Code and forks) are auto-detected via system-prompt identity markers and automatically flipped into preserve-tools mode, because mixing CC's `tools` array with their XML protocol makes the model emit `<function_calls><invoke>` that their parsers can't read. The same identity path also catches `hands` (askalf's computer-use agent) — its tool names overlap with `TOOL_MAP` but its schemas diverge, so identity match → preserve-tools is the only correct routing. If you run dario specifically for wire-level fidelity and would rather pick `--preserve-tools` yourself, `--no-auto-detect` (v3.20.1, aka `--no-auto-preserve`) disables the heuristic — explicit operator choice then wins.
@@ -208,9 +208,9 @@ OpenClaw uses the standard `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` env vars
 
 For a full end-to-end walkthrough — auth-profiles handling, classifier-filter protection, subscription-billing verification, multi-account pool, and the gotchas that bite first-time users — see [`openclaw-walkthrough.md`](./openclaw-walkthrough.md).
 
-### hands
+### hands (archived)
 
-[hands](https://github.com/askalf/hands) is a sister project to dario — a local computer-use agent that drives your OS through its native shell instead of a screenshot loop. Two modes: Claude Login (uses the `claude` CLI directly, no dario required) and SDK mode (audit-logged, supports `--dry-run`, routes through dario for $0 per task).
+[hands](https://github.com/askalf/hands) (archived 2026-09-06; the wire-format notes below still apply to any computer-use agent) was a sister project to dario — a local computer-use agent that drives your OS through its native shell instead of a screenshot loop. Two modes: Claude Login (uses the `claude` CLI directly, no dario required) and SDK mode (audit-logged, supports `--dry-run`, routes through dario for $0 per task).
 
 ```bash
 # SDK mode — env vars route the Anthropic SDK through dario

package/docs/integrations/compat-matrix.md

@@ -18,7 +18,7 @@ Status legend:
 | **Zed** | Anthropic | Claude backend | ✅ Working | [`agent-compat.md#zed`](./agent-compat.md#zed) |
 | **OpenHands** | Anthropic | Claude backend | ✅ Working | Full walkthrough: [`openhands-walkthrough.md`](./openhands-walkthrough.md) |
 | **OpenClaw** | Anthropic | Claude backend | ✅ Working | Full walkthrough: [`openclaw-walkthrough.md`](./openclaw-walkthrough.md). Identity-detected for preserve-tools. |
-| **hands** | Anthropic | Claude backend | ✅ Working | Full walkthrough: [`hands-walkthrough.md`](./hands-walkthrough.md). Identity-detected. |
+| **hands** (archived) | Anthropic | Claude backend | ✅ Working | Repo archived 2026-09-06. Walkthrough kept for the wire format: [`hands-walkthrough.md`](./hands-walkthrough.md). Identity-detected. |
 | **CC sub-agents** | Anthropic | Claude backend | ✅ Working | `dario subagent install` registers a CC sub-agent that exposes `dario doctor` and other read-only diagnostics inside any CC session. [`sub-agent.md`](./sub-agent.md) |
 | **Claude Agent SDK** | Anthropic | Claude backend | ✅ Working | `baseURL: 'http://localhost:3456'` on the `Anthropic` client. SDK examples in [`usage.md`](./usage.md). |
 | **MCP clients (any)** | MCP / JSON-RPC | dario as MCP server | ✅ Working | `dario mcp` exposes dario as a read-only MCP server. [`mcp-server.md`](./mcp-server.md) |

package/docs/integrations/cordon.md

@@ -0,0 +1,97 @@
+# dario + cordon: share a subscription without leaking PII
+
+dario lets a team share one Claude or ChatGPT subscription through a single API endpoint. That endpoint sees every prompt. Put [cordon](https://github.com/askalf/cordon) in front of it and raw email addresses, phone numbers, card numbers, SSNs and API keys are tokenized **before** they reach dario, the provider, or the provider's logs. The client still gets the real values back in the reply.
+
+```
+client ──▶ cordon :8080 ──▶ dario :3456 ──▶ Anthropic / OpenAI
+             │ redact / tokenize          │ subscription auth, pool, failover
+             └ restore in the reply       └ nothing changes here
+```
+
+Both speak the Anthropic and OpenAI wire formats, so nothing about your clients changes except the base URL.
+
+## Compose
+
+```yaml
+services:
+  dario:
+    image: ghcr.io/askalf/dario:latest
+    environment:
+      DARIO_API_KEY: ${DARIO_API_KEY}     # required, see docker.md
+      DARIO_HOST: 0.0.0.0
+    volumes:
+      - dario_data:/home/dario/.dario
+    expose: ["3456"]
+
+  cordon:
+    # cordon does not publish an image yet; build it from the repo.
+    build: https://github.com/askalf/cordon.git
+    environment:
+      ANTHROPIC_BASE: http://dario:3456
+      OPENAI_BASE: http://dario:3456
+      DEFAULT_MODE: reversible           # de-identify upstream, restore in the reply
+      FAIL_MODE: closed                  # if cordon cannot redact, it refuses, never forwards raw
+      ACTIVE_SETS: pii,pci,secrets       # add phi if you need MRN/date detection
+      ADMIN_TOKEN: ${CORDON_ADMIN_TOKEN}
+      AUDIT_LOG: /app/data/audit.jsonl
+      POLICY_STORE: /app/data/policies.json
+    volumes:
+      - cordon_data:/app/data
+    ports: ["8080:8080"]                 # the only port clients need
+
+volumes:
+  dario_data:
+  cordon_data:
+```
+
+Only cordon is published. dario stays reachable from cordon alone.
+
+## Point clients at cordon
+
+Use the same dario key you already hand out. cordon forwards `x-api-key` and `authorization` verbatim and never terminates auth.
+
+```bash
+# Anthropic-compatible clients
+export ANTHROPIC_BASE_URL=http://localhost:8080
+export ANTHROPIC_API_KEY=$DARIO_API_KEY
+
+# OpenAI-compatible clients
+export OPENAI_BASE_URL=http://localhost:8080/v1
+export OPENAI_API_KEY=$DARIO_API_KEY
+```
+
+## What you get
+
+```bash
+curl localhost:8080/v1/messages \
+  -H "x-api-key: $DARIO_API_KEY" -H 'anthropic-version: 2023-06-01' \
+  -H 'content-type: application/json' \
+  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user",
+       "content":"draft a reply to jane@acme.com about card 4012-8888-8888-1881"}]}'
+```
+
+| | value |
+|---|---|
+| the model sees | `draft a reply to <EMAIL_7F3A2B_1> about card <CREDIT_CARD_7F3A2B_1>` |
+| the client gets | the reply with `jane@acme.com` and the card number restored |
+| response headers | `X-Redacted: 2`, `X-Redacted-Types: EMAIL:1,CREDIT_CARD:1` |
+| audit log | counts and types per request, hash-chained, never values |
+
+Streaming works in reversible mode; tokens are restored as they arrive.
+
+## Per-request control
+
+| header | effect |
+|---|---|
+| `X-Redact-Mode: strip` | irreversible placeholders, nothing restored |
+| `X-Redact-Mode: off` | passthrough, still logged as a bypass |
+| `X-Redact-Sets: pii,secrets` | narrow the detector set for this call |
+| `X-Tenant: <id>` | pick a tenant policy instead of deriving it from the key |
+
+Detection is deterministic (regex plus checksum validators, no ML), so a redaction never silently rewrites prose that isn't PII. Per-tenant policies and the audit chain are documented in the [cordon README](https://github.com/askalf/cordon#per-tenant-policy--admin).
+
+## What this does not do
+
+- It does not hide the prompt from dario's own logs before redaction, because there is nothing before redaction: cordon is the first hop.
+- It does not replace provider-side data handling terms. It reduces what those terms apply to.
+- `phi` is off by default. Its date detector redacts framework context (version strings, changelog dates) in coding prompts. Turn it on for clinical workloads only.

package/docs/integrations/hands-walkthrough.md

@@ -1,5 +1,7 @@
 # dario + hands — battletested setup
 
+> **Note:** hands was archived 2026-09-06; this walkthrough is kept for the wire-format details, which still apply to any computer-use agent.
+
 End-to-end walkthrough for running [hands](https://github.com/askalf/hands) — a local computer-use agent that drives your OS through its native shell — through dario so the model spend bills against your Claude Pro / Max subscription instead of per-token overage on the computer-use beta. Covers install → mode selection → first run → verification → the gotchas that bite first-time users.
 
 This is the **first-party** walkthrough. hands is one of dario's sister projects under [askalf](https://github.com/askalf), so unlike the OpenHands / OpenClaw guides where dario is *integrating* with someone else's tool, this is the canonical end-to-end stack we run ourselves. Most of the integration work has already been done on both ends: dario v3.33.0 auto-detects hands via system-prompt identity match and preserves the computer-use beta tools (`computer`, `bash`, `str_replace_based_edit_tool`) without you needing any flag.

package/docs/multi-account-pool.md

@@ -92,3 +92,20 @@ curl http://localhost:3456/analytics    # per-account / per-model stats, burn ra
 ```
 
 Every request carries a `billingBucket` field (`subscription` / `subscription_fallback` / `extra_usage` / `api` / `unknown`) so you can see which bucket each request billed against and a `subscriptionPercent` headline number tells you at a glance whether dario is actually routing through your subscription or silently falling to API overage.
+
+## Refresh-token grant age
+
+A token refresh keeps the access token fresh. It does not move the wall on the refresh token: Anthropic expires the refresh-token family about **28 days after the original OAuth grant**, rotation or not. A seat that refreshed every 8h for four weeks still died with `invalid_grant "Refresh token expired"` 28d 10h after its grant (2026-09-05), and every request on it failed over silently.
+
+dario records `grantedAt` on every grant (`dario login`, `dario accounts add`, the admin login flow), preserves it across refreshes, and ages it everywhere the pool is inspected:
+
+```bash
+dario accounts list        # "grant 12d old, ~16d to the ~28d wall" under each seat
+dario doctor               # "Refresh grant" row: warn at 21d, fail at 26d, info when unknown
+curl http://localhost:3456/accounts   # grantedAt, grantAgeDays, grantLevel, refreshWallAt, daysToWall per seat
+curl http://localhost:3456/health     # refreshGrant: { level, oldestAgeDays, daysToWall, seats } (trusted callers)
+```
+
+The proxy also warns on stderr and sends an OS notification when a seat crosses `warn` or `urgent` (once per level, repeated daily while it stays there). A seat minted before this field existed, or imported from a Claude Code keychain, reports `unknown` — re-grant it to start the clock.
+
+Re-grant a seat before the wall with `dario accounts add <alias>` (remove the old entry first) or `dario login --force-reauth` for the `login` seat. Thresholds: `DARIO_REFRESH_GRANT_LIFETIME_DAYS` (28), `DARIO_REFRESH_GRANT_WARN_DAYS` (21), `DARIO_REFRESH_GRANT_URGENT_DAYS` (26).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.0.25",
+  "version": "6.0.26",
   "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
   "type": "module",
   "bin": {