atris 3.58.5 → 3.58.6

package/atris/skills/x-search/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: x-search
 description: "X/Twitter search via xAI Grok API. Use when user wants to search tweets, monitor topics, find viral posts, or run social listening. Costs 5 credits per search. Triggers on x search, tweet search, twitter search, social listening, revenue intel, viral tweets."
-version: 2.4.0
+version: 2.4.1
 tags:
   - x-search
   - social
@@ -33,7 +33,7 @@ login
 ```
 
 1. Login: stored login, then `atris login --agent` if needed. Never paste tokens. Never `/auth/cli`.
-2. Search: `atris x-search "QUERY"`. Always billed (5 credits). Prints to stdout. Rich ephemeral prints one apply next-step, one inferred check plus `score: 0`, then one `next: atris youtube search "<query>"` (person mode uses `--name`), and writes nothing. Thin ephemeral prints `check: fill this` then that youtube-search next, and writes nothing. Empty successful pull (no tweets) prints one `next: atris youtube search " "`. Explicit refund or failed search writes nothing extra.
+2. Search: `atris x-search "QUERY"`. Always billed (5 credits). Prints to stdout. Rich ephemeral prints one apply next-step, one inferred check plus `score: 0`, then one `next: atris youtube search "<query>"` (person mode uses `--name`), and writes nothing. Thin ephemeral prints `check: fill this` then that youtube-search next, and writes nothing. Empty successful pull (no tweets) prints one `next: atris youtube search " "`. Explicit refund or failed search writes nothing extra. Empty, 502, 401, or 402 with unused credits print Credits when present and do not say refunded unless credits_refunded is explicit. A 401 that remints and retries prints those same credit lines from the first payload before the retry. `--json` stays quiet.
 3. `--save` only when you want a brief. Rich results (a number-with-units or a named mechanism) file the brief, mint `atris/experiments/x-search-<slug>/`, write one Apply that names that pack and the keep rule, and prove that fixture starts at score 0. Thin `--save` prints `thin: no number or named mechanism. no brief.` and writes nothing. `--save` does not print a youtube-search next-step.
 4. Stop. `--json`, explicit refund, or failed search does not print apply, check, score, or youtube-search next-step.
 

package/atris/skills/youtube/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: youtube
-description: "YouTube discovery and learning. Get watch permalinks with atris youtube search QUERY (free, local ytsearch/yt-dlp). On 429 the CLI already retries; use cached rows if printed, else STOP. Never run --paid after a 429. --paid only when the user explicitly asked to buy permalinks (5 credits). After a URL is picked, atris youtube notes URL (free, ephemeral unless --save). atris youtube process only to store knowledge (5 credits). Never paste tokens. Never /auth/cli. Mint with atris login --agent from a stored login. Never summarize a video from model memory. Triggers on: youtube search, find videos, paid youtube search, any youtube.com or youtu.be link, youtube, video, watch this, notes on this."
-version: 2.16.0
+description: "YouTube discovery and learning. Get watch permalinks with atris youtube search QUERY (free, local ytsearch/yt-dlp). On 429 use printed rows if any; else the CLI retries once, then cached rows if printed, else STOP. Never run --paid after a 429. --paid only when the user explicitly asked to buy permalinks (5 credits). After a URL is picked, atris youtube notes URL (free, ephemeral unless --save). atris youtube process only to store knowledge (5 credits). Never paste tokens. Never /auth/cli. Mint with atris login --agent from a stored login. Never summarize a video from model memory. Triggers on: youtube search, find videos, paid youtube search, any youtube.com or youtu.be link, youtube, video, watch this, notes on this."
+version: 2.18.18
 tags:
   - youtube
   - research
@@ -18,12 +18,13 @@ Hard path. Follow in order. Soft memory does not override this.
 ```
 search QUERY (free)
     |
-   rows --> rich: one failing check (score 0); thin: check: fill this
-        --> next: atris youtube teach <first-url>
+   rows --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
+        --> thin: check: fill this, then next: atris youtube teach <first-url>
         --> --json stays quiet
     |
-   429 --> CLI already retried once
-        --> cached rows printed? use them
+   429 --> printed rows? use them (no retry)
+        --> else CLI retries once
+        --> cached rows printed? use them (same rich mint or thin check as live rows)
         --> rate-limit sentence printed? STOP
              do not run --paid
     |
