flipstream 0.6.0 → 0.7.0

package/dist/commands/auth/clear-all.d.ts

@@ -7,4 +7,5 @@ export default class AuthClearAll extends BaseCommand<typeof AuthClearAll> {
     };
     static summary: string;
     run(): Promise<Record<string, unknown>>;
+    private revoke;
 }

package/dist/commands/auth/clear-all.js

@@ -3,48 +3,115 @@ import { fetchMetadata } from '../../lib/auth/discovery.js';
 import { revokeToken } from '../../lib/auth/revoke.js';
 import { BaseCommand } from '../../lib/command/base.js';
 import { knownHosts, removeConfigDir } from '../../lib/config/xdg.js';
+import { CliError, TimeoutError } from '../../lib/errors.js';
+import { ExitCode } from '../../lib/exit-codes.js';
 import { createStore } from '../../lib/store/index.js';
 export default class AuthClearAll extends BaseCommand {
     static description = 'Purge ALL Flipstream credentials: every keychain entry and the local config directory.';
     static examples = ['<%= config.bin %> auth clear-all', '<%= config.bin %> auth clear-all --no-revoke'];
     static flags = {
-        'no-revoke': Flags.boolean({ description: 'Clear local credentials only; skip the per-host server revocation calls.' }),
+        'no-revoke': Flags.boolean({
+            description: 'Clear local credentials only; skip the per-host server revocation calls.',
+        }),
     };
     static summary = 'Purge ALL credentials: every keychain entry and the local config dir.';
     async run() {
         const store = createStore();
         const hosts = knownHosts();
         const timeoutMs = this.flags.timeout ?? 10_000;
-        // Best-effort revoke each host's refresh token (in parallel — no cross-host
-        // dependency), then clear its keychain entry regardless of the outcome.
-        await Promise.all(hosts.map(async (host) => {
-            const creds = store.load(host);
-            if (!this.flags['no-revoke'] && creds?.refreshToken) {
-                try {
-                    const meta = await fetchMetadata(host, { timeoutMs });
-                    await revokeToken({
-                        clientId: creds.clientId,
-                        revocationEndpoint: meta.revocationEndpoint,
-                        timeoutMs,
-                        token: creds.refreshToken,
-                        tokenTypeHint: 'refresh_token',
-                    });
-                }
-                catch {
-                    // Best-effort — proceed to clear the keychain entry anyway.
-                }
-            }
-            store.clear(host);
-        }));
+        // THE LOCAL PURGE COMES FIRST, AND ALONE. An earlier attempt at this gave the
+        // command one wall-clock budget covering both keychain and network work, and
+        // that budget then got spent by slow token revocations — so a later host's
+        // `clear` was skipped entirely and `clear-all` returned having left
+        // credentials in the keychain. A purge command must never be talked out of
+        // purging by a server that will not answer.
+        //
+        // So the two phases are separated: every host's entry is read and deleted
+        // here, one at a time (each keychain call raises its own OS dialog, and
+        // stacking them puts several prompts on one person), and the revocations run
+        // afterwards from tokens captured on the way through. Serial keychain work is
+        // bounded because each call carries its own deadline; nothing here inherits a
+        // network stall.
+        const revocations = [];
+        const failed = [];
+        let keychainTimedOut = false;
+        for (const host of hosts) {
+            let refreshToken;
+            let clientId;
+            try {
+                // eslint-disable-next-line no-await-in-loop -- serialized on purpose; see above
+                const creds = await store.load(host);
+                refreshToken = creds?.refreshToken;
+                clientId = creds?.clientId;
+            }
+            catch (error) {
+                // Unreadable is not fatal to the purge: the delete below still runs, and
+                // a credential we could not read is one we certainly cannot revoke.
+                if (error instanceof TimeoutError)
+                    keychainTimedOut = true;
+            }
+            if (!this.flags['no-revoke'] && refreshToken && clientId) {
+                revocations.push({ clientId, host, token: refreshToken });
+            }
+            try {
+                // eslint-disable-next-line no-await-in-loop -- serialized on purpose; see above
+                await store.clear(host);
+            }
+            catch (error) {
+                // Keep purging. One unusable entry must not strand every other host's
+                // credentials, and the caller is told exactly which ones survived.
+                if (error instanceof TimeoutError)
+                    keychainTimedOut = true;
+                failed.push(host);
+            }
+        }
+        // Best effort, and deliberately AFTER the purge: a revocation that hangs or
+        // 500s can no longer cost anybody a deleted credential. These are network
+        // calls with their own timeout and are never reported as keychain failures.
+        await Promise.all(revocations.map(async (revocation) => this.revoke(revocation, timeoutMs)));
+        const cleared = hosts.filter((host) => !failed.includes(host));
+        if (failed.length > 0) {
+            // The config dir STAYS. knownHosts() is read from it, so removing it here
+            // would delete the only record of the hosts whose secrets are still in the
+            // keychain — the retry this error recommends would then find nothing to
+            // retry, and live credentials would be left with no way to locate them.
+            const summary = `Cleared ${cleared.length} host(s); ${failed.length} could not be cleared: ${failed.join(', ')}`;
+            const hint = 'Those keychain entries may still exist, so the local host list has been kept for the ' +
+                'retry. Re-run once the keychain can answer.';
+            const next = ['flipstream auth clear-all'];
+            // keychain_timeout means the KEYCHAIN timed out. It is not a label for a
+            // slow issuer, which is why revocation now runs outside this path entirely.
+            if (keychainTimedOut) {
+                throw new TimeoutError(`${summary} — the OS keychain did not respond in time.`, 'keychain_timeout').withDetails({ hint, next, retryable: true });
+            }
+            throw new CliError(summary, 'clear_incomplete', ExitCode.GENERIC).withDetails({ hint, next, retryable: true });
+        }
         const configRemoved = removeConfigDir();
-        return this.respond({ clearedHosts: hosts, configRemoved }, () => {
+        return this.respond({ clearedHosts: cleared, configRemoved }, () => {
             if (hosts.length === 0 && !configRemoved) {
                 this.log('Nothing to clear.');
             }
             else {
-                this.log(`Cleared ${hosts.length} host(s): ${hosts.join(', ') || '(none)'}`);
+                this.log(`Cleared ${cleared.length} host(s): ${cleared.join(', ') || '(none)'}`);
                 this.log(configRemoved ? 'Removed the local config directory.' : 'No local config directory to remove.');
             }
         });
     }
+    // One host's revocation, swallowing everything: the local credential is
+    // already gone, so nothing here can improve or worsen the purge.
+    async revoke(revocation, timeoutMs) {
+        try {
+            const meta = await fetchMetadata(revocation.host, { timeoutMs });
+            await revokeToken({
+                clientId: revocation.clientId,
+                revocationEndpoint: meta.revocationEndpoint,
+                timeoutMs,
+                token: revocation.token,
+                tokenTypeHint: 'refresh_token',
+            });
+        }
+        catch {
+            // Best-effort by contract.
+        }
+    }
 }

package/dist/commands/auth/login.js

@@ -23,7 +23,7 @@ export default class AuthLogin extends BaseCommand {
         });
         const expiresAt = Math.floor(Date.now() / 1000) + result.expiresIn;
         try {
-            createStore().save(result.host, {
+            await createStore().save(result.host, {
                 accessToken: result.accessToken,
                 clientId: result.clientId,
                 expiresAt,

package/dist/commands/auth/logout.js

@@ -14,7 +14,7 @@ export default class AuthLogout extends BaseCommand {
     async run() {
         const host = this.resolvedHost();
         const store = createStore();
-        const creds = store.load(host);
+        const creds = await store.load(host);
         if (!creds) {
             return this.respond({ host, loggedOut: true, revoked: false }, () => this.log(`Not logged in to ${host}; nothing to do.`));
         }
@@ -40,7 +40,7 @@ export default class AuthLogout extends BaseCommand {
             }
         }
         // Always clear local credentials, even if revocation could not be confirmed.
-        store.clear(host);
+        await store.clear(host);
         forgetHost(host);
         return this.respond({ host, loggedOut: true, revoked }, () => {
             this.log(`Logged out of ${host}.`);

package/dist/commands/auth/status.js

@@ -18,16 +18,17 @@ export default class AuthStatus extends BaseCommand {
     async run() {
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.available()) {
-            process.stderr.write('The OS keychain is unavailable (e.g. a headless/SSH session). Browser login needs it; ' +
-                'a headless client_credentials / service-account path is PLANNED.\n');
+        if (!(await store.available())) {
+            process.stderr.write('The OS keychain is unavailable (e.g. a headless/SSH session). Browser login needs it. ' +
+                'Over SSH or any other remote access, use a Flipstream service account from your ' +
+                'Flipstream account instead — it needs no browser and no keychain.\n');
             return this.exit(ExitCode.NETWORK);
         }
-        const creds = store.load(host);
+        const creds = await store.load(host);
         if (!creds) {
             return this.respond({ host, loggedIn: false }, () => this.log(`Not logged in to ${host}. Run \`flipstream auth login\`.`));
         }
-        const claims = tokenClaims(host, store) ?? {};
+        const claims = (await tokenClaims(host, store)) ?? {};
         // JSON keeps the stable subject id (agent-friendly); the human line prefers
         // the friendlier email when present.
         const account = [claims.sub, claims.email].find((value) => typeof value === 'string') ?? null;

package/dist/commands/catalog.js

@@ -37,7 +37,7 @@ export default class Catalog extends BaseCommand {
         const url = resolvePlannerUrl({ urlFlag: this.flags.url });
         const authHost = resolveHost({ hostFlag: this.flags['auth-host'] ?? this.flags.host });
         const store = createStore();
-        if (!store.load(authHost))
+        if (!(await store.load(authHost)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedPlannerClient({ authHost, store, timeoutMs: this.flags.timeout, url });
         const { source } = this.args;
@@ -71,7 +71,11 @@ export default class Catalog extends BaseCommand {
                 ], 'No sources.');
                 // Footer to STDERR: it is guidance, not data, and stdout must stay clean.
                 const hint = index.defaultSource === undefined ? '' : `, default ${index.defaultSource}`;
-                this.footer(`\n${index.sources.length} source(s)${hint}; \`${this.config.bin} catalog ${index.defaultSource ?? '<source>'}\` for its names`);
+                // WHICH MODEL produced this (#125). Without it, a current catalog and a
+                // planner running a stale image read identically, and the only way to
+                // tell them apart is cloning two repos to compare pins.
+                const served = index.catalogVersion === undefined ? '' : `\ndata-model ${index.catalogVersion}`;
+                this.footer(`\n${index.sources.length} source(s)${hint}; \`${this.config.bin} catalog ${index.defaultSource ?? '<source>'}\` for its names${served}`);
             });
         }
         const entry = parseCatalogSource(payload);
@@ -96,6 +100,13 @@ export default class Catalog extends BaseCommand {
         if (entry.customDimensionsMax !== undefined) {
             this.log(`\nCUSTOM DIMENSIONS  up to ${entry.customDimensionsMax} per connection`);
         }
+        // The same version line the index carries (#125), and UNCONDITIONAL — unlike
+        // the Try block below, which only appears when this source has both a
+        // dimension and a metric. This is the view people read while checking whether
+        // a name exists, which is exactly when "is this the model I think it is?"
+        // is the question.
+        if (entry.catalogVersion !== undefined)
+            this.footer(`\ndata-model ${entry.catalogVersion}`);
         // A runnable next command built from THIS source's real names (E11-3, #102):
         // the reader of a catalog is one edit away from a working query, so hand
         // them that edit. stderr — guidance, not data.

package/dist/commands/connections/list.js

@@ -27,7 +27,7 @@ export default class ConnectionsList extends BaseCommand {
             assertUuid(workspace, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
         const startedMs = Date.now();

package/dist/commands/log/add.js

@@ -31,7 +31,7 @@ export default class LogAdd extends BaseCommand {
         assertUuid(this.flags.workspace, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
         const organizationId = await resolveWorkspaceOrg(client, this.flags.workspace);

package/dist/commands/log/list.js

@@ -26,7 +26,7 @@ export default class LogList extends BaseCommand {
         assertUuid(this.flags.workspace, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
         const projected = await fetchLog(client, {

package/dist/commands/query.js

@@ -94,7 +94,7 @@ export default class Query extends BaseCommand {
             return this.respond(body, (data) => this.log(JSON.stringify(data, null, 2)));
         }
         const store = createStore();
-        if (!store.load(authHost))
+        if (!(await store.load(authHost)))
             throw AuthRequiredError.notLoggedIn();
         const admin = authedAdminClient(authHost, store, this.flags.timeout);
         // Resolve + check the connection for BOTH paths. Name resolution is only for
@@ -174,7 +174,7 @@ export default class Query extends BaseCommand {
         if (error.details.upstreamCode?.startsWith('UNKNOWN_')) {
             // Diagnosis never triggers a token refresh: an error-path bonus fetch
             // must not be able to mutate persistent auth state (review, #110).
-            if (context.store.accessTokenIfFresh(context.authHost) === null) {
+            if ((await context.store.accessTokenIfFresh(context.authHost)) === null) {
                 this.verboseLog('vocabulary diagnosis skipped: no fresh access token (diagnosis never refreshes)');
             }
             else {
@@ -210,11 +210,11 @@ export default class Query extends BaseCommand {
         // anything client-side) and are not secrets; both lists are bounded so a
         // token from a hostile --auth-host issuer cannot balloon the envelope.
         if (error.code === 'role_forbidden') {
-            const claims = tokenClaims(context.authHost, context.store) ?? {};
+            const claims = (await tokenClaims(context.authHost, context.store)) ?? {};
             const roles = (Array.isArray(claims.roles) ? claims.roles.filter((r) => typeof r === 'string') : [])
                 .slice(0, 20)
                 .map((role) => role.slice(0, 64));
-            const scopes = (context.store.load(context.authHost)?.scopes ?? [])
+            const scopes = ((await context.store.load(context.authHost))?.scopes ?? [])
                 .slice(0, 20)
                 .map((scope) => scope.slice(0, 64));
             error.withDetails({

package/dist/commands/workspaces/connections.js

@@ -25,7 +25,7 @@ export default class WorkspacesConnections extends BaseCommand {
         assertUuid(this.args.id, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
         const startedMs = Date.now();

package/dist/commands/workspaces/get.js

@@ -31,7 +31,7 @@ export default class WorkspacesGet extends BaseCommand {
         assertUuid(this.args.id, 'workspace id'); // exit 2, no request issued
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = createAuthedAdminClient({
             accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),

package/dist/commands/workspaces/list.js

@@ -32,7 +32,7 @@ export default class WorkspacesList extends BaseCommand {
         // The admin host == the OAuth issuer (creds live here); --host overrides both.
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = createAuthedAdminClient({
             accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),

package/dist/lib/api/retry.d.ts

@@ -1,6 +1,6 @@
 import { type DataClient } from './client.js';
 export interface RefreshDeps {
-    accessTokenIfFresh: (authHost: string) => null | string;
+    accessTokenIfFresh: (authHost: string) => Promise<null | string>;
     authHost: string;
     refresh: (authHost: string) => Promise<null | string>;
 }

package/dist/lib/api/retry.js

@@ -8,7 +8,7 @@ import { requestJson } from './http.js';
 // session_expired (exit 4). Non-401 errors (403/5xx/network/timeout) are never
 // retried; a second consecutive 401 propagates. Refresh always targets authHost.
 export async function withFreshToken(deps, fn) {
-    let token = deps.accessTokenIfFresh(deps.authHost) ?? (await deps.refresh(deps.authHost));
+    let token = (await deps.accessTokenIfFresh(deps.authHost)) ?? (await deps.refresh(deps.authHost));
     if (!token)
         throw AuthRequiredError.sessionExpired();
     try {

package/dist/lib/auth/claims.d.ts

@@ -1,3 +1,3 @@
 import type { TokenStore } from '../store/index.js';
 export declare function decodeJwtClaimsUnverified(accessToken: string): null | Record<string, unknown>;
-export declare function tokenClaims(host: string, store: TokenStore): null | Record<string, unknown>;
+export declare function tokenClaims(host: string, store: TokenStore): Promise<null | Record<string, unknown>>;

package/dist/lib/auth/claims.js

@@ -14,7 +14,7 @@ export function decodeJwtClaimsUnverified(accessToken) {
     }
 }
 // Decoded claims of the stored access token for `host` (display only), or null.
-export function tokenClaims(host, store) {
-    const creds = store.load(host);
+export async function tokenClaims(host, store) {
+    const creds = await store.load(host);
     return creds ? decodeJwtClaimsUnverified(creds.accessToken) : null;
 }

package/dist/lib/auth/flow.js

@@ -108,7 +108,8 @@ export async function login(options = {}) {
             const pasted = await (options.promptRedirect ?? defaultPromptRedirect)(authorizeUrl);
             if (!pasted || !pasted.trim()) {
                 throw new AuthFailedError('No redirected URL was provided. Browser login is not possible in a non-interactive ' +
-                    'environment; use a service-account / client_credentials flow instead (PLANNED).', 'headless_no_input');
+                    'environment; over SSH or any other remote access, use a Flipstream service account ' +
+                    '(client_credentials) from your Flipstream account instead — it needs no browser.', 'headless_no_input');
             }
             return parseRedirect(pasted, state).code;
         };

package/dist/lib/auth/refresh.js

@@ -11,7 +11,7 @@ import { fetchMetadata } from './discovery.js';
 export async function refresh(host, options = {}) {
     const store = options.store ?? createStore();
     const timeoutMs = options.timeoutMs ?? 10_000;
-    const creds = store.load(host);
+    const creds = await store.load(host);
     if (!creds || !creds.refreshToken)
         return null;
     let tokenEndpoint;
@@ -50,20 +50,30 @@ export async function refresh(host, options = {}) {
         // token is dead — but the one now in the keychain is not, and clearing blindly
         // would delete a working session and log the user out for no reason.
         //
-        // Re-read past any cache and only delete if what is stored is still the token
-        // we just tried. Note this race predates the read cache: two processes could
-        // always interleave a load and a rotation.
-        const current = store.reload(host);
+        // Re-read past any cache. If somebody else's token is there now, their
+        // session is live: HAND OFF to it rather than reporting failure, because
+        // returning null would surface as "Session expired. Run `flipstream auth
+        // login`" while perfectly good credentials sit in the keychain.
+        const current = await store.reload(host);
         if (current !== null && current.refreshToken !== creds.refreshToken) {
-            // Someone else won the race and their session is live. HAND OFF to it rather
-            // than reporting failure: returning null here would surface as "Session
-            // expired. Run `flipstream auth login`" while perfectly good credentials sit
-            // in the keychain — telling the user to fix something that is not broken.
             // May still be null if their access token is also stale; either way we do
-            // not clear a session we do not own.
+            // not touch a session we do not own.
             return freshAccessToken(current);
         }
-        store.clear(host); // genuinely invalid_grant / revoked session — force re-login.
+        // AND WE DO NOT DELETE, even though this token looks dead to us.
+        //
+        // The check above cannot be made atomic. Every store operation is its own
+        // child process now (~125ms), so between that reload and any delete there is
+        // a wide window in which the process that DID win the rotation completes its
+        // save — and we would then erase credentials that had just become valid. One
+        // command would return a token while every later command looked logged out.
+        //
+        // The two mistakes are not the same size. Deleting wrongly destroys a live
+        // session silently. Keeping a genuinely dead token costs one more failed
+        // refresh, which returns null here, surfaces as session_expired, and is
+        // overwritten by the next login anyway. Given a race we cannot close without
+        // a cross-process lock that every save would also have to respect, the
+        // cheaper mistake is the right default.
         return null;
     }
     if (!response.ok)
@@ -84,6 +94,6 @@ export async function refresh(host, options = {}) {
         // Rotate the refresh token ONLY when the server issued a new one.
         refreshToken: token.refresh_token ?? creds.refreshToken,
     };
-    store.save(host, updated);
+    await store.save(host, updated);
     return token.access_token;
 }

package/dist/lib/auth/session.js

@@ -6,7 +6,7 @@ import { refresh } from './refresh.js';
 // client (E4) uses to obtain a bearer token.
 export async function getFreshAccessToken(host, options = {}) {
     const store = options.store ?? createStore();
-    const cached = store.accessTokenIfFresh(host);
+    const cached = await store.accessTokenIfFresh(host);
     if (cached)
         return cached;
     return refresh(host, { store, timeoutMs: options.timeoutMs });

package/dist/lib/command/base.js

@@ -2,6 +2,7 @@ import { Command, Flags } from '@oclif/core';
 import { CONTRACT_VERSION } from '../config/constants.js';
 import { resolveHost } from '../config/xdg.js';
 import { classifyError, renderError, UsageError } from '../errors.js';
+import { setMachineMode } from '../output/machine-mode.js';
 import { renderNdjson } from '../output/ndjson.js';
 import { redact } from '../output/redact.js';
 import { appendRunLog, currentRunLogPath } from '../output/runlog.js';
@@ -99,6 +100,10 @@ export class BaseCommand extends Command {
         });
         this.flags = flags;
         this.args = args;
+        // Tell the rest of the process which stream discipline applies, so code far
+        // from here — the keychain's "still waiting" notice, for one — can honour
+        // the empty-stderr guarantee without being handed the command object.
+        setMachineMode(this.jsonEnabled() || Boolean(this.flags.ndjson));
         // --json and --ndjson both claim stdout; refuse the ambiguous combination.
         // UsageError carries exit 2 (oclif's {exit:2} would map to GENERIC instead).
         if (this.jsonEnabled() && this.flags.ndjson) {

package/dist/lib/output/interactivity.js

@@ -17,6 +17,12 @@
 // allocate a pty can look interactive until then. The escape hatch below
 // (FLIPSTREAM_NO_INPUT) exists for exactly that gap: any wrapper can force the
 // deterministic no-prompt path regardless of what the TTY claims.
+//
+// NOTE for anyone tempted to reuse these for a GUI question: none of them
+// answer it. macOS renders a keychain prompt through SecurityAgent, which a
+// desktop-launched process with piped stdio can show and a PTY-holding SSH
+// session cannot — see src/lib/store/keyring.ts, which deliberately asks a
+// different question.
 // stdin (can the user answer?) AND stderr (can they SEE the prompt?). stdout
 // is deliberately not consulted: piping stdout is this CLI's DESIGNED usage
 // (`query --json > out.json`), and a human at a terminal doing that can still

package/dist/lib/output/machine-mode.d.ts

@@ -0,0 +1,2 @@
+export declare function setMachineMode(on: boolean): void;
+export declare function isMachineMode(): boolean;

package/dist/lib/output/machine-mode.js

@@ -0,0 +1,25 @@
+// Is this run speaking to a machine? One boolean, set once, read by the few
+// places that would otherwise write prose into a stream an agent is parsing.
+//
+// It exists because progress notices are decided FAR from the command that
+// knows the output mode: src/lib/store/keyring.ts wants to say "still waiting on
+// the keychain" while a call is in flight, and it has no access to oclif's
+// jsonEnabled(). Passing the mode down through every call site would thread a
+// display concern through the store, the deadline and the spawn; a single
+// process-wide fact is both smaller and truer — a process is in exactly one
+// output mode for its whole life.
+//
+// The rule it protects is in docs/AGENT-CONTRACT.md and pinned by a test: under
+// --json/--ndjson, stderr stays EMPTY. A notice that ignored that would put
+// prose in front of an agent that is reading stderr for diagnostics.
+const MACHINE_MODE = Symbol.for('io.flipstream.cli.machine-mode');
+// Keyed on a registered Symbol rather than a module-local, so it survives this
+// file being loaded as two module instances (the same path spelled two ways —
+// see src/lib/store/index.ts, which keeps its singleton the same way).
+export function setMachineMode(on) {
+    ;
+    globalThis[MACHINE_MODE] = on;
+}
+export function isMachineMode() {
+    return globalThis[MACHINE_MODE] === true;
+}

package/dist/lib/planner/catalog.d.ts

@@ -5,6 +5,7 @@ export interface CatalogItem {
     type: string;
 }
 export interface CatalogSource {
+    catalogVersion?: string;
     customDimensionsMax?: number;
     description: string;
     dimensions: CatalogItem[];
@@ -19,6 +20,7 @@ export interface CatalogSourceSummary {
     name: string;
 }
 export interface CatalogIndex {
+    catalogVersion?: string;
     defaultSource?: string;
     sources: CatalogSourceSummary[];
 }

package/dist/lib/planner/catalog.js

@@ -18,6 +18,15 @@ function str(value, fallback = '') {
 function arr(value) {
     return Array.isArray(value) ? value : [];
 }
+// The data-model release that produced this document (#125). data-model stamps
+// it on every catalog — `catalogVersion` is required by its own schema and reads
+// the package version through importlib.metadata, so it cannot drift from the
+// tag query-planner pins. OPTIONAL here regardless: a planner older than the
+// field simply omits it, and a missing version must print nothing rather than
+// the word "undefined".
+function version(record) {
+    return typeof record.catalogVersion === 'string' ? record.catalogVersion : undefined;
+}
 function parseItem(value) {
     const record = asRecord(value) ?? {};
     // `format` may be absent or null; its `type` is what the human table shows.
@@ -42,7 +51,7 @@ export function parseCatalogIndex(payload) {
         };
     });
     const defaultSource = typeof record.defaultSource === 'string' ? record.defaultSource : undefined;
-    return { defaultSource, sources };
+    return { catalogVersion: version(record), defaultSource, sources };
 }
 // GET /catalog/<source> — one source's full vocabulary.
 export function parseCatalogSource(payload) {
@@ -50,6 +59,7 @@ export function parseCatalogSource(payload) {
     const custom = asRecord(record.customDimensions);
     const max = custom !== undefined && typeof custom.max === 'number' ? custom.max : undefined;
     return {
+        catalogVersion: version(record),
         customDimensionsMax: max,
         description: str(record.description),
         dimensions: arr(record.dimensions).map((item) => parseItem(item)),

package/dist/lib/store/keychain-child.d.ts

@@ -0,0 +1,11 @@
+export interface KeychainChildRequest {
+    account: string;
+    op: 'delete' | 'get' | 'set';
+    secret?: string;
+    service: string;
+}
+export interface KeychainChildResult {
+    error?: string;
+    ok: boolean;
+    value?: null | string;
+}

package/dist/lib/store/keychain-child.js

@@ -0,0 +1,135 @@
+// ONE keychain operation, in a process of its own, printed as JSON on stdout.
+//
+// This exists because a macOS keychain call can park in mach_msg forever (#119):
+// when securityd wants an authorization prompt that no GUI session can show (an
+// SSH shell, a locked console), the call never returns. Nothing inside a Node
+// process can recover from that — an AbortSignal does not interrupt a syscall
+// already in flight, worker.terminate() cannot unwind a thread blocked in the
+// kernel, and even process.exit() and process.reallyExit() hang, because Node's
+// shutdown joins its libuv workers and the wedged one never finishes. All three
+// were measured doing exactly that.
+//
+// A separate PROCESS is the one thing that can be killed. So the parent spawns
+// this, waits with a deadline, and SIGKILLs it if the deadline wins — the wedged
+// thread dies with the child, and the CLI stays free to report the failure and
+// exit with its own code.
+//
+// STDIN IS ALSO THE PARENT'S HEARTBEAT. The request arrives as one line and the
+// parent then holds the pipe open rather than closing it, so losing that pipe
+// means the parent is gone. A wedged helper whose CLI was killed would otherwise
+// be reparented and block forever, and cancelling a slow command repeatedly
+// would quietly accumulate immortal processes — the exact containment failure
+// the subprocess was introduced to prevent. Self-terminating on disconnect
+// covers every way a parent can die, including SIGKILL, which no parent-side
+// signal handler could catch.
+//
+// Nothing is passed as a command-line argument: those are readable by any `ps`
+// on the machine, which would expose the secret on a write and the account name
+// on every read.
+import { AsyncEntry } from '@napi-rs/keyring';
+import { writeSync } from 'node:fs';
+// fs.writeSync rather than process.stdout.write: this is the one place a store
+// module writes to a pipe, and a synchronous write cannot be truncated by the
+// process exiting underneath it.
+function emit(result) {
+    writeSync(1, `${JSON.stringify(result)}\n`);
+}
+// SIGKILL on ourselves rather than process.exit(): if a keychain call is already
+// wedged in the kernel, Node's own shutdown would join its libuv worker and hang
+// exactly like the parent did. Only the signal is certain.
+function dieWithParent() {
+    process.kill(process.pid, 'SIGKILL');
+}
+// ONE liveness handler, installed before anything else and never conditional.
+//
+// An earlier version had two sets — one that ignored EOF while reading the
+// request, and an unconditional pair installed after the request resolved. The
+// gap between them was a real hole: a parent that died immediately after writing
+// the request could deliver EOF into the handoff, have it ignored by the first
+// set and missed by the second, and leave a wedged helper with nothing left to
+// kill it. That is precisely the orphan this design exists to prevent, so the
+// handler is now unconditional for the whole life of the process.
+process.stdin.on('end', dieWithParent);
+process.stdin.on('close', dieWithParent);
+// The first line on stdin. The pipe stays OPEN afterwards, still serving as the
+// heartbeat above.
+function readRequestLine() {
+    return new Promise((resolve, reject) => {
+        // Already gone before we got started — nothing will ever arrive.
+        if (process.stdin.readableEnded) {
+            dieWithParent();
+            return;
+        }
+        let buffered = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            buffered += chunk;
+            const newline = buffered.indexOf('\n');
+            if (newline !== -1)
+                resolve(buffered.slice(0, newline));
+        });
+        process.stdin.on('error', reject);
+    });
+}
+// Narrow the request at the boundary — the repo's rule for anything parsed, even
+// when the only writer is our own parent.
+function parseRequest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const { account, op, secret, service } = record;
+    if (op !== 'delete' && op !== 'get' && op !== 'set')
+        return undefined;
+    if (typeof service !== 'string' || typeof account !== 'string')
+        return undefined;
+    if (secret !== undefined && typeof secret !== 'string')
+        return undefined;
+    return { account, op, secret, service };
+}
+async function main() {
+    const request = parseRequest(await readRequestLine());
+    if (request === undefined) {
+        emit({ error: 'the keychain helper got no readable request', ok: false });
+        return;
+    }
+    const entry = new AsyncEntry(request.service, request.account);
+    try {
+        switch (request.op) {
+            case 'delete': {
+                await entry.deletePassword();
+                emit({ ok: true, value: null });
+                return;
+            }
+            case 'get': {
+                const value = await entry.getPassword();
+                emit({ ok: true, value: value ?? null });
+                return;
+            }
+            case 'set': {
+                await entry.setPassword(request.secret ?? '');
+                emit({ ok: true, value: null });
+            }
+        }
+    }
+    catch (error) {
+        // The message is the keychain's own ("No matching entry found…"), which the
+        // parent needs verbatim to tell "empty" apart from "unusable". It never
+        // contains the secret — that is the value we did not get.
+        emit({ error: error instanceof Error ? error.message : String(error), ok: false });
+    }
+}
+await main();
+// Explicit, because stdin is deliberately still open as the parent's heartbeat
+// and its listeners would otherwise keep this process alive forever — the answer
+// would be written and the parent would still wait for a close that never came.
+// Safe to exit here: the result left through a synchronous write, and the
+// keychain call is already finished, so there is no libuv worker left to join.
+// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- the heartbeat pipe keeps the loop alive
+process.exit(0);

package/dist/lib/store/keyring.d.ts

@@ -1,19 +1,33 @@
+import { TimeoutError } from '../errors.js';
 import { type Credentials } from './credentials.js';
+import { type KeychainChildRequest } from './keychain-child.js';
 export declare const KEYRING_SERVICE = "io.flipstream.cli";
+export declare const KEYCHAIN_TIMEOUT_MS = 5000;
+export declare const KEYCHAIN_DEFAULT_TIMEOUT_MS = 30000;
+export declare const KEYCHAIN_INTERACTIVE_TIMEOUT_MS = 120000;
+export declare const KEYCHAIN_NOTICE_AFTER_MS = 10000;
+export declare const KEYCHAIN_TIMEOUT_ENV = "FLIPSTREAM_KEYCHAIN_TIMEOUT_MS";
+export declare const KEYCHAIN_INTERACTIVE_ENV = "FLIPSTREAM_KEYCHAIN_INTERACTIVE";
+export declare const KEYCHAIN_MAX_TIMEOUT_MS = 2147483647;
 export interface TokenStore {
-    accessTokenIfFresh(host: string): null | string;
-    available(): boolean;
-    clear(host: string): void;
-    load(host: string): Credentials | null;
-    reload(host: string): Credentials | null;
-    save(host: string, creds: Credentials): void;
+    accessTokenIfFresh(host: string): Promise<null | string>;
+    available(): Promise<boolean>;
+    clear(host: string): Promise<void>;
+    load(host: string): Promise<Credentials | null>;
+    reload(host: string): Promise<Credentials | null>;
+    save(host: string, creds: Credentials): Promise<void>;
 }
+export declare function keychainDeadlineMs(env?: NodeJS.ProcessEnv): number;
+export declare function keychainTimeout(operation: string, timeoutMs?: number): TimeoutError;
+export declare function withDeadline<T>(operation: string, run: (signal: AbortSignal) => Promise<T>, timeoutMs?: number): Promise<T>;
+export declare function spawnKeychain(request: KeychainChildRequest, signal: AbortSignal, scriptPath?: string): Promise<null | string>;
 export declare class KeyringStore implements TokenStore {
     #private;
-    accessTokenIfFresh(host: string): null | string;
-    available(): boolean;
-    clear(host: string): void;
-    load(host: string): Credentials | null;
-    reload(host: string): Credentials | null;
-    save(host: string, creds: Credentials): void;
+    constructor(scriptPath?: string);
+    accessTokenIfFresh(host: string): Promise<null | string>;
+    available(): Promise<boolean>;
+    clear(host: string): Promise<void>;
+    load(host: string): Promise<Credentials | null>;
+    reload(host: string): Promise<Credentials | null>;
+    save(host: string, creds: Credentials): Promise<void>;
 }

package/dist/lib/store/keyring.js

@@ -1,10 +1,191 @@
-import { Entry } from '@napi-rs/keyring';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { TimeoutError } from '../errors.js';
+import { isCI } from '../output/interactivity.js';
+import { isMachineMode } from '../output/machine-mode.js';
 import { freshAccessToken, keyOf, parseCredentials } from './credentials.js';
 // FROZEN. Tokens are stored in the OS keychain under this service id. Renaming
 // it strands users' tokens (silent logout + orphaned secrets), so any change
 // requires a one-time keyring-only migration (read old id -> write new id ->
 // delete old) — never a plaintext intermediary.
 export const KEYRING_SERVICE = 'io.flipstream.cli';
+// Why a keychain call needs a deadline AT ALL: on macOS it can park in mach_msg
+// forever, and nothing inside this process can recover from that. An AbortSignal
+// does not interrupt a syscall already in flight, and process.exit() and
+// process.reallyExit() both hang too, because Node's shutdown joins its libuv
+// workers and the wedged one never finishes. Hence keychain-child.ts: the work
+// runs in a process we can actually kill.
+//
+// How long to wait was argued over seven review rounds, and the useful outcome
+// was learning that the question cannot be answered by detection. Every signal
+// tried was wrong: stdio says nothing (SecurityAgent draws a GUI dialog, so a
+// desktop-launched CLI has pipes and an answerable prompt), SSH_* says nothing
+// (a tmux session started before an SSH login inherits none), and `launchctl
+// managername` says nothing either — the machine this was found on reported Aqua
+// with SSH_CONNECTION unset while its console sat unattended. Aqua proves a
+// screen exists, not that a person is in front of it. There is no evidence
+// available here that somebody is there to click.
+//
+// So the deadline is a judgement rather than a deduction, and it is split three
+// ways. An unattended machine should not sit for minutes, so the DEFAULT is
+// thirty seconds. Somebody who is there gets told at ten what is happening and
+// has twenty more to answer — and if they want longer they can say so, which is
+// the only statement about presence anybody can actually make. A caller that has
+// declared nothing can answer fails fastest of all.
+export const KEYCHAIN_TIMEOUT_MS = 5000;
+export const KEYCHAIN_DEFAULT_TIMEOUT_MS = 30_000;
+export const KEYCHAIN_INTERACTIVE_TIMEOUT_MS = 120_000;
+// How long a keychain call may take before we explain the wait on stderr.
+export const KEYCHAIN_NOTICE_AFTER_MS = 10_000;
+export const KEYCHAIN_TIMEOUT_ENV = 'FLIPSTREAM_KEYCHAIN_TIMEOUT_MS';
+export const KEYCHAIN_INTERACTIVE_ENV = 'FLIPSTREAM_KEYCHAIN_INTERACTIVE';
+// setTimeout's ceiling. A larger delay is silently clamped to ~1ms, which would
+// turn "wait longer" into "fail immediately" — the opposite of the request.
+export const KEYCHAIN_MAX_TIMEOUT_MS = 2_147_483_647;
+function isTruthy(value) {
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+// How long to wait for the OS on THIS run. Every path is a stated fact — an
+// exact figure, a declared willingness to wait, or a declared inability to
+// answer — because nothing observable about the session is evidence either way.
+export function keychainDeadlineMs(env = process.env) {
+    const override = Number(env[KEYCHAIN_TIMEOUT_ENV]);
+    if (Number.isInteger(override) && override > 0 && override <= KEYCHAIN_MAX_TIMEOUT_MS)
+        return override;
+    if (isTruthy(env[KEYCHAIN_INTERACTIVE_ENV]))
+        return KEYCHAIN_INTERACTIVE_TIMEOUT_MS;
+    if (isCI(env) || isTruthy(env.FLIPSTREAM_NO_INPUT))
+        return KEYCHAIN_TIMEOUT_MS;
+    return KEYCHAIN_DEFAULT_TIMEOUT_MS;
+}
+// A keychain call that ran out of time — exit 8, like any other timeout.
+// DISTINCT from "no credentials" on purpose: reporting a stuck keychain as "not
+// logged in" sends a logged-in user to `auth login`, which needs the same
+// keychain and hangs in the same place.
+export function keychainTimeout(operation, timeoutMs = KEYCHAIN_DEFAULT_TIMEOUT_MS) {
+    return new TimeoutError(`The OS keychain did not respond within ${timeoutMs} ms (${operation}).`, 'keychain_timeout').withDetails({
+        hint: 'A keychain prompt was probably waiting with nobody at that machine to approve it — or the ' +
+            'session cannot show one at all (SSH, a locked console, an unattended box). Over SSH or any ' +
+            'other remote access, use a Flipstream service account from your Flipstream account rather ' +
+            'than an interactive login: it needs no browser and no keychain. Otherwise approve the dialog ' +
+            `on that machine and set ${KEYCHAIN_INTERACTIVE_ENV}=1 (or ${KEYCHAIN_TIMEOUT_ENV}=<ms>) to ` +
+            'allow time for it, or set FLIPSTREAM_NO_KEYRING=1 for an in-memory session that keeps nothing ' +
+            'between commands.',
+        retryable: true,
+    });
+}
+// Say something, once, when a keychain call is taking a human amount of time.
+// This is what stops a deadline long enough to be useful from looking like the
+// original hang: the complaint was never the seconds, it was the silence.
+//
+// SILENT IN MACHINE MODE. Under --json/--ndjson stderr must stay empty (the
+// agent contract, pinned by a test), and an agent has nobody to ask anyway.
+function announceWait() {
+    const timer = setTimeout(() => {
+        if (isMachineMode())
+            return;
+        process.stderr.write("→ Still waiting on the OS keychain. Are you filling in the keychain prompt? If there's " +
+            'nobody at that machine — SSH, or any other remote access — use a Flipstream service ' +
+            'account instead; it needs no browser and no keychain. Ctrl-C to stop waiting.\n');
+    }, KEYCHAIN_NOTICE_AFTER_MS);
+    // Never hold the process open for a notice that may never be due.
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+// Run something under a wall-clock deadline, aborting the signal when the
+// deadline wins. Kept separate from the spawning below so the deadline itself is
+// testable without touching a real keychain.
+export async function withDeadline(operation, run, timeoutMs = keychainDeadlineMs()) {
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(keychainTimeout(operation, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(controller.signal), deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// This module's sibling child script, in whichever form is on disk: dist/*.js
+// for a published run, src/*.ts under the Bun dev entry. Derived from our OWN
+// url rather than guessed, so it cannot point at a build that is not there.
+function childScript() {
+    const self = import.meta.url;
+    return fileURLToPath(new URL(self.endsWith('.ts') ? './keychain-child.ts' : './keychain-child.js', self));
+}
+// Ask the child to do one operation, and KILL it if the deadline passes. SIGKILL
+// rather than SIGTERM: a process wedged in the kernel will not run a handler.
+//
+// The runtime is process.execPath, never a node_modules/.bin shim — a shim
+// encodes an assumption about the machine (a `node` on PATH), while this encodes
+// only what the repo already guarantees. `scriptPath` is injectable so the kill
+// path and the failure paths can be tested against helpers that misbehave on
+// purpose.
+export function spawnKeychain(request, signal, scriptPath = childScript()) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [scriptPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+        signal.addEventListener('abort', () => child.kill('SIGKILL'), { once: true });
+        // One line, and then the pipe STAYS OPEN as the child's heartbeat: losing it
+        // is how the child learns this process died and kills itself, instead of
+        // being reparented and blocking forever. Closing it here would hand that
+        // guarantee away for nothing.
+        child.stdin.on('error', reject);
+        child.stdin.write(`${JSON.stringify(request)}\n`);
+        let out = '';
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            out += chunk;
+        });
+        child.on('error', reject);
+        child.on('close', () => {
+            // Killed by our own deadline: withDeadline's rejection is already on its
+            // way, so settling here would only race it.
+            if (signal.aborted)
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(out.trim());
+            }
+            catch {
+                reject(new Error('the keychain helper returned no readable answer'));
+                return;
+            }
+            if (parsed.ok)
+                resolve(parsed.value ?? null);
+            // The child's message is the keychain's own wording, which the callers
+            // below match on to tell "empty" apart from "unusable".
+            else
+                reject(new Error(parsed.error ?? 'the keychain helper failed'));
+        });
+    });
+}
+async function keychain(call) {
+    const request = {
+        account: call.account,
+        op: call.op,
+        secret: call.secret,
+        service: KEYRING_SERVICE,
+    };
+    const done = announceWait();
+    try {
+        return await withDeadline(call.operation, (signal) => spawnKeychain(request, signal, call.scriptPath));
+    }
+    finally {
+        done();
+    }
+}
+// "Not found" is the keychain working and holding nothing — the ONLY failure
+// that means absence. A helper that could not spawn, crashed loading its native
+// binding, or answered with something unreadable has told us nothing about
+// whether a credential exists, and must never be read as "there isn't one".
+function isNotFound(error) {
+    return /not found|no (matching )?(entry|password|item)|could not be found/i.test(error.message);
+}
 // TokenStore backed by the OS keychain. The whole Credentials JSON is the single
 // secret per host (keyed by host).
 //
@@ -13,7 +194,8 @@ export const KEYRING_SERVICE = 'io.flipstream.cli';
 // re-reads it through withFreshToken, and a paginated call re-reads it per page.
 // On macOS each read is a separate access, so a user who granted "Allow" rather
 // than "Always Allow" gets prompted once per read: two dialogs for `catalog`,
-// three for `query`, more for anything that paginates or resolves a name.
+// three for `query`, more for anything that paginates or resolves a name. Each
+// read is also a process now, so the cache saves spawns as well as dialogs.
 //
 // This costs nothing in EXPOSURE: the credentials are already in memory the moment
 // they are read — they have to be, to go in an Authorization header — so holding
@@ -38,49 +220,95 @@ export class KeyringStore {
     // `null` is cached too: "this host has no credentials" is an answer worth
     // remembering, or a logged-out run re-reads on every check.
     #cache = new Map();
-    accessTokenIfFresh(host) {
-        return freshAccessToken(this.load(host));
+    // Injectable purely so the failure paths can be driven by a helper that
+    // misbehaves on purpose; production always uses the sibling script.
+    #scriptPath;
+    constructor(scriptPath) {
+        this.#scriptPath = scriptPath;
     }
-    available() {
+    async accessTokenIfFresh(host) {
+        return freshAccessToken(await this.load(host));
+    }
+    async available() {
         try {
-            new Entry(KEYRING_SERVICE, '__probe__').getPassword();
+            await keychain({
+                account: '__probe__',
+                op: 'get',
+                operation: 'probing the keychain',
+                scriptPath: this.#scriptPath,
+            });
             return true;
         }
         catch (error) {
+            // A wedged keychain is NOT an answer to "is one available" — it is the
+            // timeout this whole change exists to report. Returning false here sent
+            // `auth status` down its unavailable branch and out with exit 7 (network),
+            // for the one condition whose entire point is exit 8 and a message naming
+            // the prompt. It propagates.
+            if (error instanceof TimeoutError)
+                throw error;
             // "not found" means the keychain works but is empty (available); any other
             // failure (e.g. no Secret Service on headless Linux) means it is unavailable.
-            return /not found|no (matching )?(entry|password|item)|could not be found/i.test(error.message);
+            return isNotFound(error);
         }
     }
-    clear(host) {
-        this.#cache.set(host, null);
+    async clear(host) {
         try {
-            new Entry(KEYRING_SERVICE, keyOf(host)).deletePassword();
+            await keychain({
+                account: keyOf(host),
+                op: 'delete',
+                operation: `clearing credentials for ${host}`,
+                scriptPath: this.#scriptPath,
+            });
         }
-        catch {
-            // Nothing stored for this host.
+        catch (error) {
+            // Only a verified "there was nothing to delete" counts as cleared. Anything
+            // else — a timeout, a helper that could not start, an unreadable answer —
+            // leaves the credential possibly intact, and logout must not report success
+            // over it.
+            if (!isNotFound(error))
+                throw error;
         }
+        // Cached only once the deletion is confirmed, so a failed clear cannot leave
+        // this process believing the session is gone.
+        this.#cache.set(host, null);
     }
-    load(host) {
+    async load(host) {
         const cached = this.#cache.get(host);
         if (cached !== undefined)
             return cached;
         return this.reload(host);
     }
-    reload(host) {
+    async reload(host) {
         let creds = null;
         try {
-            const secret = new Entry(KEYRING_SERVICE, keyOf(host)).getPassword();
+            const secret = await keychain({
+                account: keyOf(host),
+                op: 'get',
+                operation: `reading credentials for ${host}`,
+                scriptPath: this.#scriptPath,
+            });
             creds = secret ? parseCredentials(secret) : null;
         }
-        catch {
+        catch (error) {
+            // Absence is the only thing we may infer. Every other failure propagates:
+            // "we could not read" reported as "nothing stored" turns a spawn failure
+            // into not_logged_in and sends a logged-in user to re-authenticate.
+            if (!isNotFound(error))
+                throw error;
             creds = null;
         }
         this.#cache.set(host, creds);
         return creds;
     }
-    save(host, creds) {
-        new Entry(KEYRING_SERVICE, keyOf(host)).setPassword(JSON.stringify(creds));
+    async save(host, creds) {
+        await keychain({
+            account: keyOf(host),
+            op: 'set',
+            operation: `saving credentials for ${host}`,
+            scriptPath: this.#scriptPath,
+            secret: JSON.stringify(creds),
+        });
         // Keep the cache authoritative: a refresh saves rotated tokens mid-command,
         // and a later read must see them rather than the ones it started with.
         this.#cache.set(host, creds);

package/dist/lib/store/memory-store.d.ts

@@ -2,10 +2,10 @@ import type { TokenStore } from './keyring.js';
 import { type Credentials } from './credentials.js';
 export declare class MemoryStore implements TokenStore {
     private readonly entries;
-    accessTokenIfFresh(host: string): null | string;
-    available(): boolean;
-    clear(host: string): void;
-    load(host: string): Credentials | null;
-    reload(host: string): Credentials | null;
-    save(host: string, creds: Credentials): void;
+    accessTokenIfFresh(host: string): Promise<null | string>;
+    available(): Promise<boolean>;
+    clear(host: string): Promise<void>;
+    load(host: string): Promise<Credentials | null>;
+    reload(host: string): Promise<Credentials | null>;
+    save(host: string, creds: Credentials): Promise<void>;
 }

package/dist/lib/store/memory-store.js

@@ -3,24 +3,27 @@ import { freshAccessToken, keyOf } from './credentials.js';
 // Interchangeable with KeyringStore via the TokenStore interface.
 export class MemoryStore {
     entries = new Map();
-    accessTokenIfFresh(host) {
-        return freshAccessToken(this.load(host));
+    async accessTokenIfFresh(host) {
+        return freshAccessToken(await this.load(host));
     }
-    available() {
+    // Async to match TokenStore, which is async because a REAL keychain call has
+    // to be cancellable (see keyring.ts). Nothing here can block; the signature
+    // exists so tests drive the same call shape production does.
+    async available() {
         return true;
     }
-    clear(host) {
+    async clear(host) {
         this.entries.delete(keyOf(host));
     }
-    load(host) {
+    async load(host) {
         return this.entries.get(keyOf(host)) ?? null;
     }
     // No cache here, so a forced re-read is the same read. Present so the interface
     // is honest and tests exercise the same call sites as the real store.
-    reload(host) {
+    async reload(host) {
         return this.load(host);
     }
-    save(host, creds) {
+    async save(host, creds) {
         this.entries.set(keyOf(host), creds);
     }
 }

package/oclif.manifest.json

@@ -1445,5 +1445,5 @@
       ]
     }
   },
-  "version": "0.6.0"
+  "version": "0.7.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flipstream",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Flipstream CLI — query your Flipstream data from the terminal.",
   "keywords": [
     "flipstream",