@phnx-labs/agents-cli 1.22.25 → 1.22.26

package/dist/lib/session/tool-index.js

@@ -1,9 +1,9 @@
 import * as fs from 'fs';
 import { StringDecoder } from 'string_decoder';
-import { getDB } from './db.js';
+import { getDB, maintainSessionSearchIndex } from './db.js';
 import { parseSession } from './parse.js';
 import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, ToolCallCollector, collectClaudeToolCalls, collectCodexToolCalls, toolCallEvidenceBytes, toolCallsFromEvents, } from './tool-calls.js';
-import { persistToolCalls, purgeToolCalls, toolEvidenceSourcePath, } from './tool-store.js';
+import { canonicalToolLedgerPath, persistToolCalls, purgeToolCalls, toolEvidenceSourcePath, } from './tool-store.js';
 const BACKFILL_MAX_FILES = 25;
 const BACKFILL_MAX_BYTES = 16 * 1024 * 1024;
 const BACKFILL_MAX_IN_MEMORY_SOURCE_BYTES = 16 * 1024 * 1024;
@@ -39,16 +39,71 @@ export function toolSearchRemoteReceiveBudget(envelope) {
     const localBytes = serializedToolSearchEnvelopeBytes(envelope);
     return Math.max(0, TOOL_QUERY_MAX_SERIALIZED_BYTES - TOOL_QUERY_MERGE_OVERHEAD_BYTES - localBytes);
 }