@@ -33,22 +34,34 @@ search QUERY (free)
     |                 then next: atris youtube teach <same-url>
     |                 --json stays quiet
     |                 --save files brief + pack-named apply when notes have a number or named mechanism; a multi-url --save batch proves the first saved pack the same way single-url --save does; thin --save refuses
+    |                 playlist expand keeps printed yt-dlp rows on 429
+    |                 notes keep a written yt_<id>.md (and ytnotes keeps a written manual or auto en / en-orig / en-US / en-GB VTT) when yt-dlp exits 429 or a later error, or --print is empty
+    |                 watch, youtu.be, shorts, embed, live, /e/, and youtube-nocookie embed urls all resolve the same video id for that keep
+    |                 a copied #t= timestamp still finds yt_<id>.en.vtt
+    |                 a watch?v=&list= copy still finds yt_<video>.en.vtt when -J dumps playlist JSON
     |            or teach URL [--section N] (one chapter: claim numbers, named mechanisms, one check; free unless --save)
+    |                 printed yt-dlp metadata is a hit even on 429
+    |                 a written VTT or clean.txt is used when the caption URL fetch fails, `-J` stdout is empty, or `-J` dumps a playlist for a watch?v=&list= URL
     |                 a taught section that is not last prints next: recap TEXT or skip
     |                 last section: rich ephemeral apply, failing check, and score 0, then next: atris youtube watch tick; save pack keep stays; no recap next
     |                 next --section refuses until recap/skip
     |                 owed prints unpaid check; successful unlock prints next section command
     |                 bare teach resumes owed, or prints a start command if nothing is owed
     |
+   persist a rich lesson? --> learn log '{"type":"pattern","key":"...","insight":"..."}'
+                           --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
+                           --> thin: jsonl only
+
    write one Apply (claimable) before process
     |
    store knowledge? --> process URL (5 credits)
-                    --> rich: one failing check (score 0); thin: check: fill this; --json stays quiet
+                    --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
+                    --> thin: check: fill this; --json stays quiet
 
 watch add --> next: atris youtube watch tick
 watch tick --> briefs new videos
-           --> if briefed: rich pack-named apply + failing measure.py (score 0), then next: experiments keep
-           -->            thin: check: fill this, then next: atris youtube teach <first-briefed-url>
+           --> if briefed: first rich brief mints pack-named apply + failing measure.py (score 0), then next: experiments keep
+           -->            all thin: check: fill this, then next: atris youtube teach <first-briefed-url>
            --> 0 briefed, no channels: next: atris youtube watch add <channel-url-or-@handle>
            --> 0 briefed, channels exist: next: atris youtube search " "
 
@@ -58,18 +71,18 @@ digest --> files brief + claimable journal
 
 --paid QUERY only if the user asked to buy permalinks
     |
