@phnx-labs/agents-cli 1.20.17 → 1.20.18

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

@@ -23,6 +23,8 @@ export interface SessionRow {
     label: string | null;
     message_count: number | null;
     token_count: number | null;
+    cost_usd: number | null;
+    duration_ms: number | null;
     file_path: string;
     file_mtime_ms: number | null;
     file_size: number | null;
@@ -50,6 +52,12 @@ export interface QueryOptions {
     excludeTeamOrigin?: boolean;
     /** Keep only team-origin rows (for hidden-count queries). */
     onlyTeamOrigin?: boolean;
+    /**
+     * Column to order by, all descending. 'timestamp' (default) sorts newest
+     * first; 'cost' and 'duration' put the priciest / longest sessions on top,
+     * with NULLs sorted last so unpriced rows never crowd out real data.
+     */
+    sortBy?: 'timestamp' | 'cost' | 'duration';
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export declare function getDB(): Database.Database;
@@ -114,6 +122,38 @@ export declare function syncLabels(labelMap: Map<string, string | null>): number
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;
+/** One grouped row in a cost/duration rollup. */
+export interface UsageRollupRow {
+    /** Grouping key value: the agent id, project name, or ISO date (YYYY-MM-DD). */
+    key: string;
+    costUsd: number;
+    durationMs: number;
+    sessionCount: number;
+    tokenCount: number;
+}
+/** What to group a usage rollup by. */
+export type UsageRollupGroup = 'agent' | 'project' | 'day';
+/**
+ * Aggregate cost / duration / tokens across sessions, grouped by agent,
+ * project, or calendar day. Honors the same filter shape as querySessions
+ * (agent, since/until, team-origin) so `agents cost --since 7d --by day`
+ * lines up with what `agents sessions` would list. Ordered by cost desc.
+ */
+export declare function queryUsageRollup(options: QueryOptions & {
+    groupBy: UsageRollupGroup;
+}): UsageRollupRow[];
+/** A session with its cost, for the top-N-by-cost listing. */
+export interface TopCostSession {
+    meta: SessionMeta;
+    costUsd: number;
+    durationMs: number;
+}
+/**
+ * Return the N most expensive sessions (cost_usd DESC, NULLs excluded),
+ * honoring the same filter shape as querySessions. Drops rows whose JSONL
+ * vanished, mirroring querySessions' liveness filter.
+ */
+export declare function topSessionsByCost(n: number, options?: QueryOptions): TopCostSession[];
 /** Return the set of all file paths currently tracked in the sessions table. */
 export declare function getAllFilePaths(): Set<string>;
 /** Look up sessions by their source file paths. */

package/dist/lib/session/db.js

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

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

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

package/dist/lib/session/discover.js

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

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

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

package/dist/lib/session/render.js

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

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

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

package/dist/lib/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;
 }
 /**