@phnx-labs/agents-cli 1.22.7 → 1.22.8

package/dist/lib/profiles.js

@@ -199,11 +199,46 @@ export function profileAuthLabel(profile) {
     return provider;
 }
 /**
- * Header label for the harness — the slot `AGENTS[id].name` fills for a native
- * harness, so `agents view` can print custom and native harnesses the same way.
+ * Curated vendor/brand display names, matched case-insensitively per token.
+ * Entries with a space (e.g. 'Moonshot AI') are single-token → multi-word expansions.
+ */
+const VENDOR_TABLE = [
+    ['deepseek', 'DeepSeek'],
+    ['openai', 'OpenAI'],
+    ['anthropic', 'Anthropic'],
+    ['claude', 'Claude'],
+    ['grok', 'Grok'],
+    ['xai', 'xAI'],
+    ['gpt', 'GPT'],
+    ['meta', 'Meta'],
+    ['mistral', 'Mistral'],
+    ['mistralai', 'Mistral'],
+    ['qwen', 'Qwen'],
+    ['gemini', 'Gemini'],
+    ['moonshot', 'Moonshot AI'],
+    ['moonshotai', 'Moonshot AI'],
+    ['kimi', 'Kimi'],
+    ['cohere', 'Cohere'],
+    ['perplexity', 'Perplexity'],
+];
+function tokenToDisplayName(token) {
+    const lower = token.toLowerCase();
+    for (const [key, display] of VENDOR_TABLE) {
+        if (lower === key)
+            return display;
+    }
+    return token.charAt(0).toUpperCase() + token.slice(1);
+}
+/**
+ * Header label for the harness — derived from `profile.name` by splitting on
+ * `[-_]` and mapping each token through the vendor/brand table. Never reads
+ * the stored `label` field; old YAML files with a `label:` key are unaffected.
+ *
+ * Examples: `deepseek-flash` → `'DeepSeek Flash'`, `spark` → `'Spark'`,
+ * `deepseek_chat_v3` → `'DeepSeek Chat V3'`.
  */
 export function profileLabel(profile) {
-    return profile.label || profile.name;
+    return profile.name.split(/[-_]/).map(tokenToDisplayName).join(' ');
 }
 /** Build a stable, machine-readable summary for list and view surfaces. */
 export function profileSummary(profile) {
@@ -300,8 +335,6 @@ export function profileFromHostModel(name, host, model, opts = {}) {
         provider: opts.provider ?? host,
         forkedFrom: host,
     };
-    if (opts.label)
-        profile.label = opts.label;
     if (opts.provider && opts.authEnvVar) {
         profile.auth = { envVar: opts.authEnvVar, keychainItem: keychainItemName(opts.provider) };
         profile.authOptional = false;
@@ -337,14 +370,6 @@ export function forkProfile(source, name, opts = {}) {
         description: opts.description ?? (opts.model ? `Forked from ${source.name}: ${opts.model}` : source.description),
         forkedFrom: source.name,
     };
-    // `label` is the header `agents view` prints, so an inherited one would make
-    // the fork and its source visually identical — the ambiguity a per-harness
-    // block exists to remove. A fork carries a label only when it is given one;
-    // otherwise `profileLabel` falls back to the fork's own name.
-    if (opts.label)
-        forked.label = opts.label;
-    else
-        delete forked.label;
     // A fork that repoints the model or endpoint is no longer that preset — keep
     // the preset link only while the fork still matches what the preset defines.
     if (opts.model || opts.baseUrl)
@@ -360,6 +385,51 @@ export function forkProfile(source, name, opts = {}) {
     }
     return forked;
 }
+/**
+ * Edit an existing profile in-place, applying overrides without changing its
+ * name or lineage. Reuses {@link forkProfile}'s validation and override logic
+ * (model swap, base-URL validation, auth repoint), then restores the original
+ * `forkedFrom` so an edit never self-references the profile.
+ *
+ * Note: this returns the updated `Profile` object but does NOT write it to
+ * disk — callers should follow up with `writeProfile(result)` if persistence
+ * is needed.
+ */
+export function editProfile(source, opts = {}) {
+    const edited = forkProfile(source, source.name, opts);
+    // forkProfile sets forkedFrom = source.name; for an in-place edit that would
+    // be a self-reference. Restore the original lineage instead.
+    edited.forkedFrom = source.forkedFrom;
+    return edited;
+}
+/**
+ * Rename a profile on disk, then rewrite `forkedFrom` in every other profile
+ * that pointed at the old name so lineage display never goes stale.
+ *
+ * Throws if `oldName` does not exist or `newName` already exists. There is no
+ * `--force` / overwrite path — a collision is a hard error directing the user
+ * to remove the target first.
+ */
+export function renameProfile(oldName, newName) {
+    validateProfileName(newName);
+    if (!profileExists(oldName)) {
+        throw new Error(`Profile '${oldName}' not found.`);
+    }
+    if (profileExists(newName)) {
+        throw new Error(`Profile '${newName}' already exists; remove it first.`);
+    }
+    const profile = readProfile(oldName);
+    profile.name = newName;
+    writeProfile(profile);
+    deleteProfile(oldName);
+    // Rewrite forkedFrom in every other profile that referenced the old name.
+    for (const other of listProfiles()) {
+        if (other.name !== newName && other.forkedFrom === oldName) {
+            other.forkedFrom = newName;
+            writeProfile(other);
+        }
+    }
+}
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

package/dist/lib/rotate.d.ts

@@ -8,6 +8,7 @@ import type { AgentId, RunStrategy } from './types.js';
 import type { FallbackEntry } from './exec.js';
 import { type AccountInfo, type CredentialPresence } from './agents.js';
 import { type UsageSnapshot } from './usage.js';
+import { type AuthVerdict } from './auth-health.js';
 export interface RotateCandidate {
     agent: AgentId;
     version: string;
@@ -35,6 +36,18 @@ export interface RotateCandidate {
     usageMinutesToLimit: number | null;
     plan: string | null;
     signedIn: boolean;
+    /**
+     * Live auth-health verdict for this (agent, version) from the daemon's probe
+     * cache (`auth-health.ts`), or null when no probe row exists (cold cache, or a
+     * harness with no live-probe endpoint). `signedIn` only means "a credential
+     * file is present and its email decodes" — it cannot tell a good token from a
+     * revoked-but-unexpired one, so a server-rejected account reads
+     * `signedIn: true` but `authVerdict: 'revoked'`. Eligibility excludes a
+     * revoked account so rotation never launches into a doomed auth (see
+     * {@link readinessFromCandidate}). Fail-open: any non-revoked or null verdict
+     * does not gate — a stale/absent probe never blocks a launch.
+     */
+    authVerdict: AuthVerdict | null;
     lastActive: Date | null;
 }
 export interface RotateResult {
@@ -108,15 +121,17 @@ export declare const USAGE_DECISION_MAX_AGE_MS: number;
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
- * why. `signed_out` covers a missing usable credential; `rate_limited` and
- * `out_of_credits` name the throttle. Used to pre-warn on a version-pinned
- * teammate whose account rotation won't route around (a pin IS the target).
+ * why. `signed_out` covers a missing usable credential; `revoked` is a token the
+ * server has actually rejected (401/403, from the live auth-health probe);
+ * `rate_limited` and `out_of_credits` name the throttle. Used to pre-warn on a
+ * version-pinned teammate whose account rotation won't route around (a pin IS
+ * the target).
  */
 export type AccountReadiness = {
     ready: true;
 } | {
     ready: false;
-    reason: 'rate_limited' | 'out_of_credits' | 'signed_out';
+    reason: 'rate_limited' | 'out_of_credits' | 'signed_out' | 'revoked';
     email: string | null;
 };
 /**

package/dist/lib/rotate.js

@@ -13,6 +13,8 @@ import { getProjectRunConfigs } from './run-config.js';
 import { emit } from './events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
 import { readAccountHeadroom } from './fleet-cache.js';
+import { machineId } from './machine-id.js';
+import { readAuthHealthCache, authCacheKey, isDeadVerdict } from './auth-health.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -65,8 +67,14 @@ export function setGlobalRunStrategy(agent, strategy) {
     meta.run[agent] = { ...(meta.run[agent] ?? {}), strategy };
     writeMeta(meta);
 }
+/**
+ * Whether an account may be rotated INTO right now. Defined in terms of
+ * {@link readinessFromCandidate} so the router's pick gate and the pre-flight
+ * warning can never disagree: an account is eligible iff its readiness is
+ * `ready` — signed in, not server-revoked, and not out of usage.
+ */
 function isRotationEligible(candidate) {
-    return candidate.signedIn && hasUsageAvailable(candidate);
+    return readinessFromCandidate(candidate).ready;
 }
 /**
  * Whether a version home can actually authenticate a launch.
@@ -146,6 +154,13 @@ export function readinessFromCandidate(candidate) {
     if (!candidate.signedIn) {
         return { ready: false, reason: 'signed_out', email: candidate.email };
     }
+    // A token the daemon's live probe saw rejected (401/403 -> `revoked`) will fail
+    // auth at spawn no matter how much usage headroom it has. Exclude it BEFORE the
+    // usage gate so rotation never routes into a doomed login. Fail-open: any other
+    // (or null) verdict does not gate — see `RotateCandidate.authVerdict`.
+    if (candidate.authVerdict !== null && isDeadVerdict(candidate.authVerdict)) {
+        return { ready: false, reason: 'revoked', email: candidate.email };
+    }
     if (hasUsageAvailable(candidate)) {
         return { ready: true };
     }
@@ -495,6 +510,12 @@ export function formatNoHealthyHarnessError(summaries, nowMs = Date.now()) {
 }
 export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
+    // Read the local auth-health probe cache once (cache-only, no network — the
+    // daemon is the sole writer). A `revoked` verdict for a (host, agent, version)
+    // excludes that account from the pick; a missing row is fail-open. Keyed by the
+    // LOCAL host — routing decides which local version to launch.
+    const authCache = readAuthHealthCache();
+    const localHost = machineId();
     const rows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
         const info = await getAccountInfo(agent, home);
@@ -510,6 +531,7 @@ export async function collectRunCandidates(agent) {
         // lives — see isLaunchableSignedIn. Do not reuse the active-home fallback
         // identity for routing, or empty version homes look healthy and die at spawn.
         const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
+        const authVerdict = authCache[authCacheKey(localHost, agent, version)]?.verdict ?? null;
         return {
             agent,
             version,
@@ -521,6 +543,7 @@ export async function collectRunCandidates(agent) {
             usageStatus: launchable ? info.usageStatus : null,
             plan: launchable ? info.plan : null,
             signedIn: launchable,
+            authVerdict,
             lastActive: info.lastActive,
         };
     }));

package/dist/lib/routines.d.ts

@@ -239,6 +239,8 @@ export interface RunMeta {
     pid: number | null;
     /** Process birth time (epoch ms) recorded at spawn for pid-reuse detection. */
     spawnedAt?: number;
+    /** Configured execution deadline persisted for daemon-restart recovery. */
+    timeoutMs?: number;
     /**
      * `missed` is not an execution outcome — it is the record that a scheduled
      * fire never happened (the daemon was down, asleep, or wedged when it came

package/dist/lib/runner.d.ts

@@ -23,6 +23,9 @@ export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+export declare class RoutineAlreadyRunningError extends Error {
+    constructor(jobName: string, runId: string);
+}
 /** Agents the daemon can actually run, derived from the command table above
  * so the `--agent` help and any validation can never drift from it. */
 export declare const ROUTINE_AGENT_IDS: readonly string[];

package/dist/lib/runner.js

@@ -17,7 +17,7 @@ import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, } from './routines.js';
+import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, } from './routines.js';
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
@@ -26,7 +26,9 @@ import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, dete
 import { resolveActor } from './actor.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
 import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