-   rows --> rich: one failing check (score 0); thin: check: fill this
-        --> next: atris youtube teach <first-url>
-        --> --json stays quiet
+   rows --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
+        --> thin: check: fill this, then next: atris youtube teach <first-url>
+        --> --json stays quiet and writes no pack
 login: atris login --agent from a stored login
 never paste tokens, never /auth/cli
 ```
 
-1. Get watch permalinks: `atris youtube search QUERY` (free). A rich hit prints one inferred check plus `score: 0`. A thin hit prints `check: fill this`. Then one next teach command.
-2. If 429: wait/retry is already in the CLI. If it prints cached rows, use those. If it prints `youtube rate-limited local search. do not use --paid as a fallback; retry later.`, STOP. Do not run `--paid`.
+1. Get watch permalinks: `atris youtube search QUERY` (free). A rich hit mints `atris/experiments/search-<query>/`, writes one pack-named Apply, and prints `score: 0` only when that Apply starts failing. A thin hit prints `check: fill this`, then one next teach command. `--json` stays quiet and writes no pack.
+2. If 429: use any rows already printed. If none, wait/retry is already in the CLI. If it prints cached rows, use those. Cached rows mint or print the same rich or thin gate as a live hit. If it prints `youtube rate-limited local search. do not use --paid as a fallback; retry later.`, STOP. Do not run `--paid`.
 3. `--paid` only when the user explicitly asked to buy permalinks. The CLI hard-refuses `--paid` when the free cache still has a fresh same-query hit.
-4. `atris youtube notes URL` after a URL is picked (free). Notes is ephemeral unless `--save`. Rich ephemeral prints one apply next-step and one failing check (`score: 0`), then one `next: atris youtube teach <same-url>`, and writes no files. Thin ephemeral prints `check: fill this` instead of inventing a check. A playlist or multi-url batch does the same for the first successful item only. `--json` stays quiet on the check and the teach next-step. Rich `--save` files the brief, mints `atris/experiments/notes-<id>/`, writes one Apply, and prints `score: 0` only when that Apply starts failing. A rich multi-url `--save` batch proves that failing baseline for the first saved pack only; thin `--save` (no number-with-units and no named mechanism) refuses with no brief and exit 2. Do not auto `--paid`.
-5. Write one Apply (change + receipt) before `atris youtube process`. Process still requires a filled Apply (so you `--save` a rich brief, fill Apply, then process).
+4. `atris youtube notes URL` after a URL is picked (free). Notes is ephemeral unless `--save`. Rich ephemeral prints one apply next-step and one failing check (`score: 0`), then one `next: atris youtube teach <same-url>`, and writes no files. Thin ephemeral prints `check: fill this` instead of inventing a check. A playlist or multi-url batch does the same for the first successful item only. A playlist expand that prints video rows keeps them even when yt-dlp exits 429. A notes run that already wrote `yt_<id>.md` keeps that lesson even when the runner exits 429 or a later error, so the learner gate and rich `--save` mint still run. Watch, youtu.be, shorts, embed, live, /e/, and youtube-nocookie embed urls all resolve the same video id, so empty-JSON teach/process and notes keep still find that file. A copied watch?v=&list= URL still finds yt_<video>.en.vtt when -J dumps playlist JSON. A copied #t= timestamp still finds the same yt_<id> file. The bundled ytnotes script does the same for a written manual or auto en, en-orig, en-US, or en-GB VTT plus printed metadata. `--json` stays quiet on the check and the teach next-step. Rich `--save` files the brief, mints `atris/experiments/notes-<id>/`, writes one Apply, and prints `score: 0` only when that Apply starts failing. A rich multi-url `--save` batch proves that failing baseline for the first saved pack only; thin `--save` (no number-with-units and no named mechanism) refuses with no brief and exit 2. Do not auto `--paid`.
+5. Write one Apply (change + receipt) before `atris youtube process`. Process still requires a filled Apply (so you `--save` a rich brief, fill Apply, then process). A rich analysis then mints `atris/experiments/process-<id>/`, writes one pack-named Apply, and prints `score: 0` only when that Apply starts failing. Thin analysis prints `check: fill this`. `--json` stays quiet. 401, 402, or 502 print Credits when present and say credits refunded only when the server marks a refund. A local-transcript 502 that then retries cloud prints those same credit lines from the first payload before the retry. A 401 that remints and retries prints those same credit lines from the first payload before the retry.
 6. Never paste tokens. Never `/auth/cli`. Mint with `atris login --agent` from a stored login.
 
 If the user says "find videos", "search youtube", or "get youtube links" → search. If they say "learn from", "notes on", "alpha", or "rabbit hole" → notes. If they say "process", "store", "add to knowledge" → process. "Buy permalinks" or "paid search" is the only ask that unlocks `--paid`.
@@ -89,7 +102,7 @@ if ! command -v atris &> /dev/null; then
   npm install -g atris
 fi
 
-echo "Ready. Feature map: free search, 429 cache-or-stop, notes, then process."
+echo "Ready. Feature map: free search, 429 printed-rows or cache-or-stop, notes, then process."
 ```
 
 ---
@@ -104,7 +117,7 @@ atris youtube search "MCP agents" --json
 
 Uses `ytsearch` on PATH when present, else bundled `scripts/det/ytsearch`, else `yt-dlp --flat-playlist --print` with `ytsearchN:`. No credits. No `/agent/process_youtube` call. A rich hit prints one inferred check plus `score: 0`. A thin hit prints `check: fill this`. Then one next: `atris youtube teach <first-url>`. `--json` stays quiet.
 
-On 429 the CLI retries once, then serves `~/.atris/youtube-search-cache.json` if the same query is younger than one hour. If it prints the rate-limit sentence, stop. Do not run `--paid`.
+On 429, printed rows are a hit (no retry). If stdout is empty the CLI retries once, then serves `~/.atris/youtube-search-cache.json` if the same query is younger than one hour. A cache reprint prints the same rich or thin check as a live hit. If it prints the rate-limit sentence, stop. Do not run `--paid`.
 
 ## Paid search (5 credits, opt-in buy only)
 