-function needsIndex(db, sessionId, stamp) {
-    const row = db.prepare(`
-    SELECT file_mtime_ms, file_size, extractor_version
+/**
+ * The ledger columns every candidate session is judged on. Deliberately NOT
+ * `parser_state`: this runs once per session in the scan's warm path, and that
+ * column holds a serialized collector snapshot that can reach a megabyte. It is
+ * read separately, only for the sessions that turn out to need indexing.
+ */
+function readToolLedger(db, sessionId) {
+    return db.prepare(`
+    SELECT file_path, file_mtime_ms, file_size, extractor_version, parsed_offset
     FROM tool_scan_ledger WHERE session_id = ?
   `).get(sessionId);
+}
+function readToolParserState(db, sessionId) {
+    const row = db.prepare(`SELECT parser_state FROM tool_scan_ledger WHERE session_id = ?`)
+        .get(sessionId);
+    return row?.parser_state ?? null;
+}
+function needsIndex(row, stamp) {
     return !row
         || row.file_mtime_ms !== stamp.fileMtimeMs
         || row.file_size !== stamp.fileSize
         || row.extractor_version !== TOOL_INDEX_VERSION;
 }
+/**
+ * Where to start reading a session whose transcript changed.
+ *
+ * A live session's transcript is append-only, so re-reading it from byte 0 on
+ * every scan re-parses the entire history to discover the handful of records
+ * that are new — the cost that makes a large session's tool index quadratic in
+ * the number of scans. When the ledger carries a resume point that the current
+ * file still agrees with, the scan reads only the appended bytes and merges the
+ * result (`append`); anything else re-reads the whole file (`replace`).
+ *
+ * Each check below rejects a case where the stored prefix may no longer describe
+ * the file: a harness the streaming parser cannot resume, a different extractor,
+ * no recorded resume point, a source path the ledger row does not describe, a
+ * file that shrank below what was already parsed (a rewrite or truncation, not
+ * an append), or a snapshot that does not read back.
+ */
+function planToolScan(db, sessionId, row, sourcePath, stamp, resumable) {
+    const full = { mode: 'replace', startOffset: 0 };
+    if (!resumable || !row)
+        return full;
+    if (row.extractor_version !== TOOL_INDEX_VERSION)
+        return full;
+    if (row.parsed_offset === null)
+        return full;
+    if (row.file_path !== canonicalToolLedgerPath(sourcePath))
+        return full;
+    if (stamp.fileSize < row.file_size || stamp.fileSize < row.parsed_offset)
+        return full;
+    const parserState = readToolParserState(db, sessionId);
+    if (parserState === null)
+        return full;
+    let snapshot;
+    try {
+        snapshot = JSON.parse(parserState);
+    }
+    catch {
+        return full;
+    }
+    if (snapshot?.v !== 1 || !Number.isSafeInteger(snapshot.nextOrdinal))
+        return full;
+    return { mode: 'append', startOffset: row.parsed_offset, snapshot };
+}
 /** Read index completeness from SQLite only; never stat or parse transcripts. */
 export function readToolIndexCoverage(sessions) {
     const db = getDB();
@@ -90,14 +145,23 @@ function backfillLimitCall(session, reason) {
     };
 }
 /** Stream Claude/Codex JSONL without ever retaining an oversized record. */
-async function streamJsonlToolCalls(session) {
-    const collector = new ToolCallCollector();
-    const stream = fs.createReadStream(session.filePath, { highWaterMark: 64 * 1024 });
+async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
+    const collector = new ToolCallCollector(from.snapshot);
+    const stream = fs.createReadStream(session.filePath, {
+        highWaterMark: 64 * 1024,
+        start: from.startOffset,
+    });
     const decoder = new StringDecoder('utf8');
     let pending = '';
     let pendingBytes = 0;
     let droppingOversizedLine = false;
     let skippedOversizedLine = false;
+    // Byte offset just past the last complete record applied. Only a complete,
+    // newline-terminated record advances it, so resuming here can never re-apply a
+    // record (which would mint a second ordinal for it) nor skip a partial tail.
+    let parsedOffset = from.startOffset;
+    /** Bytes of the record currently being assembled, across chunk boundaries. */
+    let lineBytes = 0;
     const applyLine = (line) => {
         if (!line.trim())
             return;
@@ -119,8 +183,14 @@ async function streamJsonlToolCalls(session) {
             const newline = text.indexOf('\n', start);
             const end = newline >= 0 ? newline : text.length;
             const segment = text.slice(start, end);
+            const segmentBytes = Buffer.byteLength(segment);
+            // Counted outside the drop guard and across chunk boundaries: this is the
+            // record's true size on disk, which is what the resume offset is measured
+            // in. `pendingBytes` cannot stand in for it — that one resets when an
+            // oversized record is dropped, and a record split over two 64 KiB reads
+            // would lose the part carried in from the previous chunk.
+            lineBytes += segmentBytes;
             if (!droppingOversizedLine) {
-                const segmentBytes = Buffer.byteLength(segment);
                 if (pendingBytes + segmentBytes <= BACKFILL_MAX_JSONL_RECORD_BYTES) {
                     pending += segment;
                     pendingBytes += segmentBytes;
@@ -136,6 +206,8 @@ async function streamJsonlToolCalls(session) {
                 break;
             if (!droppingOversizedLine)
                 applyLine(pending);
+            parsedOffset += lineBytes + 1; // + the newline itself
+            lineBytes = 0;
             pending = '';
             pendingBytes = 0;
             droppingOversizedLine = false;
@@ -145,25 +217,48 @@ async function streamJsonlToolCalls(session) {
     for await (const chunk of stream)
         consume(decoder.write(chunk));
     consume(decoder.end());
+    // Snapshot BEFORE the unterminated trailing record, and pair it with an offset
+    // that stops short of that record. The writer may be mid-append, so the record
+    // is indexed now (its evidence is real) but is re-read by the next scan — which
+    // resumes with the same next-ordinal and so re-derives the same ordinals,
+    // making the re-read an idempotent upsert rather than a duplicate.
+    const resume = skippedOversizedLine
+        // A dropped oversized record left the ordinals and the pending map out of
+        // step with the file; nothing here can be resumed from.
+        ? null
+        : { parserState: JSON.stringify(collector.snapshot()), parsedOffset };
     if (!droppingOversizedLine && pending.length > 0)
         applyLine(pending);
     const calls = collector.drainChanged();
     if (skippedOversizedLine && !calls.some((call) => call.ordinal === TOOL_INDEX_LIMIT_ORDINAL)) {
         calls.push(backfillLimitCall(session, 'At least one JSONL record exceeded the 1 MiB tool-backfill parser limit.'));
     }
-    return calls;
+    return { calls, resume };
+}
+/** True for the harnesses whose transcript the streaming parser can resume. */
+function isResumableToolSource(agent) {
+    return agent === 'claude' || agent === 'codex';
 }
-async function toolCallsForBackfill(session, sourceBytes) {
-    if (session.agent === 'claude' || session.agent === 'codex') {
+async function toolCallsForBackfill(session, sourceBytes, from = { startOffset: 0 }) {
+    if (isResumableToolSource(session.agent)) {
         if (sourceBytes > BACKFILL_MAX_STREAM_SOURCE_BYTES) {
-            return [backfillLimitCall(session, 'Transcript exceeds the 64 MiB safe streaming tool-backfill limit.')];
+            return {
+                calls: [backfillLimitCall(session, 'Transcript exceeds the 64 MiB safe streaming tool-backfill limit.')],
+                resume: null,
+            };
         }
-        return streamJsonlToolCalls(session);
+        return streamJsonlToolCalls(session, from);
     }
     if (sourceBytes > BACKFILL_MAX_IN_MEMORY_SOURCE_BYTES) {
-        return [backfillLimitCall(session, 'Transcript exceeds the 16 MiB safe in-memory tool-backfill parser limit.')];
+        return {
+            calls: [backfillLimitCall(session, 'Transcript exceeds the 16 MiB safe in-memory tool-backfill parser limit.')],
+            resume: null,
+        };
     }
-    return toolCallsFromEvents(parseSession(session.filePath, session.agent));
+    // Every other harness is parsed whole into memory by parseSession, which
+    // exposes no byte offset to resume from — so these stay full replaces and
+    // record no resume point, rather than storing one this path cannot honour.
+    return { calls: toolCallsFromEvents(parseSession(session.filePath, session.agent)), resume: null };
 }
 /**
  * Fill one bounded chunk of the independent tool index. A warm call performs
@@ -179,6 +274,7 @@ export async function ensureToolIndex(sessions, limits = {}) {
         if (!session.filePath)
             continue;
         const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
+        const ledger = readToolLedger(db, session.id);
         const mustStatSource = limits.verifySourceStamps || sourcePath !== session.filePath;
         const indexed = !mustStatSource
             ? db.prepare(`
@@ -199,8 +295,15 @@ export async function ensureToolIndex(sessions, limits = {}) {
                 continue;
             }
         }
-        if (needsIndex(db, session.id, stamp))
-            pending.push({ session, stamp });
+        if (!needsIndex(ledger, stamp))
+            continue;
+        const plan = planToolScan(db, session.id, ledger, sourcePath, stamp, isResumableToolSource(session.agent));
+        pending.push({
+            session,
+            stamp,
+            plan,
+            readBytes: Math.max(0, stamp.fileSize - plan.startOffset),
+        });
     }
     let indexedFiles = 0;
     let indexedCalls = 0;
