@phnx-labs/agents-cli 1.22.7 → 1.22.9

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/session/parse.d.ts

@@ -31,7 +31,11 @@ export declare function safeReadSessionFile(filePath: string, maxBytes?: number)
 /**
  * Auto-detect agent type from file path and parse the session.
  */
-export declare function parseSession(filePath: string, agent?: SessionAgentId): SessionEvent[];
+export interface ParseSessionOptions {
+    /** Keep normalized tool results compact by default; renderers can request full output. */
+    maxToolOutputChars?: number;
+}
+export declare function parseSession(filePath: string, agent?: SessionAgentId, opts?: ParseSessionOptions): SessionEvent[];
 /** Infer the agent type from a session file path using known directory conventions. */
 export declare function detectAgent(filePath: string): SessionAgentId | null;
 /**

package/dist/lib/session/parse.js

@@ -112,10 +112,12 @@ export function safeReadSessionFile(filePath, maxBytes = SESSION_FILE_MAX_BYTES)
     }
     return fs.readFileSync(filePath, 'utf-8');
 }
-/**
- * Auto-detect agent type from file path and parse the session.
- */
-export function parseSession(filePath, agent) {
+function truncateNormalizedToolOutput(output, maxChars) {
+    if (!Number.isFinite(maxChars) || output.length <= maxChars)
+        return output;
+    return `${output.slice(0, maxChars)}\n\n[Output truncated: ${output.length - maxChars} characters omitted.]`;
+}
+export function parseSession(filePath, agent, opts = {}) {
     const detected = agent || detectAgent(filePath);
     if (!detected) {
         throw new Error(`Cannot detect agent type from path: ${filePath}`);
@@ -166,7 +168,11 @@ export function parseSession(filePath, agent) {
     // from `!`-prefix runs, `<system-reminder>`, etc.) as `_synthetic` so turn
     // slicing and `--include user` count only genuine user intent — one place,
     // every harness, instead of per-consumer regex.
+    const maxToolOutputChars = opts.maxToolOutputChars ?? 500;
     for (const e of events) {
+        if (e.type === 'tool_result' && e.output) {
+            e.output = truncateNormalizedToolOutput(e.output, maxToolOutputChars);
+        }
         sanitizeEvent(e);
         if (e.type === 'message' && e.role === 'user' && isSyntheticUserMessage(e.content)) {
             e._synthetic = true;
@@ -496,7 +502,11 @@ export function parseClaudeContent(content) {
                                 exitCode: structured.exitCode,
                                 statusCode: structured.statusCode,
                                 errorCode: structured.errorCode,
-                                output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                                // Not truncated here: `parseSession` caps every event's `output`
+                                // centrally via `maxToolOutputChars` (default 500, the same
+                                // bound this site used to hardcode), so the render path can ask
+                                // for the full text with `Infinity`.
+                                output,
                             });
                         }
                         if (toolId)
@@ -686,7 +696,7 @@ export function parseCodexContent(content) {
                     exitCode: result.exitCode,
                     statusCode: result.statusCode,
                     errorCode: result.errorCode,
-                    output: result.text.length > 500 ? result.text.slice(0, 497) + '...' : result.text,
+                    output: result.text,
                 });
                 if (callId)
                     callMap.delete(callId);
@@ -741,7 +751,7 @@ export function parseCodexContent(content) {
                     exitCode: result.exitCode,
                     statusCode: result.statusCode,
                     errorCode: result.errorCode,
-                    output: result.text.length > 500 ? result.text.slice(0, 497) + '...' : result.text,
+                    output: result.text,
                 });
                 if (callId)
                     callMap.delete(callId);
@@ -865,7 +875,7 @@ export function parseGemini(filePath) {
                             tool: toolName,
                             callId: typeof tc.id === 'string' ? tc.id : undefined,
                             success: tc.status === 'success',
-                            output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                            output,
                         });
                     }
                 }
@@ -1242,7 +1252,7 @@ export function parseGrok(filePath) {
                 callId,
                 success: structuredError ? false : structuredSuccess ? true : undefined,
                 outcome: structuredError ? 'error' : structuredSuccess ? 'ok' : 'unknown',
-                output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                output: output,
             });
             if (callId)
                 toolCallMap.delete(callId);
@@ -1360,7 +1370,7 @@ export function parseOpenCode(filePath) {
                             tool: toolName,
                             callId,
                             success: state.status === 'completed',
-                            output: outputStr.length > 500 ? outputStr.slice(0, 497) + '...' : outputStr,
+                            output: outputStr,
                         });
                     }
                     break;
@@ -1470,7 +1480,7 @@ export function parseRush(filePath) {
                 tool: info?.tool ?? (typeof raw.name === 'string' ? raw.name : 'unknown'),
                 callId,
                 success,
-                output: outputStr.length > 500 ? outputStr.slice(0, 497) + '...' : outputStr,
+                output: outputStr,
             });
             if (callId)
                 toolCallMap.delete(callId);