-import { backgroundSpawnOptions } from './platform/process.js';
+import { backgroundSpawnOptions, killTree } from './platform/process.js';
+import lockfile from 'proper-lockfile';
+import { ensureLockTarget } from './fs-atomic.js';
 import { walkForFiles } from './fs-walk.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from './rotate.js';
@@ -34,6 +36,66 @@ import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
 import { isSelfUpdatingAgent } from './agents.js';
 import { expandLocalHome, getProjectRoot } from './project-root.js';
+export class RoutineAlreadyRunningError extends Error {
+    constructor(jobName, runId) {
+        super(`Routine '${jobName}' already has a running execution (${runId})`);
+        this.name = 'RoutineAlreadyRunningError';
+    }
+}
+const ROUTINE_LAUNCH_LOCK_STALE_MS = 30_000;
+const ROUTINE_LAUNCH_LOCK_WAIT_MS = 10_000;
+function activeRoutineRun(config) {
+    const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
+    const now = Date.now();
+    const runs = listRuns(config.name);
+    for (let i = runs.length - 1; i >= 0; i--) {
+        const run = runs[i];
+        if (run.status !== 'running')
+            continue;
+        if (run.pid && isPidOurs(run.pid, run.spawnedAt))
+            return run;
+        if (!run.pid) {
+            const startedAt = Date.parse(run.startedAt);
+            if (Number.isFinite(startedAt) && now - startedAt < (run.timeoutMs ?? timeoutMs))
+                return run;
+        }
+    }
+    return null;
+}
+async function withRoutineLaunchClaim(config, launch) {
+    const target = path.join(getJobRunsDir(config.name), '.launch-claim');
+    ensureLockTarget(target, '', 0o700);
+    const release = await lockfile.lock(target, {
+        stale: ROUTINE_LAUNCH_LOCK_STALE_MS,
+        retries: {
+            retries: Math.ceil(ROUTINE_LAUNCH_LOCK_WAIT_MS / 100),
+            factor: 1,
+            minTimeout: 100,
+            maxTimeout: 100,
+        },
+    });
+    try {
+        const active = activeRoutineRun(config);
+        if (active)
+            throw new RoutineAlreadyRunningError(config.name, active.runId);
+        return await launch();
+    }
+    finally {
+        await release();
+    }
+}
+function terminateRoutineTree(pid) {
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        killTree(pid);
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* already exited */ }
+}
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
@@ -1086,6 +1148,9 @@ export async function executeJobDetached(config, hooks) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
+    return withRoutineLaunchClaim(config, () => executeJobDetachedClaimed(config, hooks));
+}
+async function executeJobDetachedClaimed(config, hooks) {
     // Placement (hostStrategy / bare host:) — dispatch off-box and return; the
     // monitor finalizes host: runs, cloud runs stay terminal when dispatch ends.
     // Either way the in-process onFinish hook does not fire for off-box routines
@@ -1161,6 +1226,7 @@ export async function executeJobDetached(config, hooks) {
         ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
         spawnedAt: Date.now(),
+        timeoutMs: parseTimeout(config.timeout) || 10 * 60 * 1000,
         status: 'running',
         startedAt: new Date().toISOString(),
         completedAt: null,
@@ -1195,10 +1261,13 @@ export async function executeJobDetached(config, hooks) {
         env: spawnEnv,
     });
     let settled = false;
+    let timeoutTimer;
     const settle = (status, exitCode, errorMessage) => {
         if (settled)
             return;
         settled = true;
+        if (timeoutTimer)
+            clearTimeout(timeoutTimer);
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
         archiveRoutineTranscripts(meta, runDir, overlayHome);
@@ -1212,6 +1281,10 @@ export async function executeJobDetached(config, hooks) {
         // can read report.md (RUSH-2030). Best-effort; never breaks finalization.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
+    timeoutTimer = setTimeout(() => {
+        terminateRoutineTree(child.pid ?? null);
+        settle('timeout', null, 'exceeded configured timeout');
+    }, meta.timeoutMs);
     child.on('exit', (code) => {
         let logText = '';
         try {
@@ -1249,7 +1322,7 @@ export async function executeJobDetached(config, hooks) {
     catch { /* fd already closed */ }
     meta.pid = child.pid || null;
     writeRunMeta(meta);
-    return meta;
+    return { ...meta };
 }
 /**
  * Detached (fire-and-forget) execution for a command-mode routine. Mirrors the
@@ -1288,6 +1361,7 @@ function executeCommandJobDetached(config, hooks) {
         command: config.command,
         pid: null,
         spawnedAt: Date.now(),
+        timeoutMs: parseTimeout(config.timeout) || 10 * 60 * 1000,
         status: 'running',
         startedAt: new Date().toISOString(),
         completedAt: null,
@@ -1302,17 +1376,24 @@ function executeCommandJobDetached(config, hooks) {
     // fire-and-forget call, so the exit event fires here. (monitorRunningJobs no
     // longer force-fails command jobs; it reads exit-code only on the restart edge.)
     let settled = false;
+    let timeoutTimer;
     const settle = (status, exitCode, errorMessage) => {
         if (settled)
             return;
         settled = true;
+        if (timeoutTimer)
+            clearTimeout(timeoutTimer);
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
-        timer.end({ status, exitCode, runId, ...(errorMessage ? { error: errorMessage } : {}) });
+        timer.end({ status, exitCode: exitCode ?? undefined, runId, ...(errorMessage ? { error: errorMessage } : {}) });
         // Finish notification (RUSH-2030). For command routines the threshold only
         // surfaces failures, decided in routine-notify.ts. Best-effort.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
+    timeoutTimer = setTimeout(() => {
+        terminateRoutineTree(child.pid ?? null);
+        settle('timeout', null, 'exceeded configured timeout');
+    }, meta.timeoutMs);
     child.on('exit', (code) => settle(code === 0 ? 'completed' : 'failed', code ?? 1));
     child.on('error', (err) => {
         settle('failed', 1, err.message);
@@ -1325,7 +1406,7 @@ function executeCommandJobDetached(config, hooks) {
     catch { /* fd already closed */ }
     meta.pid = child.pid || null;
     writeRunMeta(meta);
-    return meta;
+    return { ...meta };
 }
 function extractAndSaveReport(stdoutPath, agentType, runDir) {
     try {
@@ -1508,8 +1589,10 @@ export function monitorRunningJobs() {
                 // parse or extract. Reap them on pid liveness alone.
                 const isCommandRun = Boolean(meta.command) || !meta.agent;
                 const wallClockMs = Date.now() - Date.parse(meta.startedAt);
-                if (Number.isFinite(wallClockMs) && wallClockMs > MAX_WALL_CLOCK_MS) {
-                    finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded max wall clock' });
+                const timeoutMs = meta.timeoutMs ?? MAX_WALL_CLOCK_MS;
+                if (Number.isFinite(wallClockMs) && wallClockMs > timeoutMs) {
+                    terminateRoutineTree(meta.pid);
+                    finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded configured timeout' });
                     writeRunMeta(meta);
                     if (!isCommandRun) {
                         extractAndSaveReport(stdoutPath, meta.agent, runDirPath);

package/dist/lib/snapshot.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `agents snapshot` — one-process fleet consumer snapshot.
+ *
+ * Consumers (Factory watchdog, menubar, fleet scripts) used to fork:
+ *   agents view <agent> --json  × N harnesses
+ *   agents sessions --active --json
+ *   agents feed --json          (sometimes)
+ *
+ * That is N+2 process starts per poll tick. This module gathers the same
+ * shapes in one invocation so poll count drops to 1 without redefining
+ * `agents status` (which stays the UnifiedSyncStatus sync contract).
+ *
+ * Stores are not merged — inventory still comes from view, active rows from
+ * sessions, blocks from feed. Only the reader is consolidated.
+ */
+import { type OpenBlock } from './feed.js';
+import { type FleetAgentCounts } from './fleet-status.js';
+import type { AgentId } from './types.js';
+import type { UnifiedSyncStatus } from './sync-status.js';
+import type { ViewJsonAgent } from '../commands/view.js';
+/** One open-block row in the optional feed summary (no full question bodies). */
+export interface SnapshotFeedBlock {
+    blockId: string;
+    sessionId: string;
+    host: string;
+    runtime: string;
+    kind?: OpenBlock['kind'];
+    ticket?: string;
+    pr?: string;
+    questionCount: number;
+    ts: string;
+}
+/** Compact feed slice for needs-you polls. */
+export interface SnapshotFeedSummary {
+    openBlocks: number;
+    blocks: SnapshotFeedBlock[];
+}
+/** Active-session row as emitted by `sessions --active --json`. */
+export type SnapshotSessionRow = {
+    ticketId: string | null;
+    project: string | null;
+    prLink: string | null;
+    viewingIn: string | null;
+    [key: string]: unknown;
+};
+/**
+ * Stable machine-readable contract for `agents snapshot --json`.
+ * Bump `version` only on breaking shape changes.
+ */
+export interface FleetSnapshot {
+    version: 1;
+    /** Host that produced this snapshot (machineId). */
+    host: string;
+    /** ISO-8601 capture time. */
+    capturedAt: string;
+    /** Installed agent inventory — same shape as `agents view --json`. */
+    inventory: ViewJsonAgent[];
+    /** Live sessions — same row shape as `agents sessions --active --json`. */
+    sessions: SnapshotSessionRow[];
+    /** How many remote devices contributed sessions (0 when --local). */
+    remoteDeviceCount: number;
+    /** Running/live tallies derived from `sessions` (same as fleet-status). */
+    agents: FleetAgentCounts;
+    /** Present when --with-feed. */
+    feed?: SnapshotFeedSummary;
+    /** Present when --with-sync (UnifiedSyncStatus; does not replace `agents status`). */
+    sync?: UnifiedSyncStatus;
+}
+export interface ComputeSnapshotOptions {
+    /** Restrict inventory to one agent id. */
+    agent?: AgentId;
+    /** Local sessions only — no cross-machine SSH fan-out. Default true for cheap polls. */
+    local?: boolean;
+    /** Explicit host filter for the sessions gather (same semantics as sessions --active). */
+    hosts?: string[];
+    /** Include open feed-block summary. */
+    withFeed?: boolean;
+    /** Include UnifiedSyncStatus (opt-in; can be slower). */
+    withSync?: boolean;
+    /** Cap feed.blocks length (default 50). */
+    feedLimit?: number;
+}
+/** Summarize open blocks for the snapshot feed slice. Pure / unit-testable. */
+export declare function summarizeFeedBlocks(blocks: ReadonlyArray<OpenBlock>, limit?: number): SnapshotFeedSummary;
+/**
+ * Assemble a snapshot payload from already-gathered pieces. Pure so tests do
+ * not need live process scans or network.
+ */
+export declare function assembleSnapshot(parts: {
+    host: string;
+    capturedAt: string;
+    inventory: ViewJsonAgent[];
+    sessions: SnapshotSessionRow[];
+    remoteDeviceCount: number;
+    feed?: SnapshotFeedSummary;
+    sync?: UnifiedSyncStatus;
+}): FleetSnapshot;
+/**
+ * Gather inventory + active sessions (+ optional feed/sync) in one process.
+ * Default `local: true` keeps the common poll path free of SSH fan-out; pass
+ * `local: false` (or hosts) to match full `sessions --active` fleet scope.
+ */
+export declare function computeSnapshot(opts?: ComputeSnapshotOptions): Promise<FleetSnapshot>;

package/dist/lib/snapshot.js

@@ -0,0 +1,99 @@
+/**
+ * `agents snapshot` — one-process fleet consumer snapshot.
+ *
+ * Consumers (Factory watchdog, menubar, fleet scripts) used to fork:
+ *   agents view <agent> --json  × N harnesses
+ *   agents sessions --active --json
+ *   agents feed --json          (sometimes)
+ *
+ * That is N+2 process starts per poll tick. This module gathers the same
+ * shapes in one invocation so poll count drops to 1 without redefining
+ * `agents status` (which stays the UnifiedSyncStatus sync contract).
+ *
+ * Stores are not merged — inventory still comes from view, active rows from
+ * sessions, blocks from feed. Only the reader is consolidated.
+ */
+import { machineId } from './machine-id.js';
+import { listBlocks } from './feed.js';
+import { computeAgentCounts } from './fleet-status.js';
+/** Summarize open blocks for the snapshot feed slice. Pure / unit-testable. */
+export function summarizeFeedBlocks(blocks, limit = 50) {
+    const sorted = [...blocks].sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
+    const slice = sorted.slice(0, Math.max(0, limit));
+    return {
+        openBlocks: blocks.length,
+        blocks: slice.map((b) => ({
+            blockId: b.blockId,
+            sessionId: b.sessionId,
+            host: b.host,
+            runtime: b.runtime,
+            kind: b.kind,
+            ticket: b.ticket,
+            pr: b.pr,
+            questionCount: b.questions?.length ?? 0,
+            ts: b.ts,
+        })),
+    };
+}
+/**
+ * Assemble a snapshot payload from already-gathered pieces. Pure so tests do
+ * not need live process scans or network.
+ */
+export function assembleSnapshot(parts) {
+    return {
+        version: 1,
+        host: parts.host,
+        capturedAt: parts.capturedAt,
+        inventory: parts.inventory,
+        sessions: parts.sessions,
+        remoteDeviceCount: parts.remoteDeviceCount,
+        agents: computeAgentCounts(parts.sessions.map((s) => ({
+            status: typeof s.status === 'string' ? s.status : undefined,
+            context: typeof s.context === 'string' ? s.context : undefined,
+            kind: typeof s.kind === 'string' ? s.kind : undefined,
+        }))),
+        ...(parts.feed ? { feed: parts.feed } : {}),
+        ...(parts.sync ? { sync: parts.sync } : {}),
+    };
+}
+/**
+ * Gather inventory + active sessions (+ optional feed/sync) in one process.
+ * Default `local: true` keeps the common poll path free of SSH fan-out; pass
+ * `local: false` (or hosts) to match full `sessions --active` fleet scope.
+ */
+export async function computeSnapshot(opts = {}) {
+    // Default local-only sessions (cheap poll). Explicit hosts → scoped fan-out.
+    // local: false (from --all-hosts) → full sessions --active fan-out.
+    const localOnly = opts.hosts?.length ? false : opts.local !== false;
+    const [{ collectAgentsJson }, sessionsMod] = await Promise.all([
+        import('../commands/view.js'),
+        import('../commands/sessions.js'),
+    ]);
+    const inventoryP = collectAgentsJson(opts.agent);
+    const sessionsP = sessionsMod.gatherActiveSessions({
+        local: localOnly,
+        hosts: opts.hosts,
+    });
+    const feedP = opts.withFeed
+        ? Promise.resolve(summarizeFeedBlocks(listBlocks(), opts.feedLimit ?? 50))
+        : Promise.resolve(undefined);
+    const syncP = opts.withSync
+        ? import('./sync-status.js').then((m) => m.computeSyncStatus())
+        : Promise.resolve(undefined);
+    const [inventory, gathered, feed, sync] = await Promise.all([
+        inventoryP,
+        sessionsP,
+        feedP,
+        syncP,
+    ]);
+    const sessions = sessionsMod.serializeActiveSessionsForJson(gathered.sessions);
+    return assembleSnapshot({
+        host: machineId(),
+        capturedAt: new Date().toISOString(),
+        inventory,
+        sessions,
+        remoteDeviceCount: gathered.remoteDeviceCount,
+        feed,
+        sync,
+    });
+}

package/dist/lib/startup/command-registry.d.ts

@@ -56,6 +56,7 @@ export declare const loadRestore: ModuleLoader;
 export declare const loadDoctor: ModuleLoader;
 export declare const loadApply: ModuleLoader;
 export declare const loadStatus: ModuleLoader;
+export declare const loadSnapshot: ModuleLoader;
 export declare const loadProfiles: ModuleLoader;
 export declare const loadHarness: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;