@@ -212,13 +315,16 @@ export async function ensureToolIndex(sessions, limits = {}) {
         // The byte budget is a batch boundary, not a correctness boundary. Admit
         // one oversized transcript by itself so it can never wedge the ledger or
         // silently disappear from results; the next invocation resumes afterward.
-        if (attemptedFiles > 0 && consumedBytes + item.stamp.fileSize > maxBytes)
+        // Budgeted on the bytes this scan reads, not the file's size: a resumed
+        // session costs only its appended tail, so a batch can cover far more
+        // growing sessions than it could when every one was re-read whole.
+        if (attemptedFiles > 0 && consumedBytes + item.readBytes > maxBytes)
             break;
         attemptedFiles++;
-        consumedBytes += item.stamp.fileSize;
+        consumedBytes += item.readBytes;
         try {
-            const calls = await toolCallsForBackfill(item.session, item.stamp.fileSize);
-            persistToolCalls(db, item.session, calls, item.stamp);
+            const { calls, resume } = await toolCallsForBackfill(item.session, item.stamp.fileSize, item.plan);
+            persistToolCalls(db, item.session, calls, item.stamp, { mode: item.plan.mode, resume });
             indexedFiles++;
             indexedCalls += calls.length;
         }
@@ -226,6 +332,11 @@ export async function ensureToolIndex(sessions, limits = {}) {
             skippedFiles++;
         }
     }
