@agentage/cli 0.0.3 → 0.0.4

package/dist/lib/fs/file-lock.js

@@ -0,0 +1,163 @@
+import { randomBytes } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+// A cross-process advisory lock keyed to a target file (`<target>.lock`). Config read-modify-writes
+// are sub-millisecond, so a lock past this age whose holder is gone is a crashed holder to take over.
+const LOCK_TTL_MS = 10_000;
+// A caller blocks up to this long for a contended lock. Past the TTL so a crashed holder is taken
+// over rather than wedging the caller; a throw only happens if the lock is genuinely stuck.
+const MAX_WAIT_MS = 15_000;
+// Past this age a holder is taken over even if its pid still resolves - the only explanation left is
+// pid reuse after a crash. Far beyond any real critical section or plausible scheduler pause, so a
+// live-but-CPU-starved holder is never mistaken for crashed below it.
+const STALE_HARD_MS = 60_000;
+const STEP_MS = 25;
+const lockPath = (target) => `${target}.lock`;
+// The lock file holds "<pid> <timestamp>": pid gates crash-takeover, the trailing token is the
+// acquisition time used for staleness. A legacy single-token file parses as pid 0 (unknown holder).
+const holderOf = (path) => {
+    try {
+        const parts = readFileSync(path, 'utf-8').trim().split(/\s+/);
+        const at = Number.parseInt(parts[parts.length - 1] ?? '', 10);
+        if (Number.isNaN(at))
+            return null;
+        const pid = parts.length >= 2 ? Number.parseInt(parts[0] ?? '', 10) : 0;
+        return { pid: Number.isNaN(pid) ? 0 : pid, at };
+    }
+    catch {
+        return null;
+    }
+};
+// Same-host liveness probe. ESRCH = the holder is gone (crashed); EPERM = alive but owned by another
+// user. pid 0/unknown counts as gone so a legacy or malformed lock still ages out on the TTL.
+const holderAlive = (pid) => {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+};
+// A holder is safe to take over only once it is past the TTL AND provably gone: a dead pid, our own
+// leftover pid (we cannot be inside our own synchronous section while here), or so old that pid reuse
+// is the only explanation. A live holder merely starved of CPU is NEVER stolen - stealing it would
+// put two writers in the critical section and silently drop an append (issue #249).
+const isCrashed = (holder, now) => {
+    const age = now - holder.at;
+    if (age < LOCK_TTL_MS)
+        return false;
+    if (age >= STALE_HARD_MS)
+        return true;
+    return holder.pid === process.pid || !holderAlive(holder.pid);
+};
+const unlinkQuiet = (path) => {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // already gone
+    }
+};
+// Atomic exclusive create: writeFileSync('wx') is create-then-write, so a concurrent holderOf can
+// read the freshly created but still-empty lock and mistake a live holder for absent (issue #231
+// lost-update). Instead write the full "<pid> <at>" to a unique temp, then linkSync it into place:
+// link is atomic and fails EEXIST if held, so the content is always complete when the lock appears.
+const createLockExclusive = (path, content) => {
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.new`;
+    writeFileSync(tmp, content);
+    try {
+        linkSync(tmp, path);
+    }
+    finally {
+        unlinkQuiet(tmp);
+    }
+};
+// Serialize stale-lock takeover behind its own exclusive create so no taker can delete a lock that
+// turned FRESH mid-takeover (the ABA race: a reader sees the stale timestamp, a winner re-creates
+// the lock, the reader deletes the winner's file). Same O_EXCL-guard design proven in
+// update-lock.ts. Returns whether to re-race the create.
+const takeOverStale = (target, now) => {
+    const path = lockPath(target);
+    const guard = `${path}.takeover`;
+    const guardHeld = holderOf(guard);
+    if (guardHeld !== null && isCrashed(guardHeld, now))
+        unlinkQuiet(guard);
+    try {
+        createLockExclusive(guard, `${process.pid} ${now}`);
+    }
+    catch {
+        return false; // another taker is mid-takeover; let it win
+    }
+    try {
+        const holder = holderOf(path);
+        // A null holder means the lock file exists but its content did not read cleanly. Never treat that
+        // as absent: clearing it here would steal a live holder still writing its bytes. Only a holder we
+        // can positively prove crashed is taken over.
+        if (holder === null || !isCrashed(holder, now))
+            return false;
+        unlinkQuiet(path);
+        return true;
+    }
+    finally {
+        unlinkQuiet(guard);
+    }
+};
+// One-shot acquire: the atomic link IS the mutex - concurrent callers cannot both win it, and the
+// linked content is always complete so no reader sees an empty lock. A fresh or live holder refuses;
+// a crashed one (dead holder past the TTL) is cleared under the takeover guard and re-raced once.
+// `now` is injectable for tests.
+export const acquireFileLock = (target, now = Date.now()) => {
+    mkdirSync(dirname(target), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            createLockExclusive(lockPath(target), `${process.pid} ${now}`);
+            return true;
+        }
+        catch (err) {
+            // Only EEXIST means contention. A permission/read-only error never clears, so failing fast
+            // beats burning the full MAX_WAIT_MS before reporting a generic "could not acquire lock".
+            const code = err.code;
+            if (code !== 'EEXIST') {
+                const path = lockPath(target);
+                throw new Error(code === 'EACCES' || code === 'EPERM' || code === 'EROFS'
+                    ? `permission denied: ${path}`
+                    : `could not write lock file ${path}${code ? ` (${code})` : ''}`);
+            }
+            const holder = holderOf(lockPath(target));
+            // Refuse unless the holder is positively crashed. A null holder (unreadable content) is NOT
+            // proof of a crash: attempting takeover on it once stole a live holder's lock (issue #231).
+            if (holder === null || !isCrashed(holder, now))
+                return false;
+            if (!takeOverStale(target, now))
+                return false;
+        }
+    }
+    return false;
+};
+export const releaseFileLock = (target) => unlinkQuiet(lockPath(target));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Run `fn` while holding the advisory lock for `target`, blocking with bounded backoff until the
+// lock is free (or a crashed holder is taken over past the TTL). `fn` MUST be synchronous: the lock
+// is held only across one synchronous critical section, so in-process callers can never both be
+// inside it. The whole read-modify-write belongs in `fn` - locking only the write still loses
+// updates across the read->write gap. Released in a finally, so a throw never wedges the lock.
+export const withFileLock = async (target, fn) => {
+    const deadline = Date.now() + MAX_WAIT_MS;
+    for (;;) {
+        if (acquireFileLock(target)) {
+            try {
+                return fn();
+            }
+            finally {
+                releaseFileLock(target);
+            }
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`could not acquire lock for ${target} within ${MAX_WAIT_MS}ms`);
+        }
+        await sleep(STEP_MS + Math.floor(Math.random() * STEP_MS));
+    }
+};

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

@@ -0,0 +1,30 @@
+import { type EditInput, type ListResult, type MemoryView, type SearchResult, type VaultsConfig, type WriteResult } from '@agentage/memory-core';
+export interface DeleteResult {
+    path: string;
+    deleted: boolean;
+}
+export declare const translateEngineMessage: (message: string) => string;
+export interface VerbOptions {
+    vault?: string;
+}
+export interface SearchOptions extends VerbOptions {
+    folder?: string;
+    limit?: number;
+    tags?: string[];
+    cursor?: string;
+}
+export interface ListOptions extends VerbOptions {
+    depth?: 1 | 2;
+    tags?: string[];
+}
+export interface MemoryClient {
+    search(query: string, opts?: SearchOptions): Promise<SearchResult>;
+    read(ref: string, opts?: VerbOptions): Promise<MemoryView>;
+    write(ref: string, body: string, opts?: VerbOptions & {
+        frontmatter?: Record<string, unknown>;
+    }): Promise<WriteResult>;
+    edit(ref: string, op: Omit<EditInput, 'path'>, opts?: VerbOptions): Promise<WriteResult>;
+    list(folder: string | undefined, opts?: ListOptions): Promise<ListResult>;
+    delete(ref: string, opts?: VerbOptions): Promise<DeleteResult>;
+}
+export declare const createDirectClient: (config: VaultsConfig) => MemoryClient;

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

@@ -0,0 +1,98 @@
+import { createRegistry, createRouter, } from '@agentage/memory-core';
+// Engine (memory-core) messages leak MCP tool vocabulary (`memory__list`, ...) unfit for a terminal.
+// Rewrite the known patterns to CLI vocabulary at this seam; do not fork the engine.
+const ENGINE_MESSAGE_MAP = [
+    [
+        /Use memory__list with no folder to see available vaults\.?/g,
+        'Run `agentage vault list` to see available vaults.',
+    ],
+];
+export const translateEngineMessage = (message) => ENGINE_MESSAGE_MAP.reduce((m, [pattern, replacement]) => m.replace(pattern, replacement), message);
+// --vault becomes an @-prefix so the router resolves it; an explicit @<vault>/... passes through.
+const scopeRef = (ref, vault) => ref.startsWith('@') ? ref : vault ? `@${vault}/${ref}` : ref;
+const scopeFolder = (folder, vault) => {
+    if (vault)
+        return folder ? `@${vault}/${folder}` : `@${vault}`;
+    return folder || undefined;
+};
+export const createDirectClient = (config) => {
+    let ctxP;
+    const ctx = () => {
+        if (!ctxP) {
+            ctxP = (async () => {
+                const registry = await createRegistry(config);
+                // Offline engine: only local (git working-copy) backends are usable here.
+                const local = registry.list().filter((h) => h.backend.capabilities().kind === 'local');
+                if (local.length === 0)
+                    throw new Error('no local vaults registered - run `agentage vault add <name> --local`');
+                const def = registry.default();
+                const defaultHandle = def && local.some((h) => h.id === def.id) ? def : undefined;
+                return {
+                    router: createRouter(local, defaultHandle),
+                    multi: local.length > 1,
+                    hasDefault: !!defaultHandle,
+                };
+            })();
+            ctxP.catch(() => (ctxP = undefined));
+        }
+        return ctxP;
+    };
+    // A single-target verb on a bare ref needs a vault when >1 is registered and none is default.
+    const requireTarget = (ref, c) => {
+        if (c.multi && !c.hasDefault && !ref.startsWith('@'))
+            throw new Error('multiple vaults - use --vault <name>, @<vault>/<path>, or set "default" in vaults.json');
+    };
+    return {
+        async search(query, opts = {}) {
+            const { router } = await ctx();
+            return router.search({
+                query,
+                folder: scopeFolder(opts.folder, opts.vault),
+                tags: opts.tags,
+                limit: opts.limit,
+                cursor: opts.cursor,
+            });
+        },
+        async read(ref, opts = {}) {
+            const c = await ctx();
+            const target = scopeRef(ref, opts.vault);
+            requireTarget(target, c);
+            const view = await c.router.read(target);
+            if (!view)
+                throw new Error(`not found: ${ref}`);
+            return view;
+        },
+        async write(ref, body, opts = {}) {
+            const c = await ctx();
+            const target = scopeRef(ref, opts.vault);
+            requireTarget(target, c);
+            return c.router.write({ path: target, body, frontmatter: opts.frontmatter });
+        },
+        async edit(ref, op, opts = {}) {
+            const c = await ctx();
+            const target = scopeRef(ref, opts.vault);
+            requireTarget(target, c);
+            const receipt = await c.router.edit({ ...op, path: target });
+            if (!receipt)
+                throw new Error(`not found: ${ref}`);
+            return receipt;
+        },
+        async list(folder, opts = {}) {
+            const { router } = await ctx();
+            return router.list({
+                folder: scopeFolder(folder, opts.vault),
+                depth: opts.depth,
+                tags: opts.tags,
+            });
+        },
+        async delete(ref, opts = {}) {
+            const c = await ctx();
+            const target = scopeRef(ref, opts.vault);
+            requireTarget(target, c);
+            const deleted = await c.router.delete(target);
+            if (!deleted)
+                throw new Error(`not found: ${ref}`);
+            return { path: target, deleted };
+        },
+    };
+};

package/dist/lib/net/http.d.ts

@@ -0,0 +1,6 @@
+export interface UnrefResponse {
+    ok: boolean;
+    status: number;
+    json: unknown;
+}
+export declare const fetchJsonUnref: (url: string, timeoutMs: number, headers?: Record<string, string>) => Promise<UnrefResponse | null>;

package/dist/lib/net/http.js

@@ -0,0 +1,32 @@
+import { get } from 'node:https';
+// node:https instead of global fetch: undici keeps a ref'd ~10s connect timer alive even after
+// its AbortSignal fires, stalling process exit on an unreachable network. req.destroy() from an
+// unref'd timer caps the whole attempt and frees the event loop the moment it settles. Never
+// throws: an unreachable host or malformed body resolves null (unreachable) or json:null.
+export const fetchJsonUnref = (url, timeoutMs, headers = {}) => new Promise((resolve) => {
+    const req = get(url, { headers: { Accept: 'application/json', ...headers } }, (res) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+            body += chunk;
+        });
+        res.on('end', () => {
+            const status = res.statusCode ?? 0;
+            let json = null;
+            try {
+                json = body ? JSON.parse(body) : null;
+            }
+            catch {
+                json = null;
+            }
+            resolve({ ok: status >= 200 && status < 300, status, json });
+        });
+    });
+    const timer = setTimeout(() => req.destroy(), timeoutMs);
+    timer.unref();
+    req.once('error', () => resolve(null));
+    req.once('close', () => {
+        clearTimeout(timer);
+        resolve(null); // no-op when already resolved
+    });
+});

package/dist/lib/{origins.d.ts → net/origins.d.ts}

@@ -4,9 +4,9 @@ export interface Links {
     api: string;
     auth: string;
     mcp: string;
+    sync: string;
 }
 export declare const normalizeFqdn: (raw?: string) => string;
 export declare const siteFqdn: () => string;
 export declare const environment: (fqdn: string) => Env;
 export declare const links: (fqdn: string) => Links;
-//# sourceMappingURL=origins.d.ts.map

package/dist/lib/net/origins.js

@@ -0,0 +1,39 @@
+const DEFAULT_FQDN = 'agentage.io';
+export const normalizeFqdn = (raw) => {
+    const value = (raw ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, '')
+        .replace(/\/+$/, '');
+    return value || DEFAULT_FQDN;
+};
+export const siteFqdn = () => normalizeFqdn(process.env['AGENTAGE_SITE_FQDN']);
+const isLocal = (fqdn) => fqdn === 'localhost' || fqdn.startsWith('localhost:') || fqdn.startsWith('127.0.0.1');
+// A loopback-IP-with-port fqdn (`127.0.0.1:<port>`) collapses every service onto that one
+// origin, path-prefixed - the single-server stub convention the hermetic e2e drives. The bare
+// `localhost` / `localhost:<port>` dev fqdns keep the multi-port dev mapping below untouched.
+const stubOrigin = (fqdn) => {
+    const m = fqdn.match(/^127\.0\.0\.1:(\d+)$/);
+    return m ? `http://127.0.0.1:${m[1]}` : null;
+};
+export const environment = (fqdn) => isLocal(fqdn) || fqdn.startsWith('dev.') ? 'development' : 'production';
+export const links = (fqdn) => {
+    const stub = stubOrigin(fqdn);
+    if (stub)
+        return { site: stub, api: `${stub}/api`, auth: stub, mcp: `${stub}/mcp`, sync: stub };
+    return isLocal(fqdn)
+        ? {
+            site: 'http://localhost:3000',
+            api: 'http://localhost:3001/api',
+            auth: 'http://localhost:3010',
+            mcp: 'http://localhost:3003/mcp',
+            sync: 'http://localhost:3011',
+        }
+        : {
+            site: `https://${fqdn}`,
+            api: `https://api.${fqdn}/api`,
+            auth: `https://auth.${fqdn}`,
+            mcp: `https://memory.${fqdn}/mcp`,
+            sync: `https://sync.${fqdn}`,
+        };
+};

