@dinoxx/dinox-cli 1.0.22 → 1.1.0

package/dist/commands/doctor.js

@@ -0,0 +1,539 @@
+import { existsSync } from 'node:fs';
+import { hydrateResolvedAuthIdentity } from '../auth/userInfo.js';
+import { getPowerSyncDbPath } from '../config/paths.js';
+import { loadConfig } from '../config/store.js';
+import { fingerprintDaemonRuntimeConfig, resolveConfig } from '../config/resolve.js';
+import { getDaemonInfo, isDaemonFresh, shutdownDaemonForExclusiveAccess } from '../daemon/client.js';
+import { restartDaemonLocked } from '../daemon/index.js';
+import { acquireDaemonStartLock, getDaemonSocketPath, isProcessRunning, readPid, } from '../daemon/pid.js';
+import { DEFAULT_DAEMON_PORT } from '../daemon/types.js';
+import { closePowerSyncAndReleaseOwner, connectPowerSync, getStatusSnapshot, waitForUploadQueueEmpty, } from '../powersync/runtime.js';
+import { inspectNoteTokenIndex, rebuildNoteTokenIndex, } from '../powersync/tokenIndex.js';
+import { getPackageVersion } from '../utils/version.js';
+import { parseSyncTimeoutMs } from '../utils/syncTimeout.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printHumanReadableWarning, printSuccess, } from '../utils/output.js';
+import { registerStandaloneCommand } from './descriptor/register.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from './schema/globalOptions.js';
+const DEFAULT_DOCTOR_TIMEOUT_MS = 10_000;
+const doctorPreparationDependencies = {
+    loadConfig,
+    resolveConfig,
+    hydrateAuthIdentity: hydrateResolvedAuthIdentity,
+    acquireDaemonStartLock,
+    captureDaemonSnapshot,
+    shutdownDaemon: shutdownDaemonForExclusiveAccess,
+    connectPowerSync,
+    restartDaemon: restartDaemonLocked,
+};
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function issue(issues, condition, message) {
+    if (condition) {
+        issues.push(message);
+    }
+}
+function doctorTimeoutMs(globals, config) {
+    return parseSyncTimeoutMs(globals.syncTimeout) ?? Math.min(config.sync.timeoutMs, DEFAULT_DOCTOR_TIMEOUT_MS);
+}
+export async function prepareDoctorRuntime(context, overrides = {}) {
+    const dependencies = { ...doctorPreparationDependencies, ...overrides };
+    const releaseDaemonStartLock = await dependencies.acquireDaemonStartLock(parseSyncTimeoutMs(context.globals.syncTimeout) ?? DEFAULT_DOCTOR_TIMEOUT_MS);
+    try {
+        const rawConfig = await dependencies.loadConfig();
+        const baseConfig = dependencies.resolveConfig(rawConfig);
+        const offline = Boolean(context.globals.offline);
+        const timeoutMs = doctorTimeoutMs(context.globals, baseConfig);
+        let config = baseConfig;
+        let authError = null;
+        let syncError = null;
+        if (!offline && baseConfig.auth.authorization) {
+            try {
+                const hydrated = await dependencies.hydrateAuthIdentity(baseConfig, { timeoutMs });
+                config = hydrated.config;
+            }
+            catch (error) {
+                authError = errorMessage(error);
+            }
+        }
+        const daemonBefore = await dependencies.captureDaemonSnapshot();
+        const daemonDbPath = daemonBefore.info ? getPowerSyncDbPath(daemonBefore.info.userId) : null;
+        const targetDbPath = getPowerSyncDbPath(config.auth.userId);
+        const daemonWasStopped = Boolean(daemonBefore.info
+            && daemonDbPath === targetDbPath
+            && await dependencies.shutdownDaemon(Math.min(timeoutMs, 10_000), daemonBefore.info.instanceId));
+        try {
+            if (!offline && config.auth.authorization && !authError) {
+                try {
+                    const connected = await dependencies.connectPowerSync({
+                        config,
+                        offline: false,
+                        timeoutMs,
+                        expectedTokenFingerprint: config.auth.tokenFingerprint ?? null,
+                    });
+                    return {
+                        db: connected.db,
+                        dbPath: connected.dbPath,
+                        config,
+                        authError,
+                        syncError,
+                        offline,
+                        timeoutMs,
+                        releaseOwner: connected.releaseOwner,
+                        daemonBefore,
+                        daemonWasStopped,
+                        releaseDaemonStartLock,
+                        daemonStartLockReleased: false,
+                        released: false,
+                    };
+                }
+                catch (error) {
+                    syncError = errorMessage(error);
+                }
+            }
+            const opened = await dependencies.connectPowerSync({
+                config,
+                offline: true,
+                timeoutMs,
+                expectedTokenFingerprint: config.auth.tokenFingerprint ?? null,
+            });
+            return {
+                db: opened.db,
+                dbPath: opened.dbPath,
+                config,
+                authError,
+                syncError,
+                offline,
+                timeoutMs,
+                releaseOwner: opened.releaseOwner,
+                daemonBefore,
+                daemonWasStopped,
+                releaseDaemonStartLock,
+                daemonStartLockReleased: false,
+                released: false,
+            };
+        }
+        catch (error) {
+            await restoreStoppedDoctorDaemon(config, daemonBefore, daemonWasStopped, dependencies.restartDaemon);
+            throw error;
+        }
+    }
+    catch (error) {
+        await releaseDaemonStartLock().catch((releaseError) => {
+            printHumanReadableWarning(`warning: failed to release daemon lifecycle lock: ${errorMessage(releaseError)}`);
+        });
+        throw error;
+    }
+}
+async function readUploadQueueCount(db) {
+    try {
+        const stats = await db.getUploadQueueStats(false);
+        return stats.count;
+    }
+    catch {
+        return null;
+    }
+}
+async function inspectDbIntegrity(db, dbPath) {
+    try {
+        const rows = await db.getAll('PRAGMA integrity_check', []);
+        const messages = rows
+            .flatMap((row) => Object.values(row))
+            .map((value) => String(value ?? '').trim())
+            .filter(Boolean);
+        const ok = messages.length === 1 && messages[0]?.toLowerCase() === 'ok';
+        return {
+            status: ok ? 'ok' : 'error',
+            path: dbPath,
+            integrity: ok ? 'ok' : 'error',
+            ...(ok ? {} : { message: messages.join('; ') || 'integrity_check returned no result' }),
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            path: dbPath,
+            integrity: 'unknown',
+            message: errorMessage(error),
+        };
+    }
+}
+async function captureDaemonSnapshot() {
+    return {
+        info: await getDaemonInfo(),
+        pidInfo: readPid(),
+        socketExists: process.platform !== 'win32' && existsSync(getDaemonSocketPath()),
+    };
+}
+function inspectDaemon(config, snapshot) {
+    const { info, pidInfo, socketExists } = snapshot;
+    const version = getPackageVersion();
+    const expectedUserId = config.auth.userId ?? null;
+    const running = Boolean(info);
+    const unreachable = !info && Boolean((pidInfo && isProcessRunning(pidInfo.pid))
+        || socketExists);
+    const versionMatch = info ? info.version === version : null;
+    const accountMatch = info ? info.userId === expectedUserId : null;
+    const tokenMatch = info
+        ? info.tokenFingerprint === (config.auth.tokenFingerprint ?? null)
+        : null;
+    const runtimeConfigFingerprint = fingerprintDaemonRuntimeConfig(config);
+    const runtimeConfigMatch = info
+        ? info.runtimeConfigFingerprint === runtimeConfigFingerprint
+        : null;
+    const fresh = info
+        ? isDaemonFresh(info, version, expectedUserId, config.auth.tokenFingerprint ?? null, runtimeConfigFingerprint)
+        : false;
+    const pidFileMatches = Boolean(info
+        && pidInfo
+        && pidInfo.pid === info.pid
+        && pidInfo.instanceId === info.instanceId);
+    return {
+        status: unreachable ? 'error' : !info || fresh ? 'ok' : 'warn',
+        running,
+        pid: info?.pid || (pidInfo && isProcessRunning(pidInfo.pid) ? pidInfo.pid : null),
+        port: pidFileMatches ? pidInfo?.port ?? null : null,
+        transport: 'socket',
+        socket_path: info?.socketPath ?? (socketExists ? getDaemonSocketPath() : null),
+        version: info?.version ?? null,
+        user_id: info?.userId ?? null,
+        authenticated: info?.authenticated ?? null,
+        version_match: versionMatch,
+        account_match: accountMatch,
+        token_match: tokenMatch,
+        runtime_config_match: runtimeConfigMatch,
+        ...(unreachable ? { error: 'Daemon artifacts exist, but the private socket is not responding.' } : {}),
+    };
+}
+async function restoreStoppedDoctorDaemon(config, snapshot, daemonWasStopped, restart = restartDaemonLocked) {
+    if (!daemonWasStopped || inspectDaemon(config, snapshot).status !== 'ok') {
+        return;
+    }
+    const port = snapshot.pidInfo?.port ?? DEFAULT_DAEMON_PORT;
+    await restart(port, { quiet: true }).catch((error) => {
+        printHumanReadableWarning(`warning: failed to restore daemon after doctor command: ${errorMessage(error)}`);
+    });
+}
+function inspectAuth(runtime) {
+    const hasToken = Boolean(runtime.config.auth.authorization);
+    if (!hasToken) {
+        return {
+            status: 'error',
+            logged_in: false,
+            verified: false,
+            user_id: null,
+            username: null,
+            email: null,
+        };
+    }
+    if (runtime.authError) {
+        return {
+            status: 'error',
+            logged_in: true,
+            verified: false,
+            user_id: runtime.config.auth.userId ?? null,
+            username: runtime.config.auth.username ?? null,
+            email: runtime.config.auth.email ?? null,
+            error: runtime.authError,
+        };
+    }
+    return {
+        status: runtime.config.auth.userId ? 'ok' : 'warn',
+        logged_in: true,
+        verified: !runtime.offline,
+        user_id: runtime.config.auth.userId ?? null,
+        username: runtime.config.auth.username ?? null,
+        email: runtime.config.auth.email ?? null,
+    };
+}
+async function inspectSync(runtime) {
+    const snapshot = getStatusSnapshot(runtime.db);
+    const uploadQueue = await readUploadQueueCount(runtime.db);
+    const uploadError = snapshot.dataFlowStatus.uploadError;
+    const downloadError = snapshot.dataFlowStatus.downloadError;
+    const result = {
+        status: 'ok',
+        connected: snapshot.connected,
+        connecting: snapshot.connecting,
+        has_synced: snapshot.hasSynced,
+        last_synced_at: snapshot.lastSyncedAt,
+        upload_queue: uploadQueue,
+        downloading: snapshot.dataFlowStatus.downloading,
+        uploading: snapshot.dataFlowStatus.uploading,
+        ...(downloadError ? { download_error: downloadError } : {}),
+        ...(uploadError ? { upload_error: uploadError } : {}),
+        ...(runtime.syncError ? { error: runtime.syncError } : {}),
+    };
+    result.status = doctorSyncStatus(runtime, result);
+    return result;
+}
+function doctorSyncStatus(runtime, sync) {
+    if (runtime.syncError || sync.error || sync.upload_error || sync.download_error) {
+        return 'error';
+    }
+    if (runtime.offline || !runtime.config.auth.authorization) {
+        return 'skipped';
+    }
+    if (!sync.connected || !sync.has_synced || sync.upload_queue === null || sync.upload_queue > 0) {
+        return 'warn';
+    }
+    return 'ok';
+}
+function refreshDoctorSyncSnapshot(runtime, sync) {
+    const snapshot = getStatusSnapshot(runtime.db);
+    sync.connected = snapshot.connected;
+    sync.connecting = snapshot.connecting;
+    sync.has_synced = snapshot.hasSynced;
+    sync.last_synced_at = snapshot.lastSyncedAt;
+    sync.downloading = snapshot.dataFlowStatus.downloading;
+    sync.uploading = snapshot.dataFlowStatus.uploading;
+    if (snapshot.dataFlowStatus.downloadError) {
+        sync.download_error = snapshot.dataFlowStatus.downloadError;
+    }
+    else {
+        delete sync.download_error;
+    }
+    if (snapshot.dataFlowStatus.uploadError) {
+        sync.upload_error = snapshot.dataFlowStatus.uploadError;
+    }
+    else {
+        delete sync.upload_error;
+    }
+}
+function summarizeIndex(inspection) {
+    return {
+        ...inspection,
+        status: inspection.drift === 0 && inspection.ftsAvailable ? 'ok' : 'warn',
+    };
+}
+export async function applyDatabaseFixes(runtime, payload) {
+    if (payload.sync.upload_queue && payload.sync.upload_queue > 0 && !runtime.offline && !runtime.syncError) {
+        const result = await waitForUploadQueueEmpty(runtime.db, runtime.timeoutMs);
+        const fixStatus = result.ok
+            ? 'ok'
+            : result.uploadError || result.queueError
+                ? 'error'
+                : 'warn';
+        payload.fixes.push({
+            target: 'upload_queue',
+            status: fixStatus,
+            message: result.ok
+                ? 'Upload queue drained.'
+                : result.uploadError
+                    ? `Upload failed while waiting for the queue: ${result.uploadError.message}. No queued mutations were discarded.`
+                    : result.queueError
+                        ? `Upload queue could not be verified: ${result.queueError.message}. No queued mutations were discarded.`
+                        : `Upload queue still has ${result.pendingCount ?? 'an unknown number of'} pending mutation(s). No queued mutations were discarded.`,
+        });
+        payload.sync.upload_queue = result.pendingCount;
+        refreshDoctorSyncSnapshot(runtime, payload.sync);
+        if (result.uploadError) {
+            payload.sync.upload_error = result.uploadError;
+        }
+        payload.sync.status = doctorSyncStatus(runtime, payload.sync);
+    }
+    if (payload.index.drift > 0 || !payload.index.ftsAvailable) {
+        await rebuildNoteTokenIndex(runtime.db);
+        const rebuilt = summarizeIndex(await inspectNoteTokenIndex(runtime.db));
+        payload.index = rebuilt;
+        payload.fixes.push({
+            target: 'index',
+            status: rebuilt.status,
+            message: rebuilt.drift === 0 ? 'Rebuilt note FTS index.' : `Rebuilt note FTS index; drift remains ${rebuilt.drift}.`,
+        });
+    }
+}
+function daemonNeedsRepair(daemon) {
+    return !daemon.running
+        || daemon.version_match === false
+        || daemon.account_match === false
+        || daemon.token_match === false
+        || daemon.authenticated === false
+        || daemon.status === 'error';
+}
+export async function releaseDoctorRuntime(runtime) {
+    if (runtime.released) {
+        return;
+    }
+    await closePowerSyncAndReleaseOwner(runtime.db, runtime.releaseOwner);
+    runtime.released = true;
+}
+export async function releaseDoctorDaemonStartLock(runtime) {
+    if (runtime.daemonStartLockReleased) {
+        return;
+    }
+    try {
+        await runtime.releaseDaemonStartLock();
+        runtime.daemonStartLockReleased = true;
+    }
+    catch (error) {
+        printHumanReadableWarning(`warning: failed to release daemon lifecycle lock: ${errorMessage(error)}`);
+    }
+}
+export async function applyDoctorDaemonLifecycle(runtime, payload, fixRequested, dependencies = {
+    restart: restartDaemonLocked,
+    capture: captureDaemonSnapshot,
+}) {
+    if (!runtime.released) {
+        throw new Error('Doctor daemon lifecycle cannot run while the PowerSync owner lease is held.');
+    }
+    const needsRepair = daemonNeedsRepair(payload.daemon);
+    const repairRequested = Boolean(fixRequested && runtime.config.auth.userId && needsRepair);
+    const restoreRequired = Boolean(runtime.daemonWasStopped && payload.daemon.status === 'ok');
+    if (!repairRequested && !restoreRequired) {
+        if (runtime.daemonWasStopped) {
+            payload.daemon = {
+                ...payload.daemon,
+                running: false,
+                pid: null,
+                port: null,
+                socket_path: null,
+            };
+        }
+        return;
+    }
+    try {
+        const port = runtime.daemonBefore.pidInfo?.port ?? DEFAULT_DAEMON_PORT;
+        await dependencies.restart(port, { quiet: true });
+        payload.daemon = inspectDaemon(runtime.config, await dependencies.capture());
+        if (repairRequested) {
+            payload.fixes.push({
+                target: 'daemon',
+                status: payload.daemon.status,
+                message: payload.daemon.running ? 'Restarted daemon.' : 'Daemon restart did not leave a running daemon.',
+            });
+        }
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        payload.daemon = {
+            ...payload.daemon,
+            status: 'error',
+            running: false,
+            pid: null,
+            port: null,
+            socket_path: null,
+            error: message,
+        };
+        if (repairRequested) {
+            payload.fixes.push({
+                target: 'daemon',
+                status: 'error',
+                message,
+            });
+        }
+    }
+}
+export function finalizeDoctorPayload(payload) {
+    const issues = payload.issues;
+    issue(issues, payload.auth.status === 'error', payload.auth.error ?? 'auth is not configured');
+    issue(issues, payload.auth.status === 'warn', 'auth token is present but user identity is not verified');
+    issue(issues, payload.sync.status === 'error', payload.sync.error ?? payload.sync.upload_error?.message ?? payload.sync.download_error?.message ?? 'sync error');
+    issue(issues, payload.sync.status === 'warn', !payload.sync.connected
+        ? 'PowerSync is not connected'
+        : !payload.sync.has_synced
+            ? 'PowerSync has not completed a sync'
+            : payload.sync.upload_queue === null
+                ? 'upload queue status is unavailable'
+                : `upload queue has ${payload.sync.upload_queue} pending mutation(s)`);
+    issue(issues, !payload.index.ftsAvailable, 'note FTS index table is missing');
+    issue(issues, payload.index.ftsAvailable && payload.index.drift > 0, `note FTS index drift is ${payload.index.drift}`);
+    issue(issues, payload.daemon.status !== 'ok', payload.daemon.error ?? 'daemon version/account/token does not match current CLI');
+    issue(issues, payload.db.status !== 'ok', payload.db.message ?? 'database integrity check failed');
+    for (const fix of payload.fixes) {
+        issue(issues, fix.status === 'error', `${fix.target} fix failed: ${fix.message}`);
+    }
+    payload.healthy = issues.length === 0;
+    payload.fixed = payload.fixes.some((fix) => fix.status === 'ok');
+    return payload;
+}
+function printHumanDoctor(payload) {
+    printHumanReadableLine(`healthy: ${payload.healthy ? 'yes' : 'no'}`);
+    printHumanReadableLine(`auth: ${payload.auth.status}${payload.auth.user_id ? ` (${payload.auth.user_id})` : ''}`);
+    printHumanReadableLine(`sync: ${payload.sync.status} connected=${payload.sync.connected} last_synced_at=${payload.sync.last_synced_at ?? '(none)'} upload_queue=${payload.sync.upload_queue ?? 'unknown'}`);
+    printHumanReadableLine(`index: ${payload.index.status} notes=${payload.index.notes} fts_rows=${payload.index.ftsRows} drift=${payload.index.drift}`);
+    printHumanReadableLine(`daemon: ${payload.daemon.status} running=${payload.daemon.running} transport=${payload.daemon.transport} socket=${payload.daemon.socket_path ?? '(none)'} version_match=${payload.daemon.version_match ?? 'unknown'} account_match=${payload.daemon.account_match ?? 'unknown'} token_match=${payload.daemon.token_match ?? 'unknown'} runtime_config_match=${payload.daemon.runtime_config_match ?? 'unknown'}`);
+    printHumanReadableLine(`db: ${payload.db.status} integrity=${payload.db.integrity} path=${payload.db.path}`);
+    if (payload.fixes.length > 0) {
+        printHumanReadableLine('fixes:');
+        for (const fix of payload.fixes) {
+            printHumanReadableLine(`- ${fix.target}: ${fix.status} - ${fix.message}`);
+        }
+    }
+    if (payload.issues.length > 0) {
+        printHumanReadableLine('issues:');
+        for (const entry of payload.issues) {
+            printHumanReadableLine(`- ${entry}`);
+        }
+    }
+}
+async function runDoctor(context) {
+    const runtime = await prepareDoctorRuntime(context);
+    try {
+        let payload;
+        let inspectionError;
+        try {
+            payload = {
+                ok: true,
+                healthy: false,
+                fixed: false,
+                auth: inspectAuth(runtime),
+                sync: await inspectSync(runtime),
+                index: summarizeIndex(await inspectNoteTokenIndex(runtime.db)),
+                daemon: inspectDaemon(runtime.config, runtime.daemonBefore),
+                db: await inspectDbIntegrity(runtime.db, runtime.dbPath),
+                fixes: [],
+                issues: [],
+            };
+            if (Boolean(context.options.fix)) {
+                await applyDatabaseFixes(runtime, payload);
+            }
+        }
+        catch (error) {
+            inspectionError = error;
+        }
+        finally {
+            await releaseDoctorRuntime(runtime);
+        }
+        if (inspectionError) {
+            await restoreStoppedDoctorDaemon(runtime.config, runtime.daemonBefore, runtime.daemonWasStopped);
+            throw inspectionError;
+        }
+        if (!payload) {
+            throw new Error('Doctor did not produce a health report.');
+        }
+        await applyDoctorDaemonLifecycle(runtime, payload, Boolean(context.options.fix));
+        const finalized = finalizeDoctorPayload(payload);
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess(finalized);
+            return;
+        }
+        printHumanDoctor(finalized);
+    }
+    finally {
+        await releaseDoctorDaemonStartLock(runtime);
+    }
+}
+export const doctorCommandDescriptor = {
+    name: 'doctor',
+    description: 'Check Dinox CLI health across auth, sync, local indexes, daemon, and database integrity',
+    options: [
+        { flags: '--fix', description: 'Safely repair local indexes, drain upload queue, and restart stale daemon', type: 'boolean' },
+    ],
+    schema: {
+        path: 'doctor',
+        risk: 'write',
+        auth: 'optional',
+        globalOptions: [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS],
+        output: {
+            type: 'structured',
+            summary: 'Health report for auth, sync, indexes, daemon, and local database',
+            fields: ['healthy', 'fixed', 'auth', 'sync', 'index', 'daemon', 'db', 'fixes', 'issues'],
+        },
+        examples: ['dino doctor --format json', 'dino doctor --fix --format json'],
+    },
+    action: runDoctor,
+};
+export function registerDoctorCommand(program) {
+    registerStandaloneCommand(program, doctorCommandDescriptor);
+}