+    // The scan just wrote a batch of FTS segments; pay a bounded slice of the
+    // merge they need so the index converges here instead of degrading until
+    // someone runs `agents sessions optimize` by hand (RUSH-2208).
+    if (indexedFiles > 0)
+        maintainSessionSearchIndex(db);
     const remainingFiles = Math.max(0, pending.length - attemptedFiles);
     const limitedSessionIds = new Set();
     const sessionIds = sessions.map((session) => session.id);

package/dist/lib/session/tool-store.d.ts

@@ -8,8 +8,32 @@ export declare function toolEvidenceSourcePath(filePath: string, agent: string):
 export declare function purgeToolCalls(db: Database.Database, sessionId: string): void;
 /** Purge deleted direct children when a transcript directory's stamp changes. */
 export declare function purgeMissingToolCallsInDirectory(db: Database.Database, dirPath: string, currentFilePaths: string[]): number;
-/** Persist one parser batch and its file stamp atomically. */
+/** The resume point a later incremental scan starts from. */
+export interface ToolScanResumePoint {
+    /** Serialized ToolCallCollector snapshot at `parsedOffset`. */
+    parserState: string;
+    /** Byte offset just past the last complete record consumed. */
+    parsedOffset: number;
+}
+export interface PersistToolCallsOptions {
+    /**
+     * `replace` drops the session's stored evidence first — correct for a parse
+     * that started at byte 0. `append` merges the batch into what is already
+     * stored and requires an existing ledger row; use it only for a parse that
+     * resumed from that row's `parsedOffset`.
+     */
+    mode?: 'replace' | 'append';
+    /**
+     * Where a later scan may resume. Omitted (or null) clears any stored resume
+     * point, which forces the next scan of this session to re-read from byte 0 —
+     * the correct outcome whenever the parse could not cover the whole prefix
+     * (an oversized record, a size-capped transcript, a non-streaming harness).
+     */
+    resume?: ToolScanResumePoint | null;
+    maxSessionBytes?: number;
+}
+/** Persist one parser batch, its file stamp, and its resume point atomically. */
 export declare function persistToolCalls(db: Database.Database, session: SessionMeta, calls: IndexedToolCall[], sourceStamp: {
     fileMtimeMs: number;
     fileSize: number;
-}, mode?: 'replace' | 'append', maxSessionBytes?: number): void;
+}, options?: PersistToolCallsOptions): void;

package/dist/lib/session/tool-store.js

@@ -28,11 +28,17 @@ export function toolEvidenceSourcePath(filePath, agent) {
     return filePath;
 }
 function deleteSessionCalls(db, sessionId) {
-    const keys = db.prepare(`SELECT call_key FROM tool_calls WHERE session_id = ?`).all(sessionId);
-    for (const { call_key } of keys) {
-        db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`).run(call_key);
-        db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`).run(call_key);
-        db.prepare(`DELETE FROM tool_call_text WHERE call_key = ?`).run(call_key);
+    const rows = db.prepare(`SELECT rowid, call_key FROM tool_calls WHERE session_id = ?`)
+        .all(sessionId);
+    const deletePrograms = db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`);
+    const deleteOccurrences = db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`);
+    // Addressed by rowid, never by the UNINDEXED call_key — see the tool_call_text
+    // schema comment in db.ts. A call_key predicate scans the whole FTS index.
+    const deleteText = db.prepare(`DELETE FROM tool_call_text WHERE rowid = ?`);
+    for (const { rowid, call_key } of rows) {
+        deletePrograms.run(call_key);
+        deleteOccurrences.run(call_key);
+        deleteText.run(rowid);
     }
     db.prepare(`DELETE FROM tool_calls WHERE session_id = ?`).run(sessionId);
 }
@@ -61,8 +67,11 @@ export function purgeMissingToolCallsInDirectory(db, dirPath, currentFilePaths)
     }
     return purged;
 }