@@ -1680,7 +1690,7 @@ export function parseKimi(filePath) {
                     callId,
                     success: structuredError ? false : structuredSuccess ? true : undefined,
                     outcome: structuredError ? 'error' : structuredSuccess ? 'ok' : 'unknown',
-                    output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                    output: output,
                 });
                 if (callId) {
                     toolCallMap.delete(callId);
@@ -1825,7 +1835,7 @@ function parseAnthropicMessageJsonl(filePath, agent) {
                 else {
                     events.push({
                         type: 'tool_result', agent, timestamp, tool: toolInfo?.tool, callId: toolId, success: true,
-                        output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                        output: output,
                     });
                 }
                 if (toolId)

package/dist/lib/session/prompt.js

@@ -46,6 +46,11 @@ const SYNTHETIC_USER_MESSAGE_PATTERNS = [
     /^\s*<\/?user-prompt-submit-hook>/i,
     /^\s*<\/?persisted-output>/i,
     /^\s*<permissions instructions>/i,
+    /^\s*<(?:apps|plugins|skills)_instructions>/i,
+    /^\s*<(?:multi_agent_mode|environment_context)>/i,
+    /^\s*## (?:In-flight in this repo|Host & Fleet)/i,
+    /^\s*Your current session id is\b/i,
+    /^\s*Linear context skipped:/i,
     /^\s*<collaboration_mode>/i,
     /^\s*Caveat: The messages below were generated by the user while running/i,
     /^\s*\[Request interrupted/i,

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

@@ -108,6 +108,9 @@ export declare function filterEvents(events: SessionEvent[], opts: FilterOptions
  */
 export interface RenderConversationMarkdownOptions {
     redact?: boolean;
+    knownSecrets?: readonly string[];
+    reasoning?: 'omit' | 'fold' | 'include';
+    maxToolOutputChars?: number;
 }
 export declare function renderConversationMarkdown(events: SessionEvent[], opts?: RenderConversationMarkdownOptions): string;
 /**

package/dist/lib/session/render.js

@@ -923,10 +923,23 @@ export function filterEvents(events, opts) {
     const sliced = applyTurnSlice(events, opts);
     return applyRoleFilter(sliced, opts);
 }
+function markdownFence(content, language = '') {
+    const fence = content.includes('```') ? '````' : '```';
+    return `${fence}${language}\n${content}\n${fence}`;
+}
+function truncateToolOutput(content, maxChars) {
+    if (content.length <= maxChars)
+        return content;
+    return `${content.slice(0, maxChars)}\n\n[Output truncated: ${content.length - maxChars} characters omitted.]`;
+}
 export function renderConversationMarkdown(events, opts = {}) {
     const parts = [];
     const shouldRedact = opts.redact !== false;
-    const sanitize = (text) => shouldRedact ? redactSecrets(text) : text;
+    const sanitize = (text) => shouldRedact ? redactSecrets(text, opts.knownSecrets) : text;
+    // Preserve the long-standing `sessions <id> --markdown` full-fidelity default.
+    // The shareable `sessions render` surface passes `omit` explicitly.
+    const reasoning = opts.reasoning ?? 'include';
+    const maxToolOutputChars = opts.maxToolOutputChars ?? 4000;
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user') {
@@ -937,27 +950,37 @@ export function renderConversationMarkdown(events, opts = {}) {
             }
         }
         else if (event.type === 'thinking') {
-            if (event.content)
-                parts.push(`### Thinking\n\n${sanitize(event.content)}`);
+            if (event.content && reasoning === 'include') {
+                parts.push(`### Reasoning\n\n${sanitize(event.content)}`);
+            }
+            else if (event.content && reasoning === 'fold') {
+                parts.push(`<details>\n<summary>Reasoning</summary>\n\n${sanitize(event.content)}\n\n</details>`);
+            }
         }
         else if (event.type === 'tool_use') {
             const tool = event.tool || 'unknown';
             if (event.command) {
-                parts.push(`### Tool: ${tool}\n\n\`\`\`bash\n${sanitize(event.command)}\n\`\`\``);
+                const args = event.args && Object.keys(event.args).length > 0
+                    ? `\n\nArguments:\n\n${markdownFence(sanitize(JSON.stringify(event.args, null, 2)), 'json')}`
+                    : '';
+                parts.push(`### Tool: ${tool}\n\n${markdownFence(sanitize(event.command), 'bash')}${args}`);
+            }
+            else if (event.args && Object.keys(event.args).length > 0) {
+                parts.push(`### Tool: ${tool}\n\nArguments:\n\n${markdownFence(sanitize(JSON.stringify(event.args, null, 2)), 'json')}`);
             }
             else if (event.path) {
-                parts.push(`### Tool: ${tool}\n\n\`${shortenPathTrace(event.path)}\``);
+                parts.push(`### Tool: ${tool}\n\n\`${sanitize(shortenPathTrace(event.path))}\``);
             }
             else {
                 const summary = summarizeToolUse(tool, event.args);
-                parts.push(`### Tool: ${tool}\n\n${summary}`);
+                parts.push(`### Tool: ${tool}\n\n${sanitize(summary)}`);
             }
         }
         else if (event.type === 'tool_result') {
-            if (event.content) {
-                const truncated = event.content.length > 2000 ? event.content.slice(0, 2000) + '\n…' : event.content;
-                const body = sanitize(truncated);
-                parts.push(`### Tool Result\n\n\`\`\`\n${body}\n\`\`\``);
+            const output = event.content || event.output;
+            if (output) {
+                const body = sanitize(truncateToolOutput(output, maxToolOutputChars));
+                parts.push(`### Tool Result${event.tool ? `: ${event.tool}` : ''}\n\n${markdownFence(body)}`);
             }
         }
         else if (event.type === 'error') {

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>;