@@ -115,17 +128,18 @@ atris youtube search --paid "MCP agents 2026"
 atris youtube search --paid "MCP agents" --limit 10
 ```
 
-Requires a stored login, then `atris login --agent`. The CLI mints a youtube-scope agent token from disk the same way as `atris youtube process` and `atris x-search`. Never `/auth/cli`. Never paste tokens. Prints `title | watch permalink` plus credits. A rich hit prints one inferred check plus `score: 0`. A thin hit prints `check: fill this`. Then one next: `atris youtube teach <first-url>`. `--json` stays quiet. Empty or failed searches refund.
+Requires a stored login, then `atris login --agent`. The CLI mints a youtube-scope agent token from disk the same way as `atris youtube process` and `atris x-search`. Never `/auth/cli`. Never paste tokens. Prints `title | watch permalink` plus credits. A rich hit mints `atris/experiments/search-<query>/`, writes one pack-named Apply, and prints `score: 0` only when that Apply starts failing. A thin hit prints `check: fill this`, then one next teach command. `--json` stays quiet and writes no pack. Empty, 502, 401, or 402 with unused credits do not claim a refund unless credits_refunded is explicit.
 
 Line contract:
 
 ```text
-title | channel | duration | views | upload_date | https://youtu.be/ID
-check: <inferred or fill this>
-next: atris youtube teach "<first-url>"
+title | https://www.youtube.com/watch?v=ID
+Credits: N used, M remaining
+next: atris experiments keep search-<query>
+score: 0
 ```
 
-`upload_date` is `YYYYMMDD` (or `NA`) so callers can apply a freshness gate (for example last 6 weeks). `--json` stays machine-quiet. After the user picks a URL, run notes (free) or process (5 credits).
+A thin paid hit prints `check: fill this` and `next: atris youtube teach "<first-url>"` instead of the keep next. `--json` stays machine-quiet. After the user picks a URL, run notes (free) or process (5 credits).
 
 ---
 
@@ -246,18 +260,18 @@ Two layers, never mixed. The reply the person reads is flowing prose: ideas, spe
 
 `atris youtube search --paid` posts `{query, limit}` to `/youtube/search` with bearer auth. Agent tokens need the youtube scope. This is an opt-in buy, not a 429 fallback.
 
-`atris youtube` process first tries local transcript extraction with `yt-dlp`. It sends timestamped `transcript_text` to `/agent/process_youtube` with `cache_transcript=false`. If local transcript processing fails with a retryable error, it falls back to cloud video processing. Use `--json` to inspect `metadata.processing_method` and `metadata.transcript_source`.
+`atris youtube` process first tries local transcript extraction with `yt-dlp`. It sends timestamped `transcript_text` to `/agent/process_youtube` with `cache_transcript=false`. A written VTT or clean.txt in the notes work dir is a local hit even when `-J` stdout is empty or the caption URL fetch fails, so process does not jump to paid cloud video for that case. If local transcript processing fails with a retryable error, it falls back to cloud video processing. Use `--json` to inspect `metadata.processing_method` and `metadata.transcript_source`.
 
 ---
 
 ## Billing
 
 - **Search: 0 credits** (local discovery)
-- **Paid search: 5 credits** (`--paid`; refund on empty or fail)
+- **Paid search: 5 credits** (`--paid`; print credits refunded only when the server marks a refund. A 401 that remints and retries prints those same credit lines from the first payload before the retry. `--json` stays quiet.)
 - **Notes: 0 credits** (local captions + engine)
 - **Process: 5 credits per video** (flat rate, any length)
 - Credits deducted before processing
-- **Full refund** if Gemini fails or returns an error
+- Process 200/401/402/502 print Credits when present and say credits refunded only when `credits_refunded` is explicit. A local-transcript 502 that then retries cloud prints the same lines from the first payload. A 401 that remints and retries prints the same lines from the first payload. Unused `credits_used: 0` on a 200 is not a refund.
 - Insufficient credits returns 402 with your current balance
 
 ---
@@ -269,9 +283,11 @@ Two layers, never mixed. The reply the person reads is flowing prose: ideas, spe
 | `401` | Token expired/invalid | `atris login --agent` from a stored login |
 | `402` | Not enough credits | Check balance, purchase at atris.ai |
 | `400` | Invalid YouTube URL | Check URL format |
-| `502` | Transcript or cloud processing failed | Retry; credits auto-refunded when backend fails |
+| `502` | Transcript or cloud processing failed | Retry; print credits refunded only when the server marks a refund |
 | search exit 2 | ytsearch/yt-dlp missing or no results | Install yt-dlp, or put ytsearch on PATH |
-| search 429 | YouTube rate-limited local search | CLI already retried; use cached rows if printed; if the rate-limit sentence prints, STOP; do not use --paid |
+| search 429 | YouTube rate-limited local search | use printed rows if any; else CLI already retried; use cached rows if printed (same rich/thin check as a live hit); if the rate-limit sentence prints, STOP; do not use --paid |
+| teach 429 | YouTube rate-limited local metadata | use printed yt-dlp JSON if it parses; if the caption URL fetch fails or `-J` stdout is empty or broken, use a written VTT or clean.txt from the notes work dir; no written caption still fails; do not use process as a fallback |
+| notes 429 | YouTube rate-limited local captions | use a written yt_<id>.md if it exists; ytnotes keeps a written manual or auto en / en-orig / en-US / en-GB VTT plus printed metadata, or a VTT written in the same run when print is empty, including /e/ and youtube-nocookie embed urls; a copied #t= timestamp still finds that leftover file; empty 429 with no captions still fails; do not use --paid |
 
 ---
 

package/commands/auth.js

@@ -1,4 +1,4 @@
-const { AGENT_TOKEN_EXPIRED_DETAIL, loadCredentials, saveCredentials, deleteCredentials, getCredentialsPath, openBrowser, promptUser, displayAccountSummary, ensureValidCredentials, loadProfile, listProfiles, profileNameFromEmail, deleteProfile, saveProfile, getTokenExpiryEpochSeconds, getTerminalSessionId, setSessionProfile, getSessionProfile, clearSessionProfile, cleanStaleSessions, getSessionsDir } = require('../utils/auth');
+const { AGENT_TOKEN_EXPIRED_DETAIL, decodeJwtClaims, loadCredentials, saveCredentials, deleteCredentials, getCredentialsPath, openBrowser, promptUser, displayAccountSummary, ensureValidCredentials, loadProfile, listProfiles, profileNameFromEmail, deleteProfile, saveProfile, getTokenExpiryEpochSeconds, getTerminalSessionId, setSessionProfile, getSessionProfile, clearSessionProfile, cleanStaleSessions, getSessionsDir } = require('../utils/auth');
 const { getAppBaseUrl, apiRequestJson } = require('../utils/api');
 const { isNonInteractive, wantsJson } = require('../lib/noninteractive');
 const { hasFlag, readFlag } = require('../lib/arg-parser');
@@ -85,20 +85,45 @@ function extractAgentTokenMeta(data, requested, token) {
   return { scopes, dailyCreditCap, expiresAt };
 }
 
+function isAgentAccessToken(token) {
+  return decodeJwtClaims(token)?.type === 'agent_access';
+}
+
+function scopedTokenCandidate(credentials = {}) {
+  if (credentials.agent_token) return credentials.agent_token;
+  if (
+    credentials.source === 'env'
+    || credentials.source === 'agent_token_file'
+    || isAgentAccessToken(credentials.token)
+  ) {
+    return firstNonEmptyString(credentials.token);
+  }
+  return null;
+}
+
+function canMintFromLogin(credentials = {}) {
+  const login = firstNonEmptyString(credentials.token);
+  const refresh = firstNonEmptyString(credentials.refresh_token);
+  if (isAgentAccessToken(login) && !refresh) return false;
+  return Boolean(login || refresh);
+}
+
 function persistMintedAgentToken(credentials, token, extras = {}) {
+  if (isAgentAccessToken(credentials.token)) {
+    throw new Error('Refusing to save a scoped agent token as the login token; keep it under agent_token');
+  }
   const next = {
-    token,
+    ...credentials,
     refresh_token: extras.refresh_token || credentials.refresh_token || null,
-    email: credentials.email || null,
-    user_id: credentials.user_id || null,
-    provider: credentials.provider || null,
-    saved_at: extras.saved_at || new Date().toISOString(),
+    agent_token: token,
+    agent_token_scopes: extras.scopes || [],
+    agent_token_expires_at: extras.expiresAt || null,
   };
   if (credentials.source_profile) {
     saveProfile(credentials.source_profile, next);
     return next;
   }
-  saveCredentials(next.token, next.refresh_token, next.email, next.user_id, next.provider);
+  saveCredentials(next.token, next.refresh_token, next.email, next.user_id, next.provider, next);
   return next;
 }
 
@@ -139,10 +164,10 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
     ? requested.dailyCreditCap
     : DEFAULT_DAILY_CREDIT_CAP;
 
-  const credentials = load() || {};
+  const credentials = await load(api) || {};
   const accessToken = firstNonEmptyString(credentials.token);
   const refreshToken = firstNonEmptyString(credentials.refresh_token);
-  if (!accessToken && !refreshToken) {
+  if (!canMintFromLogin(credentials)) {
     return { ok: false, code: 'not_logged_in', error: NO_STORED_JWT_MESSAGE };
   }
 
@@ -150,7 +175,7 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
     scopes,
     daily_credit_cap: dailyCreditCap,
   };
-  let authToken = accessToken || refreshToken;
+  let authToken = isAgentAccessToken(accessToken) ? refreshToken : (accessToken || refreshToken);
   let result = await postAgentToken(api, authToken, body);
   if (!result.ok && result.status === 401 && refreshToken && authToken !== refreshToken) {
     authToken = refreshToken;
@@ -172,7 +197,9 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
     return { ok: false, code: 'missing_token', error: 'backend did not return an agent token' };
   }
 
+  const meta = extractAgentTokenMeta(result.data, { scopes, dailyCreditCap }, minted);
   persist(credentials, minted, {
+    ...meta,
     refresh_token: firstNonEmptyString(result.data && result.data.refresh_token) || refreshToken,
     saved_at: now(),
   });
@@ -180,7 +207,8 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
   return {
     ok: true,
     token: minted,
-    meta: extractAgentTokenMeta(result.data, { scopes, dailyCreditCap }, minted),
+    meta,
+    storedIn: credentials.source_profile ? `profile ${credentials.source_profile}, agent_token` : '~/.atris/credentials.json, agent_token',
   };
 }
 
@@ -191,24 +219,21 @@ async function ensureBilledCommandAuth(scope, deps = {}) {
   }
 
   const api = deps.apiRequestJson || apiRequestJson;
-  const ensureFn = deps.ensureValidCredentials || ensureValidCredentials;
   const load = deps.loadCredentials || loadCredentials;
   const mint = deps.mintScopedAgentToken || mintScopedAgentToken;
 
-  if (!deps.forceMint) {
-    const ensured = await ensureFn(api);
-    if (ensured && ensured.credentials && ensured.credentials.token) {
-      return {
-        ok: true,
-        token: ensured.credentials.token,
-        minted: false,
-        credentials: ensured.credentials,
-      };
-    }
+  const ensured = !deps.forceMint && deps.ensureValidCredentials
+    ? await deps.ensureValidCredentials(api) : null;
+  const credentials = ensured?.credentials || await load(api) || {};
+  const candidate = scopedTokenCandidate(credentials);
+  const claims = decodeJwtClaims(candidate);
+  const scopes = claims?.scopes || credentials.agent_token_scopes || [];
+  const expiry = claims?.exp ? claims.exp * 1000 : Date.parse(credentials.agent_token_expires_at);
+  if (!deps.forceMint && candidate && Array.isArray(scopes) && scopes.includes(wanted) && Number.isFinite(expiry) && expiry > Date.now()) {
+    return { ok: true, token: candidate, minted: false, credentials };
   }
 
-  const credentials = load() || {};
-  if (!firstNonEmptyString(credentials.token, credentials.refresh_token)) {
+  if (!canMintFromLogin(credentials)) {
     return { ok: false, error: NO_STORED_JWT_MESSAGE };
   }
 
@@ -267,6 +292,7 @@ async function mintAgentToken(args = [], deps = {}) {
     output(JSON.stringify({
       ok: true,
       minted: true,
+      stored_in: minted.storedIn,
       scopes: minted.meta.scopes,
       daily_credit_cap: minted.meta.dailyCreditCap,
       expires_at: minted.meta.expiresAt,
@@ -275,6 +301,7 @@ async function mintAgentToken(args = [], deps = {}) {
   }
 
   printAgentTokenMint(minted.meta, output);
+  output(`stored in ${minted.storedIn}`);
   return 0;
 }
 
@@ -982,6 +1009,7 @@ module.exports = {
   shellInit,
   parseAgentTokenArgs,
   mintAgentToken,
+  persistMintedAgentToken,
   ensureBilledCommandAuth,
   wantsAgentToken,
 };