-/** Persist one parser batch and its file stamp atomically. */
-export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replace', maxSessionBytes = TOOL_SESSION_EVIDENCE_MAX_BYTES) {
+/** Persist one parser batch, its file stamp, and its resume point atomically. */
+export function persistToolCalls(db, session, calls, sourceStamp, options = {}) {
+    const mode = options.mode ?? 'replace';
+    const maxSessionBytes = options.maxSessionBytes ?? TOOL_SESSION_EVIDENCE_MAX_BYTES;
+    const resume = options.resume ?? null;
     const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
     const insertCall = db.prepare(`
     INSERT INTO tool_calls (
@@ -89,16 +98,19 @@ export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replac
     INSERT INTO tool_program_occurrences (call_key, occurrence_ordinal, program, role)
     VALUES (?, ?, ?, ?)
   `);
-    const insertText = db.prepare(`INSERT INTO tool_call_text (call_key, tool, input, output, error) VALUES (?, ?, ?, ?, ?)`);
+    // tool_call_text rows are addressed by the rowid of the tool_calls row they
+    // describe (db.ts schema comment): its UNINDEXED call_key cannot be seeked.
+    const insertText = db.prepare(`INSERT INTO tool_call_text (rowid, call_key, tool, input, output, error) VALUES (?, ?, ?, ?, ?, ?)`);
+    const callRowid = db.prepare(`SELECT rowid FROM tool_calls WHERE call_key = ?`);
     const deletePrograms = db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`);
     const deleteOccurrences = db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`);
-    const deleteText = db.prepare(`DELETE FROM tool_call_text WHERE call_key = ?`);
+    const deleteText = db.prepare(`DELETE FROM tool_call_text WHERE rowid = ?`);
     const deleteCall = db.prepare(`DELETE FROM tool_calls WHERE call_key = ?`);
     const writeLedger = db.prepare(`
     INSERT INTO tool_scan_ledger (
       session_id, file_path, file_mtime_ms, file_size, extractor_version, indexed_at, call_count,
-      evidence_bytes
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      evidence_bytes, parser_state, parsed_offset
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(session_id) DO UPDATE SET
       file_path = excluded.file_path,
       file_mtime_ms = excluded.file_mtime_ms,
@@ -106,7 +118,9 @@ export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replac
       extractor_version = excluded.extractor_version,
       indexed_at = excluded.indexed_at,
       call_count = excluded.call_count,
-      evidence_bytes = excluded.evidence_bytes
+      evidence_bytes = excluded.evidence_bytes,
+      parser_state = excluded.parser_state,
+      parsed_offset = excluded.parsed_offset
   `);
     const txn = db.transaction(() => {
         if (mode === 'replace')
@@ -119,7 +133,7 @@ export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replac
             throw new Error('Append tool evidence requires an existing tool ledger row.');
         }
         if (mode === 'append' && calls.length === 0) {
-            writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), priorLedger.call_count, priorLedger.evidence_bytes);
+            writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), priorLedger.call_count, priorLedger.evidence_bytes, resume?.parserState ?? null, resume?.parsedOffset ?? null);
             return;
         }
         const limitKey = toolCallKey(session.id, TOOL_INDEX_LIMIT_ORDINAL);
@@ -129,9 +143,11 @@ export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replac
         const priorLimit = mode === 'append'
             ? existingSize.get(session.id, TOOL_INDEX_LIMIT_ORDINAL)
             : undefined;
+        const limitRow = callRowid.get(limitKey);
         deletePrograms.run(limitKey);
         deleteOccurrences.run(limitKey);