package/dist/lib/net/user-agent.d.ts

@@ -0,0 +1,6 @@
+export type RequestComponent = 'cli' | 'daemon';
+export interface RequestHeaderOptions {
+    component: RequestComponent;
+    daemonVersion?: string;
+}
+export declare const requestHeaders: (opts: RequestHeaderOptions) => Record<string, string>;

package/dist/lib/net/user-agent.js

@@ -0,0 +1,7 @@
+import { VERSION } from '../../utils/version.js';
+// Identify the caller + versions so the server can observe which CLI + daemon connect.
+export const requestHeaders = (opts) => ({
+    'User-Agent': `agentage-${opts.component}/${VERSION}`,
+    'X-Agentage-CLI-Version': VERSION,
+    'X-Agentage-Daemon-Version': opts.component === 'daemon' ? VERSION : (opts.daemonVersion ?? 'none'),
+});

package/dist/lib/status/format.d.ts

@@ -0,0 +1 @@
+export declare const formatUptime: (seconds: number) => string;

package/dist/lib/status/format.js

@@ -0,0 +1,12 @@
+// Compact "Hh Mm" / "Mm Ss" uptime, matching the daemon and status rows. Seconds only under a
+// minute; hours dropped once zero so short-lived daemons read cleanly.
+export const formatUptime = (seconds) => {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s}s`;
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    if (h > 0)
+        return `${h}h ${m}m`;
+    return `${m}m ${s % 60}s`;
+};

package/dist/lib/status/status-info.d.ts

@@ -0,0 +1,45 @@
+import { type AuthEnvMismatch } from '../auth/env-match.js';
+import { type AuthState } from '../fs/config.js';
+import { type Env } from '../net/origins.js';
+import { type UpdateInfo } from '../update/update-check.js';
+import { type VaultStatus } from './vaults-status.js';
+export interface DaemonSyncSummary {
+    vaults: number;
+    state: 'ok' | 'error' | 'syncing';
+    lastRun?: string;
+    lastError?: string;
+}
+export interface DaemonStatus {
+    running: boolean;
+    pid?: number;
+    port: number;
+    uptimeSeconds?: number;
+    mcp?: boolean;
+    daemonVersion?: string;
+    sync?: DaemonSyncSummary;
+}
+export interface StatusReport {
+    version: string;
+    fqdn: string;
+    env: Env;
+    target: {
+        fqdn: string;
+        env: Env;
+        reachable: boolean;
+    };
+    auth: {
+        signedIn: boolean;
+        tokenExpiresAt?: string;
+        note?: string;
+        transient?: boolean;
+        mismatch?: AuthEnvMismatch;
+    };
+    endpoint: {
+        url: string;
+        reachable: boolean;
+    };
+    update: UpdateInfo;
+    daemon?: DaemonStatus;
+    vaults: VaultStatus[];
+}
+export declare const gatherStatus: (auth: AuthState | null, fqdn: string) => Promise<StatusReport>;

package/dist/lib/status/status-info.js

@@ -0,0 +1,107 @@
+import { AuthRequiredError, introspectToken } from '../auth/api.js';
+import { detectEnvMismatch } from '../auth/env-match.js';
+import { health, syncStatus } from '../daemon/daemon-client.js';
+import { fetchJsonUnref } from '../net/http.js';
+import { requestHeaders } from '../net/user-agent.js';
+import { environment, links } from '../net/origins.js';
+import { checkForUpdate } from '../update/update-check.js';
+import { VERSION } from '../../utils/version.js';
+import { isDaemonRunning, resolvePort } from '../../daemon/lifecycle.js';
+import { buildVaultStatuses } from './vaults-status.js';
+// node:https via fetchJsonUnref, not global fetch: undici's ref'd connect timer keeps the process
+// alive ~10s after an aborted request on a packet-drop network, stalling `status` exit.
+const checkEndpoint = async (apiUrl, headers) => {
+    const res = await fetchJsonUnref(`${apiUrl}/health`, 3000, headers);
+    return res?.ok ?? false;
+};
+// Host reachability, not app health: the site root answers any HTTP status (200/3xx/4xx) when the
+// host is up, so any non-null response counts as reachable; only a refused/timed-out connect fails.
+const checkSite = async (siteUrl, headers) => {
+    const res = await fetchJsonUnref(siteUrl, 3000, headers);
+    return res !== null;
+};
+// Fold the git + couch per-vault states into one summary: any error wins, then any in-flight
+// run, else ok. lastRun is the freshest reported; lastError the first seen.
+const summarizeSync = (sync) => {
+    const git = Array.isArray(sync.vaults) ? sync.vaults : [];
+    const couch = Array.isArray(sync.couch) ? sync.couch : [];
+    const vaults = git.length + couch.length;
+    const error = git.find((v) => v.lastError)?.lastError ?? couch.find((v) => v.lastError)?.lastError;
+    const running = git.some((v) => v.running) || couch.some((v) => v.running);
+    const state = error ? 'error' : running ? 'syncing' : 'ok';
+    const runs = [...git.map((v) => v.lastRun), ...couch.map((v) => v.lastSync)].filter((r) => Boolean(r));
+    const lastRun = runs.sort().at(-1);
+    return { vaults, state, lastRun, lastError: error };
+};
+const probeDaemon = async () => {
+    const port = resolvePort();
+    const h = await health(port);
+    if (!h)
+        return { status: { running: isDaemonRunning(), port }, sync: null };
+    const sync = await syncStatus(port);
+    const summary = sync ? summarizeSync(sync) : undefined;
+    const status = {
+        running: true,
+        pid: h.pid,
+        port,
+        uptimeSeconds: h.uptime,
+        // Absent on a legacy daemon that predates the /mcp gate; treat undefined as serving (on).
+        mcp: h.mcp !== false,
+        daemonVersion: h.version,
+        sync: summary && summary.vaults > 0 ? summary : undefined,
+    };
+    return { status, sync };
+};
+// AuthRequiredError = truly expired (terminal). TransientAuthError (or any non-terminal) = a blip
+// while we could not re-verify: never rendered as expired, never told to run setup, exit stays 0.
+const classifyAuthError = (err) => err instanceof AuthRequiredError
+    ? { signedIn: false, note: 'session expired - run: agentage setup' }
+    : { signedIn: true, transient: true, note: 'signed in (could not re-verify - temporary)' };
+// A credential issued for one environment, checked against another, is not expired - it belongs
+// elsewhere. Name both sides and hint the two fixes, without introspecting cross-environment.
+const mismatchAuth = (m) => ({
+    signedIn: false,
+    mismatch: m,
+    note: `signed in to ${m.credentialFqdn} - CLI targets ${m.targetFqdn} (${m.targetEnv}); ` +
+        `run: agentage setup to sign into ${m.targetEnv}, or set AGENTAGE_SITE_FQDN=${m.credentialFqdn}`,
+});
+export const gatherStatus = async (auth, fqdn) => {
+    const target = links(fqdn);
+    const env = environment(fqdn);
+    // Probe the local daemon first (fast, 1s-capped /health) so its version can ride the probe headers.
+    const probe = await probeDaemon();
+    const headers = requestHeaders({ component: 'cli', daemonVersion: probe.status.daemonVersion });
+    // Endpoint reachability and the (npm-registry) update check are independent - run them
+    // together so `status` stays snappy.
+    const [reachable, siteReachable, update] = await Promise.all([
+        checkEndpoint(target.api, headers),
+        checkSite(target.site, headers),
+        checkForUpdate(VERSION),
+    ]);
+    const report = {
+        version: VERSION,
+        fqdn,
+        env,
+        target: { fqdn, env, reachable: siteReachable },
+        auth: { signedIn: false, note: 'not signed in - run: agentage setup' },
+        endpoint: { url: target.api, reachable },
+        update,
+        daemon: probe.status,
+        vaults: buildVaultStatuses(probe.sync, probe.status.running),
+    };
+    if (!auth)
+        return report;
+    const mismatch = detectEnvMismatch(auth, fqdn);
+    if (mismatch) {
+        report.auth = mismatchAuth(mismatch);
+        return report;
+    }
+    try {
+        const session = await introspectToken(auth, target);
+        report.auth = { signedIn: true, tokenExpiresAt: session.expiresAt };
+    }
+    catch (err) {
+        report.auth = classifyAuthError(err);
+    }
+    return report;
+};

package/dist/lib/status/vaults-format.d.ts

@@ -0,0 +1,2 @@
+import { type VaultStatus } from './vaults-status.js';
+export declare const vaultLines: (vaults: VaultStatus[]) => string[];

package/dist/lib/status/vaults-format.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+const mark = (good) => (good ? chalk.green('✓') : chalk.red('✗'));
+// HH:MM in local time; a malformed timestamp falls back to the raw string so we never crash.
+const shortTime = (iso) => {
+    if (!iso)
+        return '';
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime())
+        ? iso
+        : `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+};
+const shortError = (err) => (err ?? 'sync failed').split('\n')[0]?.slice(0, 40) ?? 'sync failed';
+// One right-hand status cell per vault, sharing the check/cross marks with the other status rows.
+const statusCell = (v) => {
+    switch (v.status) {
+        case 'ok':
+            return `${mark(true)} last ok ${shortTime(v.lastRun)}`.trimEnd();
+        case 'syncing':
+            return `${chalk.yellow('⋯')} syncing`;
+        case 'error':
+            return `${mark(false)} error (${shortError(v.lastError)})`;
+        case 'unknown':
+            return chalk.dim('- unknown (daemon stopped)');
+        case 'idle':
+            return v.channel === 'local' ? chalk.dim('- local only') : chalk.dim('- idle');
+    }
+};
+const countLabel = (vaults) => {
+    const connected = vaults.filter((v) => v.channel !== 'local').length;
+    if (connected > 0)
+        return `${connected} connected`;
+    const n = vaults.length;
+    return `${n} ${n === 1 ? 'vault' : 'vaults'}`;
+};
+// The `vaults` block: a header count line then one aligned `<name> <channel> <status>` row per vault.
+// Zero vaults prints a single actionable hint instead of an empty block.
+export const vaultLines = (vaults) => {
+    if (vaults.length === 0)
+        return [`${'vaults'.padEnd(10)} none - run: agentage vault add <name> --local`];
+    const nameW = Math.max(...vaults.map((v) => v.name.length));
+    const header = `${'vaults'.padEnd(10)} ${countLabel(vaults)}`;
+    const rows = vaults.map((v) => `  ${v.name.padEnd(nameW)}  ${v.channel.padEnd(6)} ${statusCell(v)}`);
+    return [header, ...rows];
+};

package/dist/lib/status/vaults-status.d.ts

@@ -0,0 +1,12 @@
+import { type VaultsConfig } from '@agentage/memory-core';
+import { type SyncStatus } from '../../sync/git/manager.js';
+export type VaultChannel = 'local' | 'git' | 'cloud';
+export type VaultSyncState = 'ok' | 'syncing' | 'error' | 'idle' | 'unknown';
+export interface VaultStatus {
+    name: string;
+    channel: VaultChannel;
+    status: VaultSyncState;
+    lastRun?: string;
+    lastError?: string;
+}
+export declare const buildVaultStatuses: (sync: SyncStatus | null, daemonUp: boolean, config?: VaultsConfig) => VaultStatus[];