@phnx-labs/agents-cli 1.20.16 → 1.20.18

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 5;
+const SCHEMA_VERSION = 6;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -53,6 +53,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   label TEXT,
   message_count INTEGER,
   token_count INTEGER,
+  cost_usd REAL,
+  duration_ms INTEGER,
   file_path TEXT NOT NULL,
   file_mtime_ms INTEGER,
   file_size INTEGER,
@@ -141,6 +143,19 @@ function migrateSchema(db, fromVersion) {
         // repopulate under canonical keys.
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 6) {
+        // v5 → v6: cost ($) and wall-clock duration are now computed at scan time
+        // from raw per-model token usage. Add the columns and force a full rescan
+        // so every existing session gets its cost_usd / duration_ms populated.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'cost_usd')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN cost_usd REAL`);
+        }
+        if (!cols.some(c => c.name === 'duration_ms')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN duration_ms INTEGER`);
+        }
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -350,10 +365,12 @@ const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, version, account, timestamp,
     project, cwd, git_branch, topic, label, message_count, token_count,
+    cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
+    @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin
   )
   ON CONFLICT(id) DO UPDATE SET
@@ -369,6 +386,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     label = excluded.label,
     message_count = excluded.message_count,
     token_count = excluded.token_count,
+    cost_usd = excluded.cost_usd,
+    duration_ms = excluded.duration_ms,
     file_path = excluded.file_path,
     file_mtime_ms = excluded.file_mtime_ms,
     file_size = excluded.file_size,
@@ -409,6 +428,8 @@ export function upsertSession(meta, content, scan) {
         label: meta.label ?? null,
         message_count: meta.messageCount ?? null,
         token_count: meta.tokenCount ?? null,
+        cost_usd: meta.costUsd ?? null,
+        duration_ms: meta.durationMs ?? null,
         file_path: meta.filePath,
         file_mtime_ms: scan?.fileMtimeMs ?? null,
         file_size: scan?.fileSize ?? null,
@@ -482,6 +503,8 @@ export function upsertSessionsBatch(entries) {
                 label: meta.label ?? null,
                 message_count: meta.messageCount ?? null,
                 token_count: meta.tokenCount ?? null,
+                cost_usd: meta.costUsd ?? null,
+                duration_ms: meta.durationMs ?? null,
                 file_path: meta.filePath,
                 file_mtime_ms: scan?.fileMtimeMs ?? null,
                 file_size: scan?.fileSize ?? null,
@@ -548,6 +571,8 @@ function rowToMeta(row) {
         gitBranch: row.git_branch ?? undefined,
         messageCount: row.message_count ?? undefined,
         tokenCount: row.token_count ?? undefined,
+        costUsd: row.cost_usd ?? undefined,
+        durationMs: row.duration_ms ?? undefined,
         version: row.version ?? undefined,
         account: row.account ?? undefined,
         topic: row.topic ?? undefined,
@@ -611,7 +636,14 @@ export function querySessions(options = {}) {
     const limitClause = options.limit
         ? `LIMIT ${Math.max(1, Math.floor(options.limit)) + 16}`
         : '';
-    const sql = `SELECT * FROM sessions ${clause} ORDER BY timestamp DESC ${limitClause}`;
+    // NULLs last so unpriced / duration-less rows never crowd out real data when
+    // sorting by cost or duration. timestamp is never null (NOT NULL column).
+    const orderClause = options.sortBy === 'cost'
+        ? 'ORDER BY cost_usd IS NULL, cost_usd DESC, timestamp DESC'
+        : options.sortBy === 'duration'
+            ? 'ORDER BY duration_ms IS NULL, duration_ms DESC, timestamp DESC'
+            : 'ORDER BY timestamp DESC';
+    const sql = `SELECT * FROM sessions ${clause} ${orderClause} ${limitClause}`;
     const rows = db.prepare(sql).all(...params);
     // Belt-and-suspenders: drop rows whose JSONL no longer exists on disk. The
     // authoritative fix is to keep file_path in sync (see updateSessionFilePaths
@@ -631,6 +663,56 @@ export function countSessions(options = {}) {
     const row = db.prepare(sql).get(...params);
     return row ? row.n : 0;
 }
+/**
+ * Aggregate cost / duration / tokens across sessions, grouped by agent,
+ * project, or calendar day. Honors the same filter shape as querySessions
+ * (agent, since/until, team-origin) so `agents cost --since 7d --by day`
+ * lines up with what `agents sessions` would list. Ordered by cost desc.
+ */
+export function queryUsageRollup(options) {
+    const db = getDB();
+    const { clause, params } = buildSessionWhere(options);
+    const keyExpr = options.groupBy === 'agent'
+        ? 'agent'
+        : options.groupBy === 'project'
+            ? `IFNULL(NULLIF(project, ''), '(no project)')`
+            // ISO timestamps are lexicographically date-sortable; the date is the
+            // first 10 chars (YYYY-MM-DD).
+            : `substr(timestamp, 1, 10)`;
+    const sql = `
+    SELECT
+      ${keyExpr} AS key,
+      IFNULL(SUM(cost_usd), 0) AS costUsd,
+      IFNULL(SUM(duration_ms), 0) AS durationMs,
+      COUNT(*) AS sessionCount,
+      IFNULL(SUM(token_count), 0) AS tokenCount
+    FROM sessions
+    ${clause}
+    GROUP BY key
+    ORDER BY costUsd DESC, key ASC
+  `;
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Return the N most expensive sessions (cost_usd DESC, NULLs excluded),
+ * honoring the same filter shape as querySessions. Drops rows whose JSONL
+ * vanished, mirroring querySessions' liveness filter.
+ */
+export function topSessionsByCost(n, options = {}) {
+    const db = getDB();
+    const { clause, params } = buildSessionWhere(options);
+    const whereCost = clause ? `${clause} AND cost_usd IS NOT NULL` : 'WHERE cost_usd IS NOT NULL';
+    const limit = Math.max(1, Math.floor(n));
+    // Over-fetch a small buffer to survive the on-disk liveness filter below.
+    const sql = `SELECT * FROM sessions ${whereCost} ORDER BY cost_usd DESC, timestamp DESC LIMIT ${limit + 16}`;
+    const rows = db.prepare(sql).all(...params);
+    const live = rows.filter(r => !r.file_path || fs.existsSync(r.file_path));
+    return live.slice(0, limit).map(r => ({
+        meta: rowToMeta(r),
+        costUsd: r.cost_usd ?? 0,
+        durationMs: r.duration_ms ?? 0,
+    }));
+}
 /** Return the set of all file paths currently tracked in the sessions table. */
 export function getAllFilePaths() {
     const db = getDB();

package/dist/lib/session/discover.d.ts

@@ -25,6 +25,8 @@ export interface DiscoverOptions {
     excludeTeamOrigin?: boolean;
     /** Keep only team-spawned sessions (used for hidden-count queries). */
     onlyTeamOrigin?: boolean;
+    /** Column to order results by (all descending): 'timestamp' (default), 'cost', or 'duration'. */
+    sortBy?: 'timestamp' | 'cost' | 'duration';
     /** Called as each agent makes parsing progress. Totals count only files that need re-parsing (cache misses). */
     onProgress?: (progress: ScanProgress) => void;
 }

package/dist/lib/session/discover.js

@@ -20,6 +20,7 @@ import { walkForFiles } from '../fs-walk.js';
 import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
+import { costOfUsage } from '../pricing/index.js';
 import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
@@ -108,6 +109,7 @@ function buildQueryOptions(options, agents, opts) {
         limit: opts.includeLimit ? (options?.limit ?? 50) : undefined,
         excludeTeamOrigin: options?.excludeTeamOrigin,
         onlyTeamOrigin: options?.onlyTeamOrigin,
+        sortBy: options?.sortBy,
     };
 }
 /** Resolve and canonicalize a working directory path (follows symlinks). */
@@ -402,6 +404,8 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             label,
             messageCount: scan.messageCount,
             tokenCount: scan.tokenCount,
+            costUsd: scan.costUsd,
+            durationMs: scan.durationMs,
             isTeamOrigin,
         };
     }
@@ -417,6 +421,8 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             label,
             messageCount: scan.messageCount,
             tokenCount: scan.tokenCount,
+            costUsd: scan.costUsd,
+            durationMs: scan.durationMs,
             topic: scan.topic,
             isTeamOrigin,
         };
@@ -529,6 +535,8 @@ async function readCodexMeta(filePath, account, currentVersion) {
         topic: scan.topic,
         messageCount: scan.messageCount,
         tokenCount: scan.tokenCount,
+        costUsd: scan.costUsd,
+        durationMs: scan.durationMs,
         account,
     };
     return { meta, content: scan.contentText || '' };
@@ -642,10 +650,15 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
     const cwd = projectInfo?.path ? normalizeCwd(projectInfo.path) : undefined;
     const stat = safeStatSync(filePath);
     const messages = Array.isArray(session.messages) ? session.messages : [];
+    const sessionModel = typeof session.model === 'string' ? session.model : undefined;
     let topic;
     let messageCount = 0;
     let tokenCount = 0;
     let sawTokenCount = false;
+    let costUsd = 0;
+    let sawCost = false;
+    let firstTsMs;
+    let lastTsMs;
     const userTexts = [];
     for (const message of messages) {
         if (message.type === 'user') {
@@ -662,12 +675,43 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
                 messageCount++;
             }
         }
+        // Duration: messages carry a `timestamp` on most Gemini CLI versions.
+        const tsRaw = message.timestamp ?? message.time;
+        if (typeof tsRaw === 'string' || typeof tsRaw === 'number') {
+            const ms = new Date(tsRaw).getTime();
+            if (!Number.isNaN(ms)) {
+                if (firstTsMs === undefined || ms < firstTsMs)
+                    firstTsMs = ms;
+                if (lastTsMs === undefined || ms > lastTsMs)
+                    lastTsMs = ms;
+            }
+        }
         const total = getGeminiTokenCount(message.tokens);
         if (total !== null) {
             tokenCount += total;
             sawTokenCount = true;
         }
+        // Per-message cost: directional tokens × this message's model price.
+        const msgModel = (typeof message.model === 'string' ? message.model : undefined) || sessionModel;
+        const tk = message.tokens;
+        if (msgModel && tk && typeof tk === 'object') {
+            const c = costOfUsage({
+                model: msgModel,
+                inputTokens: typeof tk.input === 'number' ? tk.input : undefined,
+                outputTokens: (typeof tk.output === 'number' ? tk.output : 0) +
+                    (typeof tk.thoughts === 'number' ? tk.thoughts : 0) +
+                    (typeof tk.tool === 'number' ? tk.tool : 0),
+                cacheReadTokens: typeof tk.cached === 'number' ? tk.cached : undefined,
+            });
+            if (c > 0) {
+                costUsd += c;
+                sawCost = true;
+            }
+        }
     }
+    const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
+        ? lastTsMs - firstTsMs
+        : undefined;
     const meta = {
         id: sessionId,
         shortId: sessionId.slice(0, 8),
@@ -680,6 +724,8 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
         topic,
         messageCount,
         tokenCount: sawTokenCount ? tokenCount : undefined,
+        costUsd: sawCost ? costUsd : undefined,
+        durationMs,
     };
     return { meta, content: userTexts.join('\n') };
 }
@@ -1206,6 +1252,11 @@ async function scanClaudeSession(filePath) {
     let messageCount = 0;
     let tokenCount = 0;
     let sawTokenCount = false;
+    let costUsd = 0;
+    let sawCost = false;
+    // Track the first and last timestamped event to derive wall-clock duration.
+    let firstTsMs;
+    let lastTsMs;
     const seenAssistantIds = new Set();
     const userTexts = [];
     try {
@@ -1224,6 +1275,16 @@ async function scanClaudeSession(filePath) {
             if (!entrypoint && typeof parsed.entrypoint === 'string') {
                 entrypoint = parsed.entrypoint;
             }
+            // Track duration across every timestamped event, not just the first.
+            if (typeof parsed.timestamp === 'string') {
+                const ms = new Date(parsed.timestamp).getTime();
+                if (!Number.isNaN(ms)) {
+                    if (firstTsMs === undefined || ms < firstTsMs)
+                        firstTsMs = ms;
+                    if (lastTsMs === undefined || ms > lastTsMs)
+                        lastTsMs = ms;
+                }
+            }
             if (!timestamp && (parsed.type === 'user' || parsed.type === 'assistant') && parsed.timestamp) {
                 timestamp = parsed.timestamp;
                 cwd = parsed.cwd || '';
@@ -1252,17 +1313,37 @@ async function scanClaudeSession(filePath) {
                 continue;
             seenAssistantIds.add(logicalId);
             messageCount++;
-            const usage = getClaudeUsageTotal(parsed.message?.usage || parsed.usage);
+            const usageObj = parsed.message?.usage || parsed.usage;
+            const usage = getClaudeUsageTotal(usageObj);
             if (usage !== null) {
                 tokenCount += usage;
                 sawTokenCount = true;
             }
+            // Per-assistant-message cost: each event carries its own model, so we
+            // multiply that event's raw token directions by that model's price.
+            const model = parsed.message?.model;
+            if (model && usageObj && typeof usageObj === 'object') {
+                const eventCost = costOfUsage({
+                    model,
+                    inputTokens: usageObj.input_tokens,
+                    outputTokens: usageObj.output_tokens,
+                    cacheReadTokens: usageObj.cache_read_input_tokens,
+                    cacheCreationTokens: usageObj.cache_creation_input_tokens,
+                });
+                if (eventCost > 0) {
+                    costUsd += eventCost;
+                    sawCost = true;
+                }
+            }
         }
     }
     finally {
         rl.close();
         stream.destroy();
     }
+    const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
+        ? lastTsMs - firstTsMs
+        : undefined;
     return {
         timestamp,
         cwd,
@@ -1272,6 +1353,8 @@ async function scanClaudeSession(filePath) {
         entrypoint,
         messageCount,
         tokenCount: sawTokenCount ? tokenCount : undefined,
+        costUsd: sawCost ? costUsd : undefined,
+        durationMs,
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
     };
 }
@@ -1287,6 +1370,10 @@ async function scanCodexSession(filePath) {
     let topic;
     let messageCount = 0;
     let tokenCount;
+    let model;
+    let lastTotalTokenUsage;
+    let firstTsMs;
+    let lastTsMs;
     const userTexts = [];
     try {
         for await (const line of rl) {
@@ -1299,6 +1386,16 @@ async function scanCodexSession(filePath) {
             catch {
                 continue;
             }
+            // Track duration across every timestamped event.
+            if (typeof parsed.timestamp === 'string') {
+                const ms = new Date(parsed.timestamp).getTime();
+                if (!Number.isNaN(ms)) {
+                    if (firstTsMs === undefined || ms < firstTsMs)
+                        firstTsMs = ms;
+                    if (lastTsMs === undefined || ms > lastTsMs)
+                        lastTsMs = ms;
+                }
+            }
             if (parsed.type === 'session_meta') {
                 const payload = parsed.payload || {};
                 sessionId = payload.id || sessionId;
@@ -1306,6 +1403,7 @@ async function scanCodexSession(filePath) {
                 cwd = payload.cwd || cwd;
                 gitBranch = payload.git?.branch || gitBranch;
                 version = payload.cli_version || payload.version || version;
+                model = payload.model || model;
                 continue;
             }
             if (parsed.type === 'response_item' && parsed.payload?.type === 'message') {
@@ -1324,9 +1422,18 @@ async function scanCodexSession(filePath) {
                 continue;
             }
             if (parsed.type === 'event_msg' && parsed.payload?.type === 'token_count') {
-                const total = getCodexTokenCount(parsed.payload.info?.total_token_usage);
+                const totalUsage = parsed.payload.info?.total_token_usage;
+                const total = getCodexTokenCount(totalUsage);
                 if (total !== null)
                     tokenCount = total;
+                // token_count is cumulative — keep the latest snapshot and price it once
+                // after the stream, so we don't double-count across intermediate events.
+                if (totalUsage && typeof totalUsage === 'object')
+                    lastTotalTokenUsage = totalUsage;
+                // Codex also stamps the model on the rate_limits/token_count payload on
+                // some versions; prefer session_meta but fall back to it.
+                if (!model && typeof parsed.payload.info?.model === 'string')
+                    model = parsed.payload.info.model;
             }
         }
     }
@@ -1334,6 +1441,21 @@ async function scanCodexSession(filePath) {
         rl.close();
         stream.destroy();
     }
+    // Price the final cumulative token snapshot once, against the session model.
+    let costUsd;
+    if (model && lastTotalTokenUsage) {
+        const c = costOfUsage({
+            model,
+            inputTokens: lastTotalTokenUsage.input_tokens,
+            outputTokens: (lastTotalTokenUsage.output_tokens ?? 0) + (lastTotalTokenUsage.reasoning_output_tokens ?? 0),
+            cacheReadTokens: lastTotalTokenUsage.cached_input_tokens,
+        });
+        if (c > 0)
+            costUsd = c;
+    }
+    const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
+        ? lastTsMs - firstTsMs
+        : undefined;
     return {
         sessionId,
         timestamp,
@@ -1343,6 +1465,8 @@ async function scanCodexSession(filePath) {
         topic,
         messageCount,
         tokenCount,
+        costUsd,
+        durationMs,
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
     };
 }

package/dist/lib/session/render.d.ts

@@ -57,6 +57,8 @@ export interface SessionStats {
 }
 /** Compute aggregate statistics (turns, tools, tokens, duration) from session events. */
 export declare function computeSummaryStats(events: SessionEvent[]): SessionStats;
+/** Format a duration in milliseconds as a human-readable string (e.g. '12 min', '2h 30min'). */
+export declare function formatDuration(ms: number): string;
 /**
  * Return the stats line for a session summary header.
  * e.g. "221 turns · 198 tools (10 errors) · 67.5M cached / 361K out · 12 min"

package/dist/lib/session/render.js

@@ -218,7 +218,7 @@ function formatTokenCount(n) {
     return (m >= 100 ? Math.round(m) : parseFloat(m.toFixed(1))) + 'M';
 }
 /** Format a duration in milliseconds as a human-readable string (e.g. '12 min', '2h 30min'). */
-function formatDuration(ms) {
+export function formatDuration(ms) {
     const totalMin = Math.round(ms / 60_000);
     if (totalMin < 1)
         return 'under 1 min';

package/dist/lib/session/types.d.ts

@@ -52,6 +52,10 @@ export interface SessionMeta {
     gitBranch?: string;
     messageCount?: number;
     tokenCount?: number;
+    /** Total USD cost, computed at scan time from per-model token usage (issue #323). */
+    costUsd?: number;
+    /** Wall-clock duration in ms (lastTs − firstTs), persisted at scan time. */
+    durationMs?: number;
     version?: string;
     account?: string;
     topic?: string;

package/dist/lib/sync-umbrella.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Umbrella `agents sync` orchestration — "make this machine current".
+ *
+ * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
+ * then reconciles it into every installed agent's version home. Each stage is
+ * an existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run (`planUmbrellaStages`). The
+ * planner is pure so the flag matrix is unit-tested without any I/O.
+ *
+ * Stage backends:
+ *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
+ *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
+ *               cleanly when none is available — tokenized non-interactive auth
+ *               arrives with `agents login`, #366/#367)
+ *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
+ */
+/** The five umbrella flags off `agents sync`. */
+export interface UmbrellaFlags {
+    repos?: boolean;
+    secrets?: boolean;
+    sessions?: boolean;
+    cloud?: boolean;
+    local?: boolean;
+}
+/** Which stages a given flag combination runs. */
+export interface UmbrellaPlan {
+    fetchRepos: boolean;
+    fetchSecrets: boolean;
+    fetchSessions: boolean;
+    reconcile: boolean;
+}
+/**
+ * Decide which stages run. Pure — no I/O. Semantics:
+ *   bare (no flags)        fetch all three, then reconcile
+ *   --local                reconcile only, no fetch
+ *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ * `--local` wins over everything; `--cloud` suppresses reconcile.
+ */
+export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
+export interface UmbrellaResult {
+    plan: UmbrellaPlan;
+    repos?: {
+        pulled: number;
+        errors: string[];
+    };
+    secrets?: {
+        pulled: number;
+        skipped: boolean;
+        reason?: string;
+        errors: string[];
+    };
+    sessions?: {
+        ran: boolean;
+        pushed: number;
+        pulled: number;
+        merged: number;
+    };
+    reconciled: boolean;
+}
+export interface RunUmbrellaArgs {
+    flags: UmbrellaFlags;
+    /** Progress sink (already quiet-aware in the caller). */
+    log: (msg: string) => void;
+    /** Pass `skipPrompts` through to reconcile / non-interactive behavior. */
+    yes: boolean;
+    /** Secrets passphrase, if available (env var or prompt). Undefined => skip secrets. */
+    passphrase?: string;
+}
+/**
+ * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * A failure in one fetch stage is recorded and does not abort the others or the
+ * reconcile — `agents sync` should make as much current as it can in one pass.
+ */
+export declare function runUmbrellaSync(args: RunUmbrellaArgs): Promise<UmbrellaResult>;

package/dist/lib/sync-umbrella.js

@@ -0,0 +1,125 @@
+/**
+ * Umbrella `agents sync` orchestration — "make this machine current".
+ *
+ * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
+ * then reconciles it into every installed agent's version home. Each stage is
+ * an existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run (`planUmbrellaStages`). The
+ * planner is pure so the flag matrix is unit-tested without any I/O.
+ *
+ * Stage backends:
+ *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
+ *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
+ *               cleanly when none is available — tokenized non-interactive auth
+ *               arrives with `agents login`, #366/#367)
+ *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
+ */
+import { pullRepo } from './git.js';
+import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
+import { listRemoteBundles, pullBundle } from './secrets/sync.js';
+/**
+ * Decide which stages run. Pure — no I/O. Semantics:
+ *   bare (no flags)        fetch all three, then reconcile
+ *   --local                reconcile only, no fetch
+ *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ * `--local` wins over everything; `--cloud` suppresses reconcile.
+ */
+export function planUmbrellaStages(f) {
+    if (f.local) {
+        return { fetchRepos: false, fetchSecrets: false, fetchSessions: false, reconcile: true };
+    }
+    const anySelector = !!(f.repos || f.secrets || f.sessions);
+    if (anySelector) {
+        return {
+            fetchRepos: !!f.repos,
+            fetchSecrets: !!f.secrets,
+            fetchSessions: !!f.sessions,
+            reconcile: !f.cloud,
+        };
+    }
+    // No per-type selector: bare = all + reconcile; --cloud = all, no reconcile.
+    return { fetchRepos: true, fetchSecrets: true, fetchSessions: true, reconcile: !f.cloud };
+}
+/**
+ * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * A failure in one fetch stage is recorded and does not abort the others or the
+ * reconcile — `agents sync` should make as much current as it can in one pass.
+ */
+export async function runUmbrellaSync(args) {
+    const { flags, log, yes, passphrase } = args;
+    const plan = planUmbrellaStages(flags);
+    const result = { plan, reconciled: false };
+    if (plan.fetchRepos) {
+        const dirs = [
+            { alias: 'user', dir: getUserAgentsDir() },
+            ...getEnabledExtraRepos().map((e) => ({ alias: e.alias, dir: e.dir })),
+        ];
+        let pulled = 0;
+        const errors = [];
+        for (const { alias, dir } of dirs) {
+            const r = await pullRepo(dir);
+            if (r.success) {
+                pulled++;
+                log(`repos: ${alias} → ${r.commit}`);
+            }
+            else {
+                errors.push(`${alias}: ${r.error ?? 'unknown error'}`);
+            }
+        }
+        result.repos = { pulled, errors };
+    }
+    if (plan.fetchSecrets) {
+        if (!passphrase) {
+            result.secrets = {
+                pulled: 0,
+                skipped: true,
+                reason: 'no passphrase — set AGENTS_SECRETS_PASSPHRASE or run `agents login` (#366)',
+                errors: [],
+            };
+            log('secrets: skipped (no passphrase available)');
+        }
+        else {
+            let pulled = 0;
+            const errors = [];
+            try {
+                const remote = await listRemoteBundles();
+                for (const b of remote) {
+                    try {
+                        await pullBundle(b.name, { passphrase, force: true });
+                        pulled++;
+                        log(`secrets: ${b.name}`);
+                    }
+                    catch (err) {
+                        errors.push(`${b.name}: ${err.message}`);
+                    }
+                }
+            }
+            catch (err) {
+                errors.push(err.message);
+            }
+            result.secrets = { pulled, skipped: false, errors };
+        }
+    }
+    if (plan.fetchSessions) {
+        // Gate exactly like the daemon: a missing r2.backups bundle is a clean no-op,
+        // not an error that fails the whole sync.
+        const { isSyncConfigured } = await import('./session/sync/config.js');
+        if (isSyncConfigured()) {
+            const { syncSessions } = await import('./session/sync/sync.js');
+            const r = await syncSessions();
+            result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };
+            log(`sessions: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}`);
+        }
+        else {
+            result.sessions = { ran: false, pushed: 0, pulled: 0, merged: 0 };
+        }
+    }
+    if (plan.reconcile) {
+        const { refresh } = await import('./refresh.js');
+        await refresh({ skipPrompts: yes });
+        result.reconciled = true;
+    }
+    return result;
+}