-        deleteText.run(limitKey);
+        if (limitRow)
+            deleteText.run(limitRow.rowid);
         deleteCall.run(limitKey);
         const existingRows = mode === 'append'
             ? calls.map((call) => ({
@@ -182,17 +198,20 @@ export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replac
         for (const call of accepted) {
             const key = toolCallKey(session.id, call.ordinal);
             insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.tool, call.input, call.outcome, call.exitCode ?? null, call.statusCode ?? null, call.errorCode ?? null, call.output ?? null, call.error ?? null, call.parseError ?? null, toolCallEvidenceBytes(call));
+            // The upsert above preserves the rowid of a call it updated, so this is
+            // the same rowid the existing text row (if any) was written under.
+            const { rowid } = callRowid.get(key);
             deletePrograms.run(key);
             deleteOccurrences.run(key);
-            deleteText.run(key);
+            deleteText.run(rowid);
             for (const program of call.programs)
                 insertProgram.run(key, program);
             call.programOccurrences.forEach((occurrence, occurrenceOrdinal) => {
                 insertOccurrence.run(key, occurrenceOrdinal, occurrence.program, occurrence.role);
             });
-            insertText.run(key, call.tool, call.input, call.output ?? '', call.error ?? '');
+            insertText.run(rowid, key, call.tool, call.input, call.output ?? '', call.error ?? '');
         }
-        writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), count, storedBytes);
+        writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), count, storedBytes, resume?.parserState ?? null, resume?.parsedOffset ?? null);
     });
     txn();
 }

package/dist/lib/ssh-exec.js

@@ -117,7 +117,11 @@ export function sshExec(target, remoteCmd, opts = {}) {
         stdio: ['pipe', 'pipe', 'pipe'],
         windowsHide: true,
     });
-    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    // Node's spawnSync with a `timeout` option kills the child via SIGTERM and sets
+    // res.signal (e.g. 'SIGTERM') — it does NOT set res.error.code = 'ETIMEDOUT'.
+    // Check both so the detection fires whether the timeout is signalled or errored.
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT') ||
+        (!!opts.timeoutMs && res.signal !== null);
     return {
         code: typeof res.status === 'number' ? res.status : null,
         stdout: res.stdout ?? '',
@@ -206,7 +210,9 @@ export function sshExecRaw(target, remoteCmd, opts = {}) {
         stdio: ['pipe', 'pipe', 'pipe'],
         windowsHide: true,
     });
