@phnx-labs/agents-cli 1.22.56 → 1.22.58

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/startup/command-registry.d.ts

@@ -26,7 +26,8 @@ export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
  * (linear-cli) (RUSH-2932). `alias` moved under `agents setup alias` (RUSH-2965).
  * `inbox` was a pure alias of `agents feed` (RUSH-2984). `unshare` nested under
  * `agents artifacts unshare` (RUSH-2989). `audit` nested under `agents events audit`.
- * `trends` nested under `agents insights mix` / `insights trends`. `serve` (the
+ * `trends` was removed with the insights recipe collapse — the one counter
+ * surface is `agents insights mix` (PHNX-3391). `serve` (the
  * read-only local web companion + `--control` anchor) was removed with the
  * unshipped iOS Fleet Cockpit it existed for (RUSH-3001). `apply` nested under
  * `agents fleet apply` / `agents devices apply`. `beta` nested under
@@ -34,7 +35,12 @@ export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
  * removed; `agents auth` returned against Phoenix ID with `auth space` as the
  * team surface (RUSH-2581). `usage` was removed as a duplicate surface of
  * `agents view`, which renders per-account usage with account, version, and
- * auth state beside it (RUSH-3079).
+ * auth state beside it (RUSH-3079). `perf` nested under `agents insights perf`
+ * — performance metrics are an insight, not a top-level noun (PHNX-3391).
+ * `list` was removed — it was a long-deprecated full duplicate of `agents view`
+ * (it already printed "agents list is now agents view"); `agents view` is the
+ * one version-listing surface (PHNX-3391). The `agents trash restore` subcommand
+ * was likewise removed as an exact duplicate of top-level `agents restore`.
  */
 export declare const RETIRED_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 export declare function isKnownTopLevelCommand(name: string): boolean;

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

@@ -1,11 +1,11 @@
 const LOADED_COMMAND_NAMES = [
     'accounts', 'auth', 'view', 'inspect', 'feedback', 'commands', 'hooks', 'skills', 'rules', 'memory',
-    'permissions', 'mcp', 'clis', 'subagents', 'plugins', 'workflows', 'add', 'use', 'list',
+    'permissions', 'mcp', 'clis', 'subagents', 'plugins', 'workflows', 'add', 'use',
     'remove', 'rm', 'purge', 'update', 'prune', 'import', 'registry', 'search', 'install',
     'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
     'route', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
-    'refresh-rules', 'factory', 'insights', 'trace', 'perf',
+    'refresh-rules', 'factory', 'insights', 'trace',
     'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',
@@ -46,7 +46,8 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
  * (linear-cli) (RUSH-2932). `alias` moved under `agents setup alias` (RUSH-2965).
  * `inbox` was a pure alias of `agents feed` (RUSH-2984). `unshare` nested under
  * `agents artifacts unshare` (RUSH-2989). `audit` nested under `agents events audit`.
- * `trends` nested under `agents insights mix` / `insights trends`. `serve` (the
+ * `trends` was removed with the insights recipe collapse — the one counter
+ * surface is `agents insights mix` (PHNX-3391). `serve` (the
  * read-only local web companion + `--control` anchor) was removed with the
  * unshipped iOS Fleet Cockpit it existed for (RUSH-3001). `apply` nested under
  * `agents fleet apply` / `agents devices apply`. `beta` nested under
@@ -54,7 +55,12 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
  * removed; `agents auth` returned against Phoenix ID with `auth space` as the
  * team surface (RUSH-2581). `usage` was removed as a duplicate surface of
  * `agents view`, which renders per-account usage with account, version, and
- * auth state beside it (RUSH-3079).
+ * auth state beside it (RUSH-3079). `perf` nested under `agents insights perf`
+ * — performance metrics are an insight, not a top-level noun (PHNX-3391).
+ * `list` was removed — it was a long-deprecated full duplicate of `agents view`
+ * (it already printed "agents list is now agents view"); `agents view` is the
+ * one version-listing surface (PHNX-3391). The `agents trash restore` subcommand
+ * was likewise removed as an exact duplicate of top-level `agents restore`.
  */
 export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'webhook',
@@ -85,6 +91,8 @@ export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'trends',
     'apply',
     'beta',
+    'perf',
+    'list',
 ]);
 export function isKnownTopLevelCommand(name) {
     return KNOWN_TOP_LEVEL_COMMANDS.has(name);

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;

package/dist/lib/traces/insights.js

@@ -12,12 +12,18 @@
  * 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 { classifyCause } from './classify.js';
 import { computeLatency } from './segments.js';
@@ -30,6 +36,24 @@ const TOP_K_PATTERNS = 25;
 const MAX_EXAMPLE_SESSIONS = 5;
 /** A gap this long right after a failure reads as an idle stall, not think-time (matches sync.ts's own "stalled Xm" threshold). */
 const STALL_MS = 60_000;
+/**
+ * Upper bound on how much of a SINGLE inter-call gap is attributable to a
+ * failure. Beyond a recovery window a gap is not failure-loop waste — it is a
+ * human away from a chat thread, an abandoned session, or an outage. This bounds
+ * BOTH branches, and that matters: `nextIsSameFailure` only compares
+ * `(tool, cause, normalized-key)`, with no temporal check, so a deterministic
+ * failure that recurs identically hours apart (a permanently-denied capability,
+ * a missing credential — e.g. a Slack user re-asking "where am I" at 2pm and
+ * 6pm) would otherwise look like an "active retry loop" and absorb the whole
+ * multi-hour gap — the very artifact this fix targets. A genuine active loop has
+ * MANY short gaps that each stay under this cap and still sum to a large total,
+ * so bounding a single gap doesn't hide it. Real single-tool stalls (a hung
+ * typecheck, a slow build) are minutes and stay fully counted.
+ *
+ * The same cap bounds the call's OWN blocking duration (PHNX-3437) so a corrupt
+ * or backwards end timestamp can't book a single call as hours of waste either.
+ */
+const MAX_GAP_ATTRIBUTION_MS = 30 * 60_000;
 // ---------------------------------------------------------------------------
 // Signature normalization — fold volatile per-instance text together
 // ---------------------------------------------------------------------------
@@ -48,8 +72,8 @@ export function normalizeErrorKey(desc, raw) {
     }
     return text.replace(/\s+/g, ' ').trim().slice(0, 160);
 }
-function hashSignature(tool, cause, key) {
-    const input = `${tool} ${cause} ${key}`;
+function hashSignature(tool, cause, key, phenotype) {
+    const input = `${tool} ${cause} ${key} ${phenotype ?? ''}`;
     let hash = 5381;
     for (let i = 0; i < input.length; i++) {
         hash = ((hash << 5) + hash + input.charCodeAt(i)) >>> 0;
@@ -82,14 +106,33 @@ function labelFor(tool, cause, key) {
  * 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 function computeInsights(rows, calls, prevShard) {
+export function computeInsights(rows, calls, prevShard, phenotypes) {
     const bySession = new Map();
     for (const call of calls) {
         const list = bySession.get(call.session_id);
@@ -100,6 +143,11 @@ export function computeInsights(rows, calls, prevShard) {
     }
     const groups = new Map();
     for (const [sessionId, sessionCalls] of bySession) {
+        // Phenotype is a per-session property (one classification per session), so
+        // every failing call in this session shares it. A caller that passes no map
+        // (unit tests, a pre-phenotype caller) collapses the dimension to `null`,
+        // yielding the exact prior grouping.
+        const phenotype = phenotypes?.get(sessionId) ?? null;
         const ordered = [...sessionCalls].sort((a, b) => a.ordinal - b.ordinal);
         for (let i = 0; i < ordered.length; i++) {
             const call = ordered[i];
@@ -107,10 +155,10 @@ export function computeInsights(rows, calls, prevShard) {
                 continue;
             const cause = classifyCause(call);
             const key = normalizeErrorKey(failureDescription(call, cause), call.error);
-            const groupKey = `${call.tool} ${cause} ${key}`;
+            const groupKey = `${call.tool} ${cause} ${key} ${phenotype ?? ''}`;
             let group = groups.get(groupKey);
             if (!group) {
-                group = { tool: call.tool, cause, key, sessions: new Set(), occurrences: 0, wastedMs: 0, examples: [] };
+                group = { tool: call.tool, cause, key, phenotype, sessions: new Set(), occurrences: 0, wastedMs: 0, examples: [] };
                 groups.set(groupKey, group);
             }
             group.occurrences++;
@@ -118,24 +166,46 @@ export function computeInsights(rows, calls, prevShard) {
             if (group.examples.length < MAX_EXAMPLE_SESSIONS && !group.examples.includes(sessionId)) {
                 group.examples.push(sessionId);
             }
+            // (1) The call's OWN blocking duration (end minus start) is the primary
+            // signal — see the computeInsights docblock. Attributed whenever the end
+            // timestamp is present, independent of whether a next call follows.
+            const startMs = Date.parse(call.timestamp);
+            const endMs = call.end_timestamp ? Date.parse(call.end_timestamp) : NaN;
+            const hasEnd = Number.isFinite(endMs) && Number.isFinite(startMs);
+            if (hasEnd) {
+                const ownMs = endMs - startMs;
+                if (ownMs > 0)
+                    group.wastedMs += Math.min(ownMs, MAX_GAP_ATTRIBUTION_MS);
+            }
+            // (2) The idle gap after the call, before the next one. Measured from the
+            // call's END when known (so the blocking time in (1) isn't double-counted),
+            // else from its START — the original heuristic, unchanged for NULL ends.
             const next = ordered[i + 1];
             if (!next)
                 continue;
-            const gapMs = Date.parse(next.timestamp) - Date.parse(call.timestamp);
+            const gapFromMs = hasEnd ? endMs : startMs;
+            const gapMs = Date.parse(next.timestamp) - gapFromMs;
             if (!Number.isFinite(gapMs) || gapMs <= 0)
                 continue;
             const nextIsSameFailure = next.outcome === 'error' &&
                 next.tool === call.tool &&
                 classifyCause(next) === cause &&
                 normalizeErrorKey(failureDescription(next, cause), next.error) === key;
-            if (nextIsSameFailure || gapMs >= STALL_MS) {
-                group.wastedMs += gapMs;
+            if (nextIsSameFailure) {
+                // Retry loop: a real active loop is many short gaps, each under the cap,
+                // summing to a large total. Bound a single gap so one huge same-signature
+                // gap (a re-ask hours later, not active retrying) can't absorb it all.
+                group.wastedMs += Math.min(gapMs, MAX_GAP_ATTRIBUTION_MS);
+            }
+            else if (gapMs >= STALL_MS) {
+                // Lone stall before an unrelated next call: same bounded recovery window.
+                group.wastedMs += Math.min(gapMs, MAX_GAP_ATTRIBUTION_MS);
             }
         }
     }
     const prevById = new Map((prevShard?.failurePatterns ?? []).map((p) => [p.id, p]));
     const allPatterns = [...groups.values()].map((group) => {
-        const id = hashSignature(group.tool, group.cause, group.key);
+        const id = hashSignature(group.tool, group.cause, group.key, group.phenotype);
         const prev = prevById.get(id);
         const drift = !prev
             ? 'up'
@@ -148,6 +218,7 @@ export function computeInsights(rows, calls, prevShard) {
             id,
             label: labelFor(group.tool, group.cause, group.key),
             signature: { tool: group.tool, cause: group.cause, key: group.key },
+            phenotype: group.phenotype,
             sessions: group.sessions.size,
             occurrences: group.occurrences,
             wastedMs: group.wastedMs,