@phnx-labs/agents-cli 1.22.57 → 1.22.58

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

@@ -12,7 +12,10 @@ export const TOOL_CHANGED_MAX_CALLS = 10_000;
 export const TOOL_INDEX_LIMIT_ORDINAL = Number.MAX_SAFE_INTEGER;
 export const TOOL_TEXT_PROCESSING_MAX_BYTES = 64 * 1024;
 export const TOOL_SHELL_PARSE_MAX_BYTES = 64 * 1024;
-export const TOOL_INDEX_VERSION = 7;
+// Bumped to 8 for the per-call end timestamp (PHNX-3437): the extractor now
+// records when a call's result arrived, so a re-index re-derives it for rows
+// stored by an older extractor.
+export const TOOL_INDEX_VERSION = 8;
 const BASE64_BLOCK = /(?:[A-Za-z0-9+/]{256,}={0,2})/g;
 const SECRET_FIELD = /(?:token|secret|password|authorization|cookie|api[_-]?key|private[_-]?key)$/i;
 const KNOWN_SECRET_VALUES = knownSecretValuesFromEnv();
@@ -310,7 +313,7 @@ function buildCall(ordinal, timestamp, tool, args, command, sourceCallId) {
 }
 export function toolCallEvidenceBytes(call) {
     return Buffer.byteLength([
-        call.sourceCallId, call.timestamp, call.tool, call.input, call.errorCode,
+        call.sourceCallId, call.timestamp, call.endTimestamp, call.tool, call.input, call.errorCode,
         call.output, call.error, call.parseError, ...call.programs,
         ...call.programOccurrences.map((occurrence) => `${occurrence.role}:${occurrence.program}`),
     ].filter((value) => typeof value === 'string').join('\0'));
@@ -363,6 +366,9 @@ export class ToolCallCollector {
         const call = this.takePending(args.sourceCallId, tool);
         if (!call)
             return undefined;
+        if (typeof args.timestamp === 'string' && args.timestamp.length > 0) {
+            call.endTimestamp = sanitizeToolEvidenceText(args.timestamp, 128);
+        }
         const outcome = args.outcome === 'ok' || args.outcome === 'error' || args.outcome === 'unknown'
             ? args.outcome
             : undefined;
@@ -471,50 +477,74 @@ export class ToolCallCollector {
         return true;
     }
 }
+/** Fold one normalized event into a collector (the full-file harness contract). */
+function foldEventIntoCollector(collector, event) {
+    if (event.type === 'tool_use') {
+        collector.start({
+            timestamp: event.timestamp,
+            tool: event.tool || 'unknown',
+            input: event.args,
+            command: event.command,
+            sourceCallId: event.callId,
+        });
+    }
+    else if (event.type === 'tool_result') {
+        collector.finish({
+            timestamp: event.timestamp,
+            sourceCallId: event.callId,
+            tool: event.tool,
+            success: event.success,
+            outcome: event.outcome,
+            exitCode: event.exitCode,
+            statusCode: event.statusCode,
+            errorCode: event.errorCode,
+            output: event.output,
+        });
+    }
+    else if (event.type === 'error' && event.tool) {
+        const structuredError = event.outcome === 'error' || event.success === false;
+        const evidence = event.content || event.output || 'Tool execution failed';
+        collector.finish({
+            timestamp: event.timestamp,
+            sourceCallId: event.callId,
+            tool: event.tool,
+            success: structuredError ? false : undefined,
+            outcome: event.outcome,
+            exitCode: event.exitCode,
+            statusCode: event.statusCode,
+            errorCode: event.errorCode,
+            error: structuredError ? evidence : undefined,
+            output: structuredError ? undefined : evidence,
+        });
+    }
+}
+/**
+ * Derive tool calls from a full-file harness's normalized events, optionally
+ * RESUMING from a prior scan of the same append-only stream.
+ *
+ * Without `prior` this is a full parse from event 0 (identical to the legacy
+ * {@link toolCallsFromEvents}). With `prior`, the collector is seeded from the
+ * prior snapshot and only events at or after `prior.eventCount` are folded — so
+ * an active session that grew by a few turns re-derives (and re-redacts) only
+ * those new tool calls instead of re-sanitizing its entire history on every
+ * daemon warm tick (PHNX-3411). The ordinals continue deterministically from the
+ * snapshot, so folding [0..k) then [k..n) yields the same index as folding
+ * [0..n) once, and the CHANGED set is safe to persist with `mode: 'append'`.
+ *
+ * The caller is responsible for only supplying `prior` when the stream is still
+ * an append of what was scanned before (same source, un-truncated,
+ * `prior.eventCount <= events.length`); anything else must full-scan.
+ */
+export function scanEventToolCalls(events, prior) {
+    const startIndex = prior ? Math.min(prior.eventCount, events.length) : 0;
+    const collector = new ToolCallCollector(prior?.snapshot);
+    for (let i = startIndex; i < events.length; i++)
+        foldEventIntoCollector(collector, events[i]);
+    return { calls: collector.drainChanged(), snapshot: collector.snapshot(), eventCount: events.length };
+}
 /** Build indexed calls from the normalized parser contract used by full-file harnesses. */
 export function toolCallsFromEvents(events) {
-    const collector = new ToolCallCollector();
-    for (const event of events) {
-        if (event.type === 'tool_use') {
-            collector.start({
-                timestamp: event.timestamp,
-                tool: event.tool || 'unknown',
-                input: event.args,
-                command: event.command,
-                sourceCallId: event.callId,
-            });
-        }
-        else if (event.type === 'tool_result') {
-            collector.finish({
-                timestamp: event.timestamp,
-                sourceCallId: event.callId,
-                tool: event.tool,
-                success: event.success,
-                outcome: event.outcome,
-                exitCode: event.exitCode,
-                statusCode: event.statusCode,
-                errorCode: event.errorCode,
-                output: event.output,
-            });
-        }
-        else if (event.type === 'error' && event.tool) {
-            const structuredError = event.outcome === 'error' || event.success === false;
-            const evidence = event.content || event.output || 'Tool execution failed';
-            collector.finish({
-                timestamp: event.timestamp,
-                sourceCallId: event.callId,
-                tool: event.tool,
-                success: structuredError ? false : undefined,
-                outcome: event.outcome,
-                exitCode: event.exitCode,
-                statusCode: event.statusCode,
-                errorCode: event.errorCode,
-                error: structuredError ? evidence : undefined,
-                output: structuredError ? undefined : evidence,
-            });
-        }
-    }
-    return collector.drainChanged();
+    return scanEventToolCalls(events).calls;
 }
 export function toolCallKey(sessionId, ordinal) {
     return createHash('sha256').update(`${sessionId}\0${ordinal}`).digest('hex').slice(0, 20);

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

@@ -1,5 +1,5 @@
 import type Database from '../sqlite.js';
-import { type IndexedToolCall } from './tool-calls.js';
+import { type IndexedToolCall, type EventToolScanResumePoint } from './tool-calls.js';
 import type { SessionMeta } from './types.js';
 export declare function canonicalToolLedgerPath(filePath: string): string;
 /** Resolve the transcript that actually carries tool events for split-file harnesses. */
@@ -12,7 +12,14 @@ export declare function purgeMissingToolCallsInDirectory(db: Database.Database,
 export interface ToolScanResumePoint {
     /** Serialized ToolCallCollector snapshot at `parsedOffset`. */
     parserState: string;
-    /** Byte offset just past the last complete record consumed. */
+    /**
+     * Where a later scan may resume. For the streaming (claude/codex) path this is
+     * a BYTE offset just past the last complete record consumed. For the full-file
+     * harness path (`planEventToolResume`) it is instead the COUNT of normalized
+     * events already folded — the two never share a session (a session is one
+     * agent, and the streaming path is claude/codex only), so the column carries
+     * whichever meaning that agent's resumer wrote.
+     */
     parsedOffset: number;
 }
 export interface PersistToolCallsOptions {
@@ -37,3 +44,27 @@ export declare function persistToolCalls(db: Database.Database, session: Session
     fileMtimeMs: number;
     fileSize: number;
 }, options?: PersistToolCallsOptions): void;
+/**
+ * Decide whether a changed full-file-harness session can RESUME its tool index
+ * from the last scan instead of re-deriving every call (PHNX-3411).
+ *
+ * The warm-tick indexer re-derives tool calls for a changed session on every
+ * tick, and for an ACTIVE large session that means re-sanitizing tens of
+ * thousands of calls each time — the synchronous work that wedged the daemon
+ * event loop. Streaming harnesses (claude/codex) already resume from a byte
+ * offset; every other harness re-parses the whole file, so this brings them the
+ * same benefit at the EVENT level: the ledger stores how many events were folded
+ * (`parsed_offset`) plus the collector snapshot (`parser_state`), and a later
+ * scan folds only the newly appended events.
+ *
+ * Returns the prior resume point when it is safe to append, or `null` (full
+ * re-scan) whenever the stored prefix may no longer describe the current file:
+ * a different extractor, no recorded resume point, a source the ledger row does
+ * not describe, a transcript that shrank below what was already parsed (a
+ * truncation/rewrite, not an append), more events already folded than the file
+ * now yields, or a snapshot that does not read back.
+ */
+export declare function planEventToolResume(db: Database.Database, sessionId: string, sourcePath: string, stamp: {
+    fileMtimeMs: number;
+    fileSize: number;
+}, currentEventCount: number): EventToolScanResumePoint | null;

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

@@ -75,13 +75,14 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
     const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
     const insertCall = db.prepare(`
     INSERT INTO tool_calls (
-      call_key, session_id, ordinal, source_call_id, timestamp, tool, input,
+      call_key, session_id, ordinal, source_call_id, timestamp, end_timestamp, tool, input,
       outcome, exit_code, status_code, error_code, output, error, parse_error
       , evidence_bytes
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(session_id, ordinal) DO UPDATE SET
       source_call_id = excluded.source_call_id,
       timestamp = excluded.timestamp,
+      end_timestamp = excluded.end_timestamp,
       tool = excluded.tool,
       input = excluded.input,
       outcome = excluded.outcome,
@@ -197,7 +198,7 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
         }
         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));
+            insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.endTimestamp ?? null, 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);
@@ -215,3 +216,55 @@ export function persistToolCalls(db, session, calls, sourceStamp, options = {})
     });
     txn();
 }
+/**
+ * Decide whether a changed full-file-harness session can RESUME its tool index
+ * from the last scan instead of re-deriving every call (PHNX-3411).
+ *
+ * The warm-tick indexer re-derives tool calls for a changed session on every
+ * tick, and for an ACTIVE large session that means re-sanitizing tens of
+ * thousands of calls each time — the synchronous work that wedged the daemon
+ * event loop. Streaming harnesses (claude/codex) already resume from a byte
+ * offset; every other harness re-parses the whole file, so this brings them the
+ * same benefit at the EVENT level: the ledger stores how many events were folded
+ * (`parsed_offset`) plus the collector snapshot (`parser_state`), and a later
+ * scan folds only the newly appended events.
+ *
+ * Returns the prior resume point when it is safe to append, or `null` (full
+ * re-scan) whenever the stored prefix may no longer describe the current file:
+ * a different extractor, no recorded resume point, a source the ledger row does
+ * not describe, a transcript that shrank below what was already parsed (a
+ * truncation/rewrite, not an append), more events already folded than the file
+ * now yields, or a snapshot that does not read back.
+ */
+export function planEventToolResume(db, sessionId, sourcePath, stamp, currentEventCount) {
+    const row = db.prepare(`
+    SELECT file_path, file_size, extractor_version, parsed_offset, parser_state
+    FROM tool_scan_ledger WHERE session_id = ?
+  `).get(sessionId);
+    if (!row)
+        return null;
+    if (row.extractor_version !== TOOL_INDEX_VERSION)
+        return null;
+    if (row.parsed_offset === null || !Number.isSafeInteger(row.parsed_offset) || row.parsed_offset < 0)
+        return null;
+    if (row.file_path !== canonicalToolLedgerPath(sourcePath))
+        return null;
+    if (stamp.fileSize < row.file_size)
+        return null;
+    // The file grew but reports fewer events than were already folded — the prefix
+    // was rewritten, not appended to. Re-scan from scratch.
+    if (row.parsed_offset > currentEventCount)
+        return null;
+    if (row.parser_state === null)
+        return null;
+    let snapshot;
+    try {
+        snapshot = JSON.parse(row.parser_state);
+    }
+    catch {
+        return null;
+    }
+    if (snapshot?.v !== 1 || !Number.isSafeInteger(snapshot.nextOrdinal))
+        return null;
+    return { snapshot, eventCount: row.parsed_offset };
+}

package/dist/lib/staleness/writers/sources.d.ts

@@ -7,6 +7,11 @@ export type EnabledExtra = {
 export declare function trustedSourceBases(): {
     dir: string;
 }[];
+/** Every `plugins/<plugin>/skills` dir across trusted source bases, filtered to an optional plugin/agent scope. */
+export declare function pluginSkillDirs(options?: {
+    agent?: AgentId;
+    plugins?: Set<string>;
+}): string[];
 /** Find the trusted source for a command markdown by name. */
 export declare function resolveCommandSource(name: string): string | null;
 /** Find the trusted source directory for a skill by name. */

package/dist/lib/staleness/writers/sources.js

@@ -54,7 +54,8 @@ function pluginSupportsAgent(manifest, agent) {
         return true;
     return !manifest.agents || manifest.agents.length === 0 || manifest.agents.includes(agent);
 }
-function pluginSkillDirs(options = {}) {
+/** Every `plugins/<plugin>/skills` dir across trusted source bases, filtered to an optional plugin/agent scope. */
+export function pluginSkillDirs(options = {}) {
     const dirs = [];
     for (const base of trustedSourceBases()) {
         const pluginsDir = path.join(base.dir, 'plugins');

package/dist/lib/sync-status.d.ts

@@ -93,6 +93,28 @@ export interface UnifiedSyncStatus {
         agentsNeedingSync: number;
     };
 }
+/**
+ * Residual drift for a single (agent, version) after a reconcile — the drifted
+ * and missing rows that a sync claimed to fix but did not. `orphan` rows are
+ * deliberately excluded: sync never removes them (that is `agents prune`'s job),
+ * so they are not "unfinished sync". Empty `drifted`+`missing` ⇒ converged.
+ */
+export interface ResidualDrift {
+    agent: AgentId;
+    version: string;
+    rows: ResourceStatusRow[];
+}
+/**
+ * Re-check that a version's home now matches its resolved sources after a
+ * reconcile. This is the post-write verification the `agents sync` success line
+ * depends on (PHNX-3186): the exit line must not read "reconciled" while drift
+ * it was asked to fix stays put. Resolves against non-project layers only
+ * (`excludeProject: true`), mirroring what the sync writer targets. Returns null
+ * when the version converged (no drifted/missing), else the residual rows.
+ */
+export declare function verifyVersionConverged(agent: AgentId, version: string, cwd?: string): ResidualDrift | null;
+/** One-line-per-resource description of residual drift, for the sync exit line. */
+export declare function formatResidualDrift(residual: ResidualDrift[]): string[];
 export interface SyncStatusOptions {
     cwd?: string;
     /** Restrict to specific agent ids; undefined = every supported agent. */

package/dist/lib/sync-status.js

@@ -27,6 +27,33 @@ import { getSystemAgentsDir, getUserAgentsDir } from './state.js';
 import * as fs from 'fs';
 import { isGitRepo, readOriginUrl } from './git.js';
 import { detectConfigDrift } from './config-drift.js';
+/**
+ * Re-check that a version's home now matches its resolved sources after a
+ * reconcile. This is the post-write verification the `agents sync` success line
+ * depends on (PHNX-3186): the exit line must not read "reconciled" while drift
+ * it was asked to fix stays put. Resolves against non-project layers only
+ * (`excludeProject: true`), mirroring what the sync writer targets. Returns null
+ * when the version converged (no drifted/missing), else the residual rows.
+ */
+export function verifyVersionConverged(agent, version, cwd = process.cwd()) {
+    const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
+    const rows = rowsFromReport(agent, version, report)
+        .filter((r) => r.status === 'drifted' || r.status === 'missing');
+    if (rows.length === 0)
+        return null;
+    return { agent, version, rows };
+}
+/** One-line-per-resource description of residual drift, for the sync exit line. */
+export function formatResidualDrift(residual) {
+    const lines = [];
+    for (const r of residual) {
+        for (const row of r.rows) {
+            const detail = row.detail ? ` (${row.detail})` : '';
+            lines.push(`${r.agent}@${r.version}: ${row.status} ${row.kind} '${row.name}'${detail}`);
+        }
+    }
+    return lines;
+}
 const STATUS_MAP = {
     ok: 'synced',
     diff: 'drifted',

package/dist/lib/sync-umbrella.d.ts

@@ -64,6 +64,15 @@ export interface UmbrellaResult {
      * Empty when nothing was declined — never conflated with "nothing to do".
      */
     declined: string[];
+    /**
+     * The (agent, version) pairs the reconcile stage actually wrote into — the set
+     * the caller re-verifies for residual drift so the `✓ sync: reconciled` line is
+     * never printed while drift it was asked to fix stays put (PHNX-3186).
+     */
+    reconciledVersions: Array<{
+        agent: string;
+        version: string;
+    }>;
 }
 export interface RunUmbrellaArgs {
     flags: UmbrellaFlags;

package/dist/lib/sync-umbrella.js

@@ -15,7 +15,7 @@
  *               arrives with `agents secrets vault unlock`, #366/#367)
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
-import { pullRepo } from './git.js';
+import { pullRepo, adoptUserRepoIfNeeded } from './git.js';
 import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets/sync.js';
 import { SYNC_PASSPHRASE_ENV } from './secrets/sync-passphrase.js';
@@ -55,7 +55,7 @@ export function planUmbrellaStages(f) {
 export async function runUmbrellaSync(args) {
     const { flags, log, yes, passphrase, quiet = false } = args;
     const plan = planUmbrellaStages(flags);
-    const result = { plan, reconciled: false, declined: [] };
+    const result = { plan, reconciled: false, declined: [], reconciledVersions: [] };
     if (plan.fetchRepos) {
         const dirs = [
             { alias: 'user', dir: getUserAgentsDir() },
@@ -64,6 +64,24 @@ export async function runUmbrellaSync(args) {
         let pulled = 0;
         const errors = [];
         for (const { alias, dir } of dirs) {
+            // A box where `~/.agents` is present but not a git repo (or lost its
+            // `.git`) is a partial install: `pullRepo` there silently fails while the
+            // umbrella still reported `✓ reconciled`, so fleet dotfiles/resources never
+            // propagated and nothing said so (PHNX-3239, m0). Adopt it in place first —
+            // the same self-heal `agents sync user` runs (PHNX-3301) — so the pull has a
+            // real repo to fast-forward. A box that cannot be adopted (no recorded
+            // remote) fails LOUD into `errors` with the reason, never a silent no-op.
+            if (alias === 'user') {
+                const adopted = await adoptUserRepoIfNeeded(dir);
+                if (adopted && !adopted.success) {
+                    const hint = adopted.needsUrl ? ' — git-back it: agents repo pull user <git-url>' : '';
+                    errors.push(`${alias}: ${adopted.error}${hint}`);
+                    continue;
+                }
+                if (adopted?.success) {
+                    log(`repos: ${alias} adopted in place → ${adopted.commit} (${adopted.materialized} file(s) materialized)`);
+                }
+            }
             const r = await pullRepo(dir);
             if (r.success) {
                 pulled++;
@@ -116,6 +134,7 @@ export async function runUmbrellaSync(args) {
         const refreshed = await refresh({ skipPrompts: yes, quiet });
         result.reconciled = true;
         result.declined = refreshed.declined;
+        result.reconciledVersions = refreshed.reconciled;
         // Keep already-registered devices' reachability current, and surface newly
         // appeared tailnet nodes as "pending" for the menu-bar Register/Ignore gate
         // rather than silently adding them (refresh mode). Soft: a machine without

package/dist/lib/traces/insights.d.ts

@@ -12,14 +12,21 @@
  * is enough to reconstruct per-session call order and inter-call gaps without a
  * full `SessionTrajectory` — that is what makes this incremental at scale.
  *
- * Scope note: `FailureSignature` does not yet carry a `phenotype`
- * (false-termination / out-of-order / …, `phenotype.ts`) — classifying that
- * needs the full derived trajectory (turns, ordered steps, gaps), which is
- * only ever materialized per-session during upload, not cached the way
- * `InsightFacets` is. Folding it in is a real, scoped follow-up (see
- * `cli/AGENTS.md`), not a silent omission.
+ * Failure phenotype (false-termination / out-of-order / premature-completion /
+ * failure-to-act, `phenotype.ts`) is folded in as a fourth grouping dimension
+ * (PHNX-3327). Classifying it needs the full derived trajectory, so it is NOT
+ * computed here — the caller passes a per-session `phenotypes` map that
+ * `buildIndexShard` fills from the persisted, mtime+size-keyed
+ * `session_phenotypes` cache for the WHOLE corpus. Keying the group on the
+ * cached-per-session phenotype (never on this run's incremental batch) is what
+ * keeps two identically-signatured sessions in one cluster regardless of when
+ * each was synced. The `signature` OUTPUT is unchanged (`{ tool, cause, key }`);
+ * phenotype is an added dimension carried alongside it, so callers that never
+ * pass a map (the unit tests, a pre-phenotype caller) see the exact prior
+ * grouping.
  */
 import { type TraceFailureCause } from './classify.js';
+import type { FailurePhenotype } from './phenotype.js';
 import { type LatencyInsight } from './segments.js';
 import { type SyncRow, type ToolCallRow, type TracesIndexShard } from './sync.js';
 export interface FailureSignature {
@@ -29,10 +36,17 @@ export interface FailureSignature {
     key: string;
 }
 export interface FailurePattern {
-    /** Stable hash of the signature — deep-linkable, unaffected by row order. */
+    /** Stable hash of the signature (incl. phenotype) — deep-linkable, unaffected by row order. */
     id: string;
     label: string;
     signature: FailureSignature;
+    /**
+     * Dominant failure phenotype of the sessions in this cluster, or `null` when
+     * none was classifiable. A fourth grouping dimension (PHNX-3327): two failures
+     * with the same `(tool, cause, key)` but different phenotypes are distinct
+     * patterns.
+     */
+    phenotype: FailurePhenotype | null;
     /** Distinct sessions this pattern occurred in. */
     sessions: number;
     /** Total failing calls matching this signature. */
@@ -57,11 +71,30 @@ export declare function normalizeErrorKey(desc: string, raw: string | null): str
  * Cluster failed tool calls into ranked patterns and estimate the wasted time
  * behind each, plus device-wide time-to-first-tool latency.
  *
- * wastedMs attribution: the gap between a failed call and the NEXT call in the
- * same session counts as wasted when either (a) the next call repeats the same
- * signature (a retry loop) or (b) the gap itself is a stall (≥60s) — an idle
- * gap unrelated to a nearby failure is never counted. This is an estimate, not
- * ground truth (a stall could be legitimate user think-time); it is not
- * inflated by folding in ordinary processing time between unrelated calls.
+ * wastedMs attribution has two parts that sum:
+ *
+ * (1) The failed call's OWN blocking duration — `end_timestamp - timestamp`
+ * (PHNX-3437). A call that hung for minutes and then failed wasted that whole
+ * time even if it was the last call in its session or was followed quickly by an
+ * unrelated call — the case the gap heuristic alone booked as ~0. This is what
+ * makes a fail-fast fix measurable: a channel that stops hanging 5.5min on stdin
+ * and instead fails in <1s (PHNX-3407) drops from ~5.5min of attributed waste to
+ * ~0. Bounded by MAX_GAP_ATTRIBUTION_MS so a corrupt end timestamp can't dominate.
+ *
+ * (2) The idle gap AFTER the call, before the NEXT call in the same session,
+ * counted when either (a) the next call repeats the same signature (a retry
+ * loop) or (b) the gap is a stall (≥60s) before an unrelated next call — each
+ * bounded by MAX_GAP_ATTRIBUTION_MS so one failure can't absorb hours of
+ * human-away idle in an async channel session, whether as a lone stall or a
+ * same-signature re-ask hours later; a genuine active retry loop is many short
+ * gaps that each clear the cap and still sum large. When the end timestamp is
+ * known, this gap is measured from the call's END, so the blocking time counted
+ * in (1) is never double-counted; for a NULL end (rows an older extractor stored,
+ * or a call still pending at scan end) it falls back to the original
+ * gap-from-START heuristic unchanged — no crash, no NaN, no regression.
+ *
+ * An idle gap unrelated to a nearby failure is never counted. This is an
+ * estimate, not ground truth; it is not inflated by folding in ordinary
+ * processing time between unrelated calls.
  */
-export declare function computeInsights(rows: readonly SyncRow[], calls: readonly ToolCallRow[], prevShard?: TracesIndexShard | null): ComputedInsights;
+export declare function computeInsights(rows: readonly SyncRow[], calls: readonly ToolCallRow[], prevShard?: TracesIndexShard | null, phenotypes?: ReadonlyMap<string, FailurePhenotype | null>): ComputedInsights;