@phnx-labs/agents-cli 1.20.17 → 1.20.19

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/teams/agents.d.ts

@@ -17,6 +17,14 @@ export declare enum AgentStatus {
 export type TaskType = 'plan' | 'implement' | 'test' | 'review' | 'bugfix' | 'docs';
 export declare const VALID_TASK_TYPES: readonly TaskType[];
 export type { AgentType } from './parsers.js';
+/**
+ * Wrap a teammate argv in a POSIX shell command that runs it and then records
+ * the real exit code to `exitCodePath`. `echo $?` captures the status of the
+ * preceding command, so the sentinel reflects the underlying CLI's exit code,
+ * not the shell's. Single source of truth shared by launchProcess() and its
+ * test. See reapProcess() for how the sentinel is consumed.
+ */
+export declare function buildSentinelCommand(cmd: string[], exitCodePath: string): string;
 /**
  * Capture a stable identifier for a process at the moment it was started.
  * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
@@ -118,6 +126,13 @@ export declare class AgentProcess {
     }>;
     getStdoutPath(): Promise<string>;
     getMetaPath(): Promise<string>;
+    /**
+     * Path to the exit-code sentinel. The launcher wraps the teammate command in
+     * a shell that writes the underlying CLI's `$?` here once it exits. Detached
+     * teammates can't be wait()ed on by the parent, so this file is the only
+     * durable record of the real exit status — see reapProcess().
+     */
+    getExitCodePath(): Promise<string>;
     toDict(): any;
     duration(): string | null;
     get events(): any[];
@@ -131,6 +146,23 @@ export declare class AgentProcess {
     static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
     isProcessAlive(): boolean;
     updateStatusFromProcess(): Promise<void>;
+    /**
+     * Recover the teammate's exit status after its process is gone.
+     *
+     * The teammate is spawned detached + unref()'d (see launchProcess), so the
+     * parent never gets the child's exit code from the OS. Instead the launcher
+     * wraps the command in a shell that records `$?` to the exit-code sentinel.
+     * This reads that file:
+     *   - still alive            -> null (no verdict yet)
+     *   - sentinel present       -> the real exit code (0 = success)
+     *   - sentinel absent        -> 1 (the shell was killed before it could write
+     *                                  it, e.g. SIGKILL on timeout/stop — a real
+     *                                  failure)
+     *
+     * Returning a real code (not a hardcoded 1) is what lets agents whose stream
+     * never emits a parsed terminal event — kimi, antigravity, droid — be marked
+     * completed on success instead of falsely failed.
+     */
     private reapProcess;
 }
 /**

package/dist/lib/teams/agents.js

@@ -135,6 +135,25 @@ function hasTransitiveDep(byName, startName, targetName, seen = new Set()) {
     }
     return false;
 }
+/**
+ * Single-quote a string for safe interpolation into a POSIX `sh -c` command.
+ * Wraps in single quotes and escapes embedded single quotes via the standard
+ * `'\''` close-escape-reopen idiom, so arbitrary prompts/paths can't break out
+ * of quoting or inject shell syntax.
+ */
+function shSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Wrap a teammate argv in a POSIX shell command that runs it and then records
+ * the real exit code to `exitCodePath`. `echo $?` captures the status of the
+ * preceding command, so the sentinel reflects the underlying CLI's exit code,
+ * not the shell's. Single source of truth shared by launchProcess() and its
+ * test. See reapProcess() for how the sentinel is consumed.
+ */
+export function buildSentinelCommand(cmd, exitCodePath) {
+    return `${cmd.map(shSingleQuote).join(' ')}; echo $? > ${shSingleQuote(exitCodePath)}`;
+}
 /**
  * Capture a stable identifier for a process at the moment it was started.
  * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
@@ -456,6 +475,15 @@ export class AgentProcess {
     async getMetaPath() {
         return path.join(await this.getAgentDir(), 'meta.json');
     }
+    /**
+     * Path to the exit-code sentinel. The launcher wraps the teammate command in
+     * a shell that writes the underlying CLI's `$?` here once it exits. Detached
+     * teammates can't be wait()ed on by the parent, so this file is the only
+     * durable record of the real exit status — see reapProcess().
+     */
+    async getExitCodePath() {
+        return path.join(await this.getAgentDir(), 'exit_code');
+    }
     toDict() {
         return {
             agent_id: this.agentId,
@@ -748,14 +776,37 @@ export class AgentProcess {
         }
         await this.saveMeta();
     }
+    /**
+     * Recover the teammate's exit status after its process is gone.
+     *
+     * The teammate is spawned detached + unref()'d (see launchProcess), so the
+     * parent never gets the child's exit code from the OS. Instead the launcher
+     * wraps the command in a shell that records `$?` to the exit-code sentinel.
+     * This reads that file:
+     *   - still alive            -> null (no verdict yet)
+     *   - sentinel present       -> the real exit code (0 = success)
+     *   - sentinel absent        -> 1 (the shell was killed before it could write
+     *                                  it, e.g. SIGKILL on timeout/stop — a real
+     *                                  failure)
+     *
+     * Returning a real code (not a hardcoded 1) is what lets agents whose stream
+     * never emits a parsed terminal event — kimi, antigravity, droid — be marked
+     * completed on success instead of falsely failed.
+     */
     async reapProcess() {
         if (!this.pid)
             return null;
-        try {
-            process.kill(this.pid, 0);
+        // isProcessAlive() applies the start-time guard, so a recycled PID now
+        // owned by an unrelated process doesn't read as still-alive.
+        if (this.isProcessAlive())
             return null;
+        try {
+            const raw = (await fs.readFile(await this.getExitCodePath(), 'utf-8')).trim();
+            const code = Number.parseInt(raw, 10);
+            return Number.isNaN(code) ? 1 : code;
         }
         catch {
+            // No sentinel: the shell died before recording $? (killed mid-run).
             return 1;
         }
     }
@@ -998,7 +1049,19 @@ export class AgentManager {
             const stdoutPath = await agent.getStdoutPath();
             const stdoutFile = await fs.open(stdoutPath, 'w');
             const stdoutFd = stdoutFile.fd;
-            const childProcess = spawn(cmd[0], cmd.slice(1), {
+            // Wrap the teammate command in a shell that records the underlying CLI's
+            // exit code to a sentinel file. Detached + unref()'d children can't be
+            // wait()ed on by this parent, so the sentinel is the only durable record
+            // of the real exit status — reapProcess() reads it to decide
+            // completed-vs-failed for agents whose stream emits no parsed terminal
+            // event (kimi, antigravity, droid). Remove any stale sentinel from a
+            // prior run of the same agent id first so a restart can't read it.
+            const exitCodePath = await agent.getExitCodePath();
+            await fs.rm(exitCodePath, { force: true }).catch(() => { });
+            const wrappedCmd = buildSentinelCommand(cmd, exitCodePath);
+            // detached:true makes the shell the process-group leader, so stop()'s
+            // `kill(-pid)` still reaches the underlying CLI through the group.
+            const childProcess = spawn('/bin/sh', ['-c', wrappedCmd], {
                 stdio: ['ignore', stdoutFd, stdoutFd],
                 cwd: agent.cwd || undefined,
                 detached: true,

package/dist/lib/teams/api.js

@@ -139,6 +139,26 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
     debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}${profileName ? ` profile=${profileName}` : ''}...`);
+    // Budget pre-flight gate (issue #346). Teammates inherit the project's caps:
+    // before launching one, project its estimated cost onto current spend and
+    // refuse when on_exceed:block would be breached. Cross-vendor by construction
+    // — a Claude teammate and a Codex teammate draw down the same per_project /
+    // per_day pool. Dormant (no-op) when no caps are configured.
+    {
+        const gateCwd = cwd || workspaceDir || worktreePath || process.cwd();
+        const { runPreflightGate } = await import('../budget/preflight.js');
+        const gate = runPreflightGate({
+            agent: agentType,
+            model: model ?? `${agentType}-default`,
+            mode: resolvedMode,
+            prompt,
+            project: gateCwd,
+            cwd: gateCwd,
+        });
+        if (!gate.dormant && !gate.decision.allow) {
+            throw new Error(`[budget] BLOCKED teammate "${taskName}" (${agentType}): ${gate.decision.reason}`);
+        }
+    }
     const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {

package/dist/lib/teams/parsers.js

@@ -917,9 +917,16 @@ function normalizeGrok(raw) {
 //   - {"role":"assistant","content":"..."}                          → final message
 //   - {"role":"assistant","tool_calls":[{"function":{"name":"Bash","arguments":"<json>"}}]} → tool use
 //   - {"role":"tool","tool_call_id":"...","content":"..."}            → tool result
-//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → init / session id
-// Tool arguments are JSON-stringified inside `function.arguments` and must be
-// parsed before extracting paths/commands. Verified against live `kimi` runs.
+//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → terminal/result
+// Kimi emits NO dedicated result/turn-complete event and NO init event. The
+// `session.resume_hint` meta is its terminal marker: emitted exactly once, as
+// the LAST line, on clean completion (it carries the `kimi -r <id>` resume
+// command). We map it to a success `result` so the team runner resolves status
+// from the stream; the run's exit code remains the safety net for crashes that
+// never reach the hint. Tool arguments are JSON-stringified inside
+// `function.arguments` and must be parsed before extracting paths/commands.
+// Verified against live `kimi` runs (no-tool and tool-using) — see
+// __tests__/testdata/kimi-stream-*.jsonl.
 function normalizeKimi(raw) {
     const timestamp = new Date().toISOString();
     if (!raw || typeof raw !== 'object') {
@@ -1044,9 +1051,14 @@ function normalizeKimi(raw) {
     if (role === 'meta') {
         const metaType = typeof raw.type === 'string' ? raw.type : '';
         if (metaType === 'session.resume_hint') {
+            // Kimi's terminal marker (see header). Emit a success `result` so the
+            // team runner's terminal-event detection resolves the teammate to
+            // COMPLETED from the stream. session_id is preserved for cross-
+            // referencing — readNewEvents() captures it off any event.
             return [{
-                    type: 'init',
+                    type: 'result',
                     agent: 'kimi',
+                    status: 'success',
                     session_id: typeof raw.session_id === 'string' ? raw.session_id : null,
                     timestamp: timestamp,
                 }];

package/dist/lib/types.d.ts

@@ -22,6 +22,43 @@ export interface RunDefaults {
 export type RunConfig = Partial<Record<AgentId, AgentRunConfig>> & {
     defaults?: Record<string, RunDefaults>;
 };
+/**
+ * What to do when a configured budget cap would be exceeded (issue #346).
+ * `block` refuses to launch (or kills a running child) and exits non-zero so
+ * CI/headless/teams/cloud all inherit the decision. `warn` prints the overrun
+ * but proceeds — useful for soft rollout / observability-only.
+ */
+export type BudgetOnExceed = 'block' | 'warn';
+/**
+ * `budget:` block in agents.yaml — cross-vendor spend guardrails (issue #346).
+ *
+ * Resolution is project > user (same precedence as `run:`); see
+ * `resolveBudgetConfig` in lib/budget/config.ts. Every cap is in USD. A cap is
+ * "unset" when undefined — only set caps are enforced. `per_agent` caps apply
+ * to one agent's spend; the top-level caps (`per_run`, `per_day`,
+ * `per_project`) aggregate ACROSS every vendor the CLI dispatches, which is the
+ * cross-vendor property no single-vendor control has.
+ */
+export interface BudgetConfig {
+    /** Display currency. Only "USD" is priced today; carried for forward-compat. */
+    currency?: string;
+    /** Hard cap on the estimated/actual cost of a single run. */
+    per_run?: number;
+    /** Hard cap on total spend attributed to the current day (local date). */
+    per_day?: number;
+    /** Per-agent daily caps, keyed by agent id (e.g. { claude: 30, codex: 20 }). */
+    per_agent?: Partial<Record<AgentId, number>>;
+    /** Hard cap on cumulative spend attributed to the current project. */
+    per_project?: number;
+    /** block (refuse/kill) or warn (proceed). Defaults to block. */
+    on_exceed?: BudgetOnExceed;
+    /**
+     * Interactive confirm threshold (USD). When a run's pre-flight estimate is at
+     * or above this, prompt before launching (unless --yes). Does NOT gate a hard
+     * block — a cap breach always blocks regardless of this value.
+     */
+    require_confirm_over?: number;
+}
 /** Preview features that users can opt into via `agents beta`. */
 export type BetaFeatureName = 'drive' | 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */
@@ -210,6 +247,8 @@ export interface InstalledHook {
 export interface Manifest {
     agents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
+    /** Spend guardrails (issue #346). Project-local block overrides user. */
+    budget?: BudgetConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };
@@ -516,6 +555,15 @@ export interface ExtraRepoConfig {
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
+    /** macOS secrets-agent config. `auto` makes the first real keychain read of a
+     * `session`-tier bundle populate the broker so concurrent runs read silently. */
+    secrets?: {
+        agent?: {
+            auto?: boolean;
+        };
+    };
+    /** Spend guardrails (issue #346). User-global caps; project agents.yaml overrides. */
+    budget?: BudgetConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };

package/dist/lib/workflows.d.ts

@@ -6,6 +6,21 @@
  * are composed at runtime by `agents run <workflow>`.
  */
 import type { AgentId } from './types.js';
+/**
+ * The `loop:` block as it appears in WORKFLOW.md frontmatter (YAML, snake_case).
+ * Parsed defensively and translated to the camelCase LoopConfig the driver
+ * consumes (src/lib/loop.ts). See docs/07-entrypoints-and-loops.md.
+ */
+export interface LoopConfigRaw {
+    /** Stop condition. Only `signal` is supported today. */
+    until?: 'signal';
+    /** Hard cap on iterations. */
+    max_iterations?: number;
+    /** Token hard-cap, enforced outside the agent. */
+    budget?: number;
+    /** Delay between iterations ("0" back-to-back, "30m" paces). */
+    interval?: string;
+}
 /** Parsed WORKFLOW.md frontmatter. */
 export interface WorkflowFrontmatter {
     name: string;
@@ -22,6 +37,12 @@ export interface WorkflowFrontmatter {
      * Pass `--no-auto-secrets` to skip this injection.
      */
     secrets?: string[];
+    /**
+     * Optional loop block: wraps the workflow in a bounded until-condition loop
+     * (issue #332). When present, `agents run <workflow>` honors it without a
+     * `--loop` flag. Validated/coerced in parseWorkflowFrontmatter.
+     */
+    loop?: LoopConfigRaw;
 }
 /** A workflow found during repo discovery. */
 export interface DiscoveredWorkflow {
@@ -39,6 +60,41 @@ export interface InstalledWorkflow {
 }
 /** Parse WORKFLOW.md frontmatter from a workflow directory. Returns null if invalid. */
 export declare function parseWorkflowFrontmatter(workflowDir: string): WorkflowFrontmatter | null;
+/**
+ * Defensively coerce a frontmatter `loop:` value into a LoopConfigRaw.
+ *
+ * Mirrors the asStringArray discipline above: a malformed field is dropped to
+ * undefined rather than passed through, so the loop driver never sees a bad
+ * shape. Returns undefined when `loop:` is absent or not an object, or when no
+ * recognized field survives coercion (an all-garbage block is treated as
+ * "no loop", not "empty loop").
+ *
+ * Field rules:
+ *   - until:          only the literal `signal` is accepted; anything else dropped.
+ *   - max_iterations: a finite positive integer; non-numbers/<=0 dropped.
+ *   - budget:         a finite positive number (tokens); non-numbers/<=0 dropped.
+ *   - interval:       a string (e.g. "0", "30m"); non-strings dropped.
+ */
+export declare function parseLoopBlock(v: unknown): LoopConfigRaw | undefined;
+/**
+ * Decide which subagent .md stems a workflow may use, given the discovered
+ * subagent files and the parsed `allowedAgents` frontmatter. This is the
+ * fail-closed security boundary for issue #324:
+ *
+ *   - `allowedAgents === undefined` (field absent)  -> NO restriction; allow all.
+ *   - `allowedAgents === []`        (present, empty) -> allow ZERO; copy none.
+ *   - `allowedAgents = [a, b]`                       -> allow only those stems.
+ *
+ * An explicit empty array must NEVER widen to "allow all" — that would copy
+ * every subagent definition into the run, granting MORE access than declared.
+ *
+ * `available` are the .md filenames found in subagents/ (e.g. `security.md`).
+ * Returns the stems to copy and any allowedAgents entries with no matching file.
+ */
+export declare function resolveAllowedSubagents(available: string[], allowedAgents: string[] | undefined): {
+    allowedStems: string[];
+    missing: string[];
+};
 /** Count subagent .md files in a workflow's subagents/ directory. */
 export declare function countWorkflowSubagents(workflowDir: string): number;
 /**