package/dist/commands/graph/index.d.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import type { CommandGroupDescriptor } from '../descriptor/types.js';
 export declare const graphCommandGroup: CommandGroupDescriptor;
 export declare function registerGraphCommands(program: Command): void;

package/dist/commands/graph/index.js

@@ -4,7 +4,7 @@ import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
 import { DinoxError } from '../../utils/errors.js';
 import { printSuccess } from '../../utils/output.js';
-import { syncBeforeCommand, withCommandRuntime } from '../runtime.js';
+import { commandStale, syncBeforeCommand, withCommandRuntime } from '../runtime.js';
 import { getBacklinks, getGraphStats, getOutlinks, getRelatedNotes } from './repo.js';
 const GRAPH_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
 function parseDepth(value) {
@@ -24,28 +24,42 @@ function parseDepth(value) {
     }
     return Math.trunc(parsed);
 }
-async function withOfflineDb(command, fn) {
-    const globals = command.optsWithGlobals?.() ?? {};
-    if (!Boolean(globals.offline)) {
-        throw new DinoxError('withOfflineDb called without --offline');
-    }
-    return withCommandRuntime(command, async ({ db }) => fn(db));
-}
 async function runGraphCommand(context, onlineAction, offlineAction) {
     const globals = context.globals;
-    if (Boolean(globals.offline)) {
-        printSuccess(await withOfflineDb(context.command, offlineAction));
-        return;
-    }
-    if (Boolean(globals.requireSync)) {
+    if (Boolean(globals.offline) || Boolean(globals.requireSync)) {
         await withCommandRuntime(context, async (runtime) => {
-            await syncBeforeCommand(runtime, { syncTokenIndex: true });
-            printSuccess(await offlineAction(runtime.db));
+            await syncBeforeCommand(runtime);
+            printSuccess({
+                ...(await offlineAction(runtime.db)),
+                stale: commandStale(runtime),
+            });
         });
         return;
     }
-    await ensureDaemonRunning();
-    printSuccess(await onlineAction());
+    try {
+        await ensureDaemonRunning();
+        const result = await onlineAction();
+        const record = result && typeof result === 'object' && !Array.isArray(result)
+            ? result
+            : {};
+        printSuccess({
+            ...record,
+            stale: typeof record.stale === 'boolean' ? record.stale : true,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DinoxError(`Daemon execution failed: ${message}`, {
+            code: 'DAEMON_UNAVAILABLE',
+            cause: error,
+            suggestion: 'Run `dino doctor --fix --format json` to repair local daemon state, or retry with `--offline` to use the local cache directly.',
+            suggestedAction: {
+                command: 'dino doctor --fix --format json',
+                reason: 'Default online graph reads require the daemon-owned database runtime.',
+            },
+            recoverable: true,
+        });
+    }
 }
 const graphBacklinksCommand = {
     name: 'backlinks',
@@ -59,7 +73,7 @@ const graphBacklinksCommand = {
         output: {
             type: 'structured',
             summary: 'Backlink graph payload',
-            fields: ['note_id', 'backlinks'],
+            fields: ['note_id', 'backlinks', 'count', 'stale'],
         },
         examples: ['dino graph backlinks <id> --format json'],
     },
@@ -83,7 +97,7 @@ const graphOutlinksCommand = {
         output: {
             type: 'structured',
             summary: 'Outlink graph payload',
-            fields: ['note_id', 'outlinks'],
+            fields: ['note_id', 'outlinks', 'count', 'stale'],
         },
         examples: ['dino graph outlinks <id> --format json'],
     },
@@ -108,7 +122,7 @@ const graphRelatedCommand = {
         output: {
             type: 'structured',
             summary: 'Related-notes graph payload',
-            fields: ['note_id', 'depth', 'related_notes'],
+            fields: ['note_id', 'depth', 'related', 'count', 'stale'],
         },
         examples: ['dino graph related <id> --depth 2 --format json'],
     },
@@ -133,7 +147,7 @@ const graphStatsCommand = {
             type: 'structured',
             summary: 'Graph statistics payload',
             entity: 'graph_stats',
-            fields: ['notes_count', 'links_count', 'connected_notes_count', 'isolated_notes_count'],
+            fields: ['notes_count', 'links_count', 'connected_notes_count', 'isolated_notes_count', 'stale'],
         },
         examples: ['dino graph stats --format json'],
     },