aismemory 0.6.0 → 0.6.2

package/dist/cli/doctor.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/**
+ * `aismemory doctor` — read-only self-diagnosis for "it doesn't work" reports.
+ *
+ * A new user whose MCP client can't reach AIS has no way to tell whether the
+ * problem is DNS, a corporate proxy, an unbonded agent, an expired token, or
+ * clock skew. This command runs a fixed set of read-only checks against the
+ * local environment and the AIS host and prints a PASS/WARN/FAIL report with
+ * a one-line remediation hint per problem — no writes to the API, no agent
+ * creation.
+ *
+ * Usage:
+ *   npx aismemory doctor
+ *   npx aismemory doctor --json
+ *   AIS_URL=https://other.example.com npx aismemory doctor
+ *
+ * Exit codes:
+ *   0 — no FAIL checks (WARNs are still reported but don't fail the command)
+ *   1 — at least one FAIL check
+ */
+import { lookup as dnsLookupDefault } from 'node:dns/promises';
+import { connect as tlsConnectDefault } from 'node:tls';
+import { loadOAuthCredentials, credentialsFilePath } from '../oauth-credentials.js';
+import { isCredsStale } from '../auth-staleness.js';
+/** Minimum Node major version this package requires (per @modelcontextprotocol/sdk engines). */
+const MIN_NODE_MAJOR = 18;
+const PROXY_ENV_KEYS = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'NO_PROXY', 'no_proxy'];
+const CLOCK_SKEW_WARN_MS = 5 * 60 * 1000;
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ── Individual checks ────────────────────────────────────
+export function checkNodeVersion(nodeVersion = process.version, minMajor = MIN_NODE_MAJOR) {
+    const match = /^v?(\d+)\./.exec(nodeVersion);
+    const major = match ? Number(match[1]) : NaN;
+    if (Number.isNaN(major)) {
+        return {
+            name: 'Node version',
+            status: 'WARN',
+            message: `Could not parse Node version string "${nodeVersion}".`,
+            hint: `aismemory requires Node >= ${minMajor}.`,
+        };
+    }
+    if (major < minMajor) {
+        return {
+            name: 'Node version',
+            status: 'FAIL',
+            message: `Node ${nodeVersion} is below the required minimum (>= ${minMajor}).`,
+            hint: `Upgrade Node (e.g. via nvm: "nvm install ${minMajor}") and retry.`,
+        };
+    }
+    return {
+        name: 'Node version',
+        status: 'PASS',
+        message: `Node ${nodeVersion} meets the minimum requirement (>= ${minMajor}).`,
+    };
+}
+export async function checkDnsResolution(host, lookup = dnsLookupDefault) {
+    try {
+        const { address } = await lookup(host);
+        return {
+            name: 'DNS resolution',
+            status: 'PASS',
+            message: `${host} resolves to ${address}.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'DNS resolution',
+            status: 'FAIL',
+            message: `Could not resolve DNS for ${host}: ${errMsg(err)}.`,
+            hint: 'Check your internet connection and DNS settings (or /etc/resolv.conf).',
+        };
+    }
+}
+function defaultTlsProbe(host, port, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const socket = tlsConnectDefault({ host, port, servername: host, timeout: timeoutMs }, () => {
+            if (settled)
+                return;
+            settled = true;
+            socket.end();
+            resolve();
+        });
+        socket.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        });
+        socket.on('timeout', () => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(new Error(`connection to ${host}:${port} timed out after ${timeoutMs}ms`));
+        });
+    });
+}
+export async function checkTlsReachability(host, probe = defaultTlsProbe, port = 443, timeoutMs = 5000) {
+    try {
+        await probe(host, port, timeoutMs);
+        return {
+            name: 'TLS reachability',
+            status: 'PASS',
+            message: `${host}:${port} accepts TLS connections.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'TLS reachability',
+            status: 'FAIL',
+            message: `Could not open a TLS connection to ${host}:${port}: ${errMsg(err)}.`,
+            hint: 'A firewall, VPN, or corporate proxy may be blocking outbound HTTPS. See the proxy check below.',
+        };
+    }
+}
+export async function checkRestHealth(baseUrl, fetchImpl = fetch) {
+    const url = `${baseUrl}/livez`;
+    try {
+        const res = await fetchImpl(url);
+        const dateHeader = res.headers.get('date') ?? undefined;
+        if (res.ok) {
+            return {
+                name: 'REST API health',
+                status: 'PASS',
+                message: `${url} responded HTTP ${res.status} (alive).`,
+                dateHeader,
+            };
+        }
+        return {
+            name: 'REST API health',
+            status: 'WARN',
+            message: `${url} responded HTTP ${res.status} — server reachable but reporting a problem.`,
+            hint: 'The AIS backend may be degraded. Check again shortly.',
+            dateHeader,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'REST API health',
+            status: 'FAIL',
+            message: `Could not reach ${url}: ${errMsg(err)}.`,
+            hint: 'Check network connectivity — see the DNS/TLS checks above.',
+        };
+    }
+}
+export async function checkMcpEndpoint(baseUrl, fetchImpl = fetch) {
+    const url = `${baseUrl}/mcp`;
+    try {
+        const res = await fetchImpl(url);
+        // Any resolved HTTP response (even 401 "auth required") proves the MCP
+        // endpoint is reachable — only a network-level failure means "down".
+        const authNote = res.status === 401 || res.status === 403 ? ' (auth required, as expected without a key)' : '';
+        return {
+            name: 'MCP HTTP endpoint',
+            status: 'PASS',
+            message: `${url} responded HTTP ${res.status}${authNote}.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'MCP HTTP endpoint',
+            status: 'FAIL',
+            message: `Could not reach ${url}: ${errMsg(err)}.`,
+            hint: 'Check network connectivity — see the DNS/TLS checks above.',
+        };
+    }
+}
+export async function checkCredentials(baseUrl, deps = {}) {
+    const load = deps.load ?? loadOAuthCredentials;
+    const now = deps.now ?? Date.now;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const home = deps.home;
+    const path = credentialsFilePath(home);
+    const creds = load(home);
+    if (!creds) {
+        return {
+            name: 'Credentials',
+            status: 'WARN',
+            message: `No credentials found at ${path} — this device has not bonded to an agent yet.`,
+            hint: 'Run any aismemory tool from your MCP client once and follow the printed bond URL/code (takes ~30s).',
+        };
+    }
+    if (isCredsStale(creds.expiresAt, now())) {
+        return {
+            name: 'Credentials',
+            status: 'WARN',
+            message: `Credentials at ${path} are expired or expiring within 5 minutes (expiresAt: ${creds.expiresAt}).`,
+            hint: 'No action needed — the next tool call re-authenticates automatically (silently if a device key is enrolled).',
+        };
+    }
+    try {
+        const res = await fetchImpl(`${baseUrl}/v1/agents/${creds.agentId}`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+        if (res.ok) {
+            return {
+                name: 'Credentials',
+                status: 'PASS',
+                message: `Bonded as agent ${creds.agentId}; AIS accepted the saved token.`,
+            };
+        }
+        return {
+            name: 'Credentials',
+            status: 'WARN',
+            message: `Saved credentials found, but AIS returned HTTP ${res.status} for agent ${creds.agentId}.`,
+            hint: 'The token may be revoked or the agent archived. Re-run any aismemory tool to trigger re-authentication.',
+        };
+    }
+    catch (err) {
+        return {
+            name: 'Credentials',
+            status: 'FAIL',
+            message: `Could not verify saved credentials with AIS: ${errMsg(err)}.`,
+            hint: 'Check network connectivity — see the REST API health check above.',
+        };
+    }
+}
+export function checkProxyEnv(env = process.env) {
+    const set = PROXY_ENV_KEYS.filter((key) => Boolean(env[key]));
+    if (set.length === 0) {
+        return {
+            name: 'Proxy environment',
+            status: 'PASS',
+            message: 'No HTTP(S)_PROXY / NO_PROXY environment variables set.',
+        };
+    }
+    return {
+        name: 'Proxy environment',
+        status: 'WARN',
+        message: `Proxy environment variable(s) detected: ${set.join(', ')}.`,
+        hint: 'A corporate proxy can block or MITM TLS to ais.agentsandswarms.ai. If aismemory only fails on this network, ask IT to allowlist the host or trust the proxy CA.',
+    };
+}
+export function checkClockSkew(dateHeader, now = Date.now, warnThresholdMs = CLOCK_SKEW_WARN_MS) {
+    if (!dateHeader) {
+        return {
+            name: 'Clock skew',
+            status: 'WARN',
+            message: 'No server Date header available to compare (REST API health check did not return one).',
+        };
+    }
+    const remoteMs = Date.parse(dateHeader);
+    if (Number.isNaN(remoteMs)) {
+        return {
+            name: 'Clock skew',
+            status: 'WARN',
+            message: `Could not parse the server Date header: "${dateHeader}".`,
+        };
+    }
+    const skewMs = Math.abs(now() - remoteMs);
+    const skewMinutes = (skewMs / 60000).toFixed(1);
+    if (skewMs > warnThresholdMs) {
+        return {
+            name: 'Clock skew',
+            status: 'WARN',
+            message: `Local clock differs from the AIS server by ~${skewMinutes} minutes.`,
+            hint: 'Large clock skew can invalidate OAuth tokens. Sync your system clock (e.g. enable automatic time/NTP).',
+        };
+    }
+    return {
+        name: 'Clock skew',
+        status: 'PASS',
+        message: `Local clock is within ${skewMinutes} min of the AIS server.`,
+    };
+}
+export async function runDoctor(options = {}) {
+    const env = options.env ?? process.env;
+    const aisUrl = options.aisUrl ?? env['AIS_URL'] ?? 'https://ais.agentsandswarms.ai';
+    const host = new URL(aisUrl).hostname;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const checks = [];
+    checks.push(checkNodeVersion(options.nodeVersion));
+    checks.push(await checkDnsResolution(host, options.dnsLookup));
+    checks.push(await checkTlsReachability(host, options.tlsProbe));
+    const health = await checkRestHealth(aisUrl, fetchImpl);
+    checks.push(health);
+    checks.push(await checkMcpEndpoint(aisUrl, fetchImpl));
+    checks.push(await checkCredentials(aisUrl, {
+        fetchImpl,
+        load: options.loadCreds,
+        home: options.home,
+        now,
+    }));
+    checks.push(checkProxyEnv(env));
+    checks.push(checkClockSkew(health.dateHeader, now));
+    const problemCount = checks.filter((c) => c.status !== 'PASS').length;
+    const hasFail = checks.some((c) => c.status === 'FAIL');
+    return {
+        aisUrl,
+        checks,
+        problemCount,
+        verdict: problemCount === 0 ? 'pass' : 'problems',
+        exitCode: hasFail ? 1 : 0,
+    };
+}
+// ── CLI formatting + entrypoint ──────────────────────────
+function formatText(report) {
+    const lines = [];
+    lines.push(`aismemory doctor — ${report.aisUrl}`);
+    lines.push('');
+    for (const c of report.checks) {
+        lines.push(`[${c.status}] ${c.name}: ${c.message}`);
+        if (c.hint && c.status !== 'PASS') {
+            lines.push(`       hint: ${c.hint}`);
+        }
+    }
+    lines.push('');
+    lines.push(report.problemCount === 0
+        ? 'doctor: all checks passed'
+        : `doctor: ${report.problemCount} problem(s) found`);
+    return lines.join('\n');
+}
+export async function main(argv = process.argv.slice(2)) {
+    const json = argv.includes('--json');
+    const report = await runDoctor();
+    if (json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatText(report)}\n`);
+    }
+    process.exit(report.exitCode);
+}
+main().catch((err) => {
+    process.stderr.write(`[aismemory doctor] Fatal: ${errMsg(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=doctor.js.map

package/dist/cli/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -7,4 +7,15 @@
  *
  * Usage: npx aismemory
  */
+type AgentSummary = {
+    id: string;
+    name: string;
+    status: string;
+};
+/**
+ * Fetch EVERY agent in the tenant, following server pagination.
+ * The server defaults to limit=20 and silently truncates (2026-08-24
+ * lockout, ticket 72ab7f4e) — never call GET /v1/agents without this.
+ */
+export declare function listAllAgents(token: string): Promise<AgentSummary[]>;
 export {};

package/dist/index.js

@@ -124,6 +124,25 @@ async function aisGet(path, token) {
     }
     return data;
 }
+/**
+ * Fetch EVERY agent in the tenant, following server pagination.
+ * The server defaults to limit=20 and silently truncates (2026-08-24
+ * lockout, ticket 72ab7f4e) — never call GET /v1/agents without this.
+ */
+export async function listAllAgents(token) {
+    const all = [];
+    let page = 1;
+    // hard stop at 50 pages (1000 agents) as a runaway guard
+    for (; page <= 50; page += 1) {
+        const res = (await aisGet(`/v1/agents?limit=100&page=${page}`, token));
+        const agents = res.data?.agents ?? [];
+        all.push(...agents);
+        const hasMore = res.data?.pagination?.hasMore ?? false;
+        if (!hasMore)
+            break;
+    }
+    return all;
+}
 async function resolveAgentForLoad(token, query) {
     const resolveRes = (await aisGet(`/v1/resolve?query=${encodeURIComponent(query)}`, token));
     if (resolveRes.data?.status === 'resolved' && resolveRes.data.agent) {
@@ -137,8 +156,7 @@ async function resolveAgentForLoad(token, query) {
         const available = resolveRes.data.available?.map((ag) => ag.name).join(', ');
         throw new Error(resolveRes.data.message ?? `agent_load: no agent named "${query}" in this tenant. Available: ${available || '(none)'}`);
     }
-    const listRes = (await aisGet('/v1/agents', token));
-    const agents = listRes.data?.agents ?? [];
+    const agents = await listAllAgents(token);
     const matches = agents.filter((ag) => ag.name.toLowerCase() === query.toLowerCase() || ag.id === query);
     if (matches.length === 0) {
         const available = agents.map((ag) => ag.name).join(', ');
@@ -160,8 +178,7 @@ async function resolveAgent(token, fallbackAgentId, fallbackTenantId, preferredA
     // Explicit env var overrides everything — must belong to this tenant.
     const envAgentId = process.env['AIS_AGENT_ID'];
     if (envAgentId) {
-        const listRes = (await aisGet('/v1/agents', token));
-        const agents = listRes.data?.agents ?? [];
+        const agents = await listAllAgents(token);
         try {
             const match = assertEnvAgentInTenant(envAgentId, agents);
             stderr(`Using agent from AIS_AGENT_ID: ${match.name} (${match.id})`);
@@ -174,8 +191,7 @@ async function resolveAgent(token, fallbackAgentId, fallbackTenantId, preferredA
         }
     }
     try {
-        const res = await aisGet('/v1/agents', token);
-        const agents = res.data?.agents?.filter((a) => a.status === 'active') ?? [];
+        const agents = (await listAllAgents(token)).filter((a) => a.status === 'active');
         const selection = selectAgentForSession({
             agents,
             envAgentName: process.env['AIS_AGENT_NAME'],
@@ -224,31 +240,31 @@ class BondPendingError extends Error {
     userCode;
     bondPending = true;
     constructor(verificationUri, userCode) {
-        super(`Memory bond required.\n\n` +
+        super(`Memory bond required — ask your human to approve now.\n\n` +
             `Visit: ${verificationUri}\n` +
             `Code: ${userCode}\n\n` +
-            `Enter your email and tap Approve, then retry this tool. Takes about 30 seconds.`);
+            `Enter your email and tap Approve, then retry this tool. Takes about 30 seconds.\n` +
+            `Heads up: this code expires in 30 minutes, and unclaimed agents (and their memories) are archived after 7 days.`);
         this.verificationUri = verificationUri;
         this.userCode = userCode;
         this.name = 'BondPendingError';
     }
 }
-async function startDeviceFlow() {
+async function startDeviceFlow(priorProvisionalToken) {
     emitTelemetry({ event: 'auth.device_flow.start' });
     stderr('Starting authentication...');
-    const authRes = (await aisPost('/v1/oauth/device/authorize', {
-        name: `agent-${homedir().split('/').pop() ?? 'user'}`,
-    }));
+    const authRes = (await aisPost('/v1/oauth/device/authorize', { name: `agent-${homedir().split('/').pop() ?? 'user'}` }, priorProvisionalToken));
     if (!authRes.success || !authRes.data) {
         throw new Error(`Authentication failed: ${authRes.error?.message ?? 'Unknown error'}`);
     }
-    const { device_code, user_code, verification_uri_complete, interval, agent_id, provisional_tenant_id } = authRes.data;
+    const { device_code, user_code, verification_uri_complete, interval, agent_id, provisional_tenant_id, provisional_token } = authRes.data;
     stderr('');
     stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     stderr('  aismemory — memory bond required');
     stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     stderr(`  Bond URL : ${verification_uri_complete}`);
     stderr(`  Code     : ${user_code}`);
+    stderr('  Code expires in 30 min; unclaimed agents are archived after 7 days.');
     stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     const flow = {
         device_code,
@@ -256,6 +272,7 @@ async function startDeviceFlow() {
         verification_uri_complete,
         agent_id,
         provisional_tenant_id,
+        provisional_token,
         // poll is assigned below after flowRef is captured so pollForToken holds
         // a reference to the live flow object for URL updates on auto-restart.
         dead: false,
@@ -276,7 +293,7 @@ async function startDeviceFlow() {
     return flow;
 }
 async function pollForToken(device_code, interval, agent_id, provisional_tenant_id, 
-/** Mutable ref so auto-restart can update the surfaced URL in ActiveDeviceFlow */
+/** Mutable ref so auto-restart can update the surfaced URL and provisional token in ActiveDeviceFlow */
 flowRef) {
     const pollIntervalMs = Math.max(interval, 5) * 1000;
     const handle = {
@@ -307,9 +324,7 @@ flowRef) {
             }
         },
         startNewFlow: async () => {
-            const authRes = (await aisPost('/v1/oauth/device/authorize', {
-                name: `agent-${homedir().split('/').pop() ?? 'user'}`,
-            }));
+            const authRes = (await aisPost('/v1/oauth/device/authorize', { name: `agent-${homedir().split('/').pop() ?? 'user'}` }, flowRef?.provisional_token));
             if (!authRes.success || !authRes.data) {
                 throw new Error(`Re-authorization failed: ${authRes.error?.message ?? 'Unknown error'}`);
             }
@@ -319,10 +334,13 @@ flowRef) {
                 user_code: authRes.data.user_code,
             };
             // Update the mutable ref so the caller (ensureCredentials) can surface
-            // the new URL to the human without restarting the MCP process.
+            // the new URL to the human without restarting the MCP process, and so
+            // a THIRD expiry in the same flow re-sends the latest provisional
+            // token rather than a stale, already-superseded one.
             if (flowRef) {
                 flowRef.verification_uri_complete = newHandle.verification_uri_complete;
                 flowRef.user_code = newHandle.user_code;
+                flowRef.provisional_token = authRes.data.provisional_token;
             }
             stderr('');
             stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -404,7 +422,7 @@ const tools = [
     },
     {
         name: 'dream',
-        description: 'Trigger a memory consolidation dream cycle — promotes important memories and archives old ones.',
+        description: 'Trigger a memory consolidation dream cycle — promotes important memories and archives old ones. Promotion only scans the session tier; active-tier memories move via context-clear or handoff, not dream.',
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -523,6 +541,10 @@ async function main() {
         await import('./cli/sync-memory.js');
         return; // sync-memory.ts calls process.exit() on failure
     }
+    if (process.argv[2] === 'doctor') {
+        await import('./cli/doctor.js');
+        return; // doctor.ts calls process.exit() itself
+    }
     // Agent API key auth mode (CORBOT-B1D3244C) — unattended machines. Checked
     // before any device-flow / OAuth-credential / DID-key-auth setup below so
     // this mode NEVER falls back to those paths (that fallback is what used to
@@ -565,51 +587,50 @@ async function main() {
             if (!isCredsStale(creds.expiresAt, Date.now()))
                 return creds;
             // CORBOT-A5BBD580: tokens live 7 days but the process can outlive
-            // them. Drop stale creds and fall through to silent key auth.
+            // them. Before falling through to key/device auth, re-read the file —
+            // an external repair may have already refreshed it. loadCredentials()
+            // returns null for a still-stale file, so this simplifies to a
+            // re-read + early return (27FA5CDD).
+            creds = loadCredentials();
+            if (creds)
+                return creds;
             stderr('Cached credentials are expired or expiring soon — re-authenticating...');
-            creds = null;
         }
         // ── Key auth (Phase 1 DID auth) ───────────────────────────────────────
-        // If the user has enrolled a private key for this device, sign a
-        // server-issued challenge and skip the device-flow ceremony entirely.
-        // tryKeyAuth() returns null if no key file is present (clean fallback
-        // to device flow) and throws only on real failures (e.g. server says
-        // INVALID_SIGNATURE). On throw we log and continue to device flow —
-        // device flow is the recovery path for "user wiped their key file".
+        let keyResult = null;
         try {
-            const keyResult = await tryKeyAuth({ aisUrl: AIS_URL });
-            if (keyResult) {
-                const claims = decodeJwtClaims(keyResult.token);
-                const tenantId = claims.tenantId ?? '';
-                const resolved = await resolveAgent(keyResult.token, '', tenantId, loadOAuthCredentials()?.agentId);
-                creds = {
-                    token: keyResult.token,
-                    agentId: resolved.agentId,
-                    tenantId: resolved.tenantId || tenantId,
-                    expiresAt: keyResult.expiresAt,
-                };
-                saveCredentials(creds);
-                emitTelemetry({
-                    event: 'auth.key.success',
-                    agentIdHash: hashAgentId(creds.agentId),
-                });
-                stderr('Authenticated via DID key auth (no browser required)');
-                if (!postAuthDone) {
-                    postAuthDone = true;
-                    void runPostAuth(creds);
-                }
-                return creds;
-            }
+            keyResult = await tryKeyAuth({ aisUrl: AIS_URL });
         }
         catch (err) {
-            emitTelemetry({
-                event: 'auth.key.fallback',
-                error: err instanceof Error ? err.message : String(err),
-            });
+            // Real key-auth failure (e.g. INVALID_SIGNATURE / server unreachable).
+            // Device flow remains the recovery path ONLY for this case.
+            emitTelemetry({ event: 'auth.key.fallback', error: err instanceof Error ? err.message : String(err) });
             stderr(`Key auth failed: ${err instanceof Error ? err.message : String(err)}. Falling back to device flow.`);
         }
+        if (keyResult) {
+            // Post-auth failures (agent resolution, claim decode) are REAL errors —
+            // surface them to the caller. They must never route to device flow
+            // (2026-08-24 lockout: a pagination bug here minted ghost agents).
+            const claims = decodeJwtClaims(keyResult.token);
+            const tenantId = claims.tenantId ?? '';
+            const resolved = await resolveAgent(keyResult.token, '', tenantId, loadOAuthCredentials()?.agentId);
+            creds = {
+                token: keyResult.token,
+                agentId: resolved.agentId,
+                tenantId: resolved.tenantId || tenantId,
+                expiresAt: keyResult.expiresAt,
+            };
+            saveCredentials(creds);
+            emitTelemetry({ event: 'auth.key.success', agentIdHash: hashAgentId(creds.agentId) });
+            stderr('Authenticated via DID key auth (no browser required)');
+            if (!postAuthDone) {
+                postAuthDone = true;
+                void runPostAuth(creds);
+            }
+            return creds;
+        }
         if (!activeFlow || activeFlow.dead) {
-            activeFlow = await startDeviceFlow();
+            activeFlow = await startDeviceFlow(activeFlow?.provisional_token);
         }
         const sentinel = Symbol('bond-pending');
         // poll is always set by startDeviceFlow before it returns; this guard
@@ -630,7 +651,7 @@ async function main() {
             // Always say WHY the old flow died: a silent discard here hid three
             // weeks of broken cold-start bonding (CORBOT-9CE03C6E).
             stderr(`Device flow discarded (${err instanceof Error ? err.message : String(err)}); starting a fresh one.`);
-            activeFlow = await startDeviceFlow();
+            activeFlow = await startDeviceFlow(activeFlow.provisional_token);
             throw new BondPendingError(activeFlow.verification_uri_complete, activeFlow.user_code);
         }
         if (got === sentinel) {
@@ -766,8 +787,12 @@ async function main() {
                         const target = await resolveAgentForLoad(token, query);
                         agentId = target.id;
                         // Persist the switch so subsequent tool calls use the new agent.
+                        // saveCredentials() MUST be called here so that a process restart
+                        // (silent MCP reconnect) restores the switched agent from disk
+                        // instead of silently reverting to the default (CORBOT-497C7FA3).
                         if (creds) {
                             creds = { ...creds, agentId };
+                            saveCredentials(creds);
                         }
                         agentContext = await hydrateIdentity(AIS_URL, agentId, token);
                         applyMemoryRefresh(agentId, token);