-    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    // Same fix as sshExec: spawnSync sets res.signal, not error.code = 'ETIMEDOUT'.
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT') ||
+        (!!opts.timeoutMs && res.signal !== null);
     return {
         code: typeof res.status === 'number' ? res.status : null,
         stdout: res.stdout ?? Buffer.alloc(0),

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

@@ -47,6 +47,7 @@ export declare const loadMonitors: ModuleLoader;
 export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
 export declare const loadResume: ModuleLoader;
+export declare const loadReconnect: ModuleLoader;
 export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadSet: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -25,6 +25,7 @@ export const loadMonitors = async () => (await import('../../commands/monitors.j
 export const loadProjects = async () => (await import('../../commands/projects.js')).registerProjectsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
 export const loadResume = async () => (await import('../../commands/resume.js')).registerResumeCommand;
+export const loadReconnect = async () => (await import('../../commands/reconnect.js')).registerReconnectCommand;
 export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadSet = async () => (await import('../../commands/set.js')).registerSetCommand;
@@ -53,6 +54,7 @@ export const loadUsage = async () => (await import('../../commands/usage.js')).r
 export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
 export const loadInsights = async () => (await import('../../commands/insights.js')).registerInsightsCommand;
 export const loadPerf = async () => (await import('../../commands/perf.js')).registerPerfCommand;
+// Thin deprecated alias of `agents insights mix` — no second mix implementation.
 export const loadTrends = async () => (await import('../../commands/trends.js')).registerTrendsCommand;
 export const loadOutput = async () => (await import('../../commands/output.js')).registerOutputCommand;
 export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
@@ -98,6 +100,7 @@ export const loadHumans = async () => (await import('../../commands/humans.js'))
 export const LAZY_COMMAND_NAMES = new Set([
     'sessions',
     'resume',
+    'reconnect',
     'roster',
     'teams',
     'cloud',
@@ -156,6 +159,7 @@ export const COMMAND_LOADERS = {
     projects: [loadProjects],
     run: [loadRun],
     resume: [loadResume],
+    reconnect: [loadReconnect],
     fork: [loadFork],
     defaults: [loadDefaults],
     set: [loadSet],

package/dist/lib/teams/agents.d.ts

@@ -1,5 +1,6 @@
 import { captureProcessStartTime } from '../platform/index.js';
 import { AgentType } from './parsers.js';
+import { NoViableDeviceError } from './scheduler.js';
 /**
  * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
  * Returns the deepest common directory shared by all paths.
@@ -405,6 +406,18 @@ export declare class AgentManager {
      * teammate schedules identically no matter how it was fired.
      */
     private maybeSchedulePlacement;
+    /** Human label of a teammate's agent for the placement fail-loud message. */
+    private placementAgentLabel;
+    /**
+     * Pre-flight the team pool at `teams start` (RUSH-2002): probe the pool and
+     * confirm each distinct agent among the pending, unpinned, pooled teammates
+     * has at least one viable device. Returns the first {@link NoViableDeviceError}
+     * so the command can fail loud BEFORE launching a wave, rather than silently
+     * leaving teammates stranded pending. A poolless team (no `--devices`) or a
+     * probe that could not gather positive evidence returns null — fail-loud fires
+     * only on proof that no device can run the agent, never on a probe miss.
+     */
+    preflightPlacement(taskName: string): Promise<NoViableDeviceError | null>;
     /**
      * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
      * The supervisor calls this each wave BEFORE listByTask() so the per-teammate

package/dist/lib/teams/agents.js

@@ -34,7 +34,8 @@ import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { pullRemoteLogDelta, REMOTE_MIRROR_MAX_BYTES } from '../hosts/progress.js';
 import { createRemoteWorktree, ensureRemoteRepo } from './remoteWorktree.js';
 import { getTeam } from './registry.js';
-import { resolvePlacement, cappedDevices } from './scheduler.js';
+import { resolvePlacement, classifyExclusions, NoViableDeviceError } from './scheduler.js';
+import { probePoolSignals } from './placement-probe.js';
 import { readMaxConcurrentCaps } from '../device-config.js';
 import chalk from 'chalk';
 let lastMemoryWarnAt = 0;
@@ -1756,7 +1757,7 @@ export class AgentManager {
      * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
      * teammate schedules identically no matter how it was fired.
      */
-    async maybeSchedulePlacement(agent, taskName) {
+    async maybeSchedulePlacement(agent, taskName, opts = {}) {
         if (agent.hostName || agent.cloudProvider)
             return;
         const teamMeta = await getTeam(taskName);
@@ -1765,15 +1766,79 @@ export class AgentManager {
         const roster = await this.listByTask(taskName);
         const pool = teamMeta.devices ?? [];
         const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
-        if (maxConcurrent) {
-            for (const c of cappedDevices(pool, roster, maxConcurrent)) {
-                console.error(chalk.dim(`[placement] '${c.device}' excluded from auto-pick — at its agents.max-concurrent cap (${c.running}/${c.cap} running)`));
+        // On the start path (opts.probe), gather live signals so the pick is health-,
+        // harness-, and load-aware (RUSH-2002); the add path stays the cap-only
+        // roster count so `teams add` never blocks on an SSH fan-out. Cached per
+        // (pool, agent), so a wave placing many teammates probes the pool once.
+        const signals = opts.probe && pool.length > 0
+            ? await probePoolSignals(pool, agent.agentType, { now: Date.now() })
+            : undefined;
+        const placeOpts = {
+            maxConcurrent,
+            signals,
+            agentLabel: this.placementAgentLabel(agent),
+        };
+        if (signals) {
+            for (const e of classifyExclusions(pool, roster, placeOpts).excluded) {
+                const why = e.reason === 'capped'
+                    ? `at its agents.max-concurrent cap (${e.detail} running)`
+                    : e.reason === 'not-installed'
+                        ? `does not have ${this.placementAgentLabel(agent)} installed`
+                        : e.reason;
+                console.error(chalk.dim(`[placement] '${e.device}' excluded from auto-pick — ${why}`));
             }
         }
-        const { device } = resolvePlacement(teamMeta, null, roster, { maxConcurrent });
+        const { device } = resolvePlacement(teamMeta, null, roster, placeOpts);
         if (device)
             await this.resolveScheduledPlacement(agent, device, taskName);
     }
+    /** Human label of a teammate's agent for the placement fail-loud message. */
+    placementAgentLabel(agent) {
+        return agent.version ? `${agent.agentType}@${agent.version}` : String(agent.agentType);
+    }
+    /**
+     * Pre-flight the team pool at `teams start` (RUSH-2002): probe the pool and
+     * confirm each distinct agent among the pending, unpinned, pooled teammates
+     * has at least one viable device. Returns the first {@link NoViableDeviceError}
+     * so the command can fail loud BEFORE launching a wave, rather than silently
+     * leaving teammates stranded pending. A poolless team (no `--devices`) or a
+     * probe that could not gather positive evidence returns null — fail-loud fires
+     * only on proof that no device can run the agent, never on a probe miss.
+     */
+    async preflightPlacement(taskName) {
+        await this.initialize();
+        const teamMeta = await getTeam(taskName);
+        const pool = teamMeta?.devices ?? [];
+        if (!teamMeta || pool.length === 0)
+            return null;
+        const roster = await this.listByTask(taskName);
+        const pending = roster.filter((a) => a.status === AgentStatus.PENDING && !a.hostName && !a.cloudProvider);
+        if (pending.length === 0)
+            return null;
+        const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
+        // One representative teammate per distinct agent type — the signal + gate is
+        // per harness, not per teammate.
+        const byAgent = new Map();
+        for (const a of pending)
+            if (!byAgent.has(a.agentType))
+                byAgent.set(a.agentType, a);
+        for (const [, rep] of byAgent) {
+            const signals = await probePoolSignals(pool, rep.agentType, { now: Date.now() });
+            try {
+                resolvePlacement(teamMeta, null, roster, {
+                    maxConcurrent,
+                    signals,
+                    agentLabel: this.placementAgentLabel(rep),
+                });
+            }
+            catch (err) {
+                if (err instanceof NoViableDeviceError)
+                    return err;
+                throw err;
+            }
+        }
+        return null;
+    }
     /**
      * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
      * The supervisor calls this each wave BEFORE listByTask() so the per-teammate
@@ -1866,9 +1931,12 @@ export class AgentManager {
             // immediate-add and staged paths agree. A null pick keeps hostName null →
             // local spawn, unchanged. Cloud teammates never schedule.
             try {
-                await this.maybeSchedulePlacement(agent, taskName);
+                await this.maybeSchedulePlacement(agent, taskName, { probe: true });
             }
             catch (err) {
+                // A NoViableDeviceError means the pool cannot host this teammate right
+                // now — leave it PENDING (never a silent local fallback) and surface the
+                // reason; a transient device loss is retried next wave.
                 console.error(`Could not schedule ${agent.agentId} onto the team pool:`, err);
                 continue;
             }

package/dist/lib/teams/placement-probe.d.ts

@@ -0,0 +1,21 @@
+import { type AgentType } from './agents.js';
+import type { DevicePlacementSignal } from './scheduler.js';
+/** Per-remote readiness probe budget — matches the health probe's short window
+ * (`agents view` on a warm box is sub-second; a wedged one degrades to unknown). */
+export declare const READY_PROBE_TIMEOUT_MS = 8000;
+/** How long a probed pool snapshot is reused within a `teams start` wave. Short
+ * enough that a device coming online / going overloaded is seen next wave, long
+ * enough that placing a wave of teammates does not re-fan-out per teammate. */
+export declare const SIGNAL_TTL_MS = 15000;
+/** Clear the probe cache — for tests and after a device-registry change. */
+export declare function clearPlacementSignalCache(): void;
+/**
+ * Probe every device in the team pool and return a name→signal map for the pure
+ * placement pick. Devices with no data at all are omitted (the pick then neither
+ * excludes nor prefers them). Never throws — a probe failure degrades to a
+ * missing/partial signal.
+ */
+export declare function probePoolSignals(pool: string[], agent: AgentType, opts?: {
+    force?: boolean;
+    now?: number;
+}): Promise<Map<string, DevicePlacementSignal>>;