@phnx-labs/agents-cli 1.22.57 → 1.22.58

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,

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

@@ -35,13 +35,33 @@ export interface OutcomeResult {
     confidence: 'high' | 'medium' | 'low';
     reason: string;
 }
+/**
+ * Did a run that hit tool errors nonetheless *recover and finish*?
+ *
+ * The causal recovery test: a **substantive** tool step (not a human-facing
+ * `AskUserQuestion` / `SendMessage` / `wait`) SUCCEEDED strictly AFTER the last
+ * error's ordinal, AND that success resolves the failed work — its
+ * {@link workSignature} matches an errored step's. A later success of *unrelated*
+ * work does NOT count: a `bun test` failure followed by an incidental `ls` leaves
+ * the failed test unresolved, so the run stays errored, even though the `ls`
+ * succeeded after it. A punt to a human is excluded twice over — human-facing
+ * tools are outside the substantive set, and they never match a failed signature.
+ *
+ * This is the single source of truth for "did this finish", shared by the
+ * false-termination phenotype below and `sync.ts`'s `deriveRunOutcome` — so a
+ * run's console outcome and its failure phenotype can never disagree about
+ * whether it recovered. It reads only the derived steps, never `meta.outcome`,
+ * precisely so `deriveRunOutcome` can call it while it is still *computing*
+ * `meta.outcome`.
+ */
+export declare function recoveredAfterErrors(session: Pick<SessionDetail, 'steps'>): boolean;
 /**
  * Classify the failure phenotype of a session from its derived trajectory.
  *
  * Definitions (from agent-failure research):
- * - `false-termination`  — stopped with an unresolved error.
- * - `premature-completion` — declared done while tests were failing or no
- *   verification step ran for the engineering work.
+ * - `false-termination`  — stopped with an unresolved error (did not causally recover).
+ * - `premature-completion` — declared done with no verification step for the
+ *   engineering work.
  * - `out-of-order` — a write/edit step occurred before any read/plan of the
  *   target.
  * - `failure-to-act` — stalled or produced no meaningful tool use.

package/dist/lib/traces/phenotype.js

@@ -156,30 +156,75 @@ function reasonOutOfOrder(session) {
     const tool = session.steps.find((s) => WRITE_EDIT_TOOLS.has(s.tool ?? s.lane));
     return `write/edit step ${tool?.tool ?? tool?.lane ?? ''} preceded any read/plan`;
 }
+/**
+ * The **work signature** of a step — what work it represents, so a later success
+ * can be matched back to the specific failure it resolves. For a shell step this
+ * is the effective program (`bun`, `git`, `gh`, …, from `TrajectoryStep.program`),
+ * so a failed `bun test` is resolved by a later `bun test` but NOT by an incidental
+ * `ls`. For any other tool it is the tool identity, so a failed `Edit` is resolved
+ * by a later successful `Edit`, not by an unrelated `Read`. A shell step whose
+ * command did not parse (no `program`) degrades to the bare tool name, matching
+ * the pre-`program` behavior only for that unparseable minority.
+ */
+function workSignature(step) {
+    const tool = step.tool ?? step.lane;
+    if (SHELL_TOOLS.has(tool) && step.program)
+        return `${tool}:${step.program}`;
+    return tool;
+}
+/**
+ * Did a run that hit tool errors nonetheless *recover and finish*?
+ *
+ * The causal recovery test: a **substantive** tool step (not a human-facing
+ * `AskUserQuestion` / `SendMessage` / `wait`) SUCCEEDED strictly AFTER the last
+ * error's ordinal, AND that success resolves the failed work — its
+ * {@link workSignature} matches an errored step's. A later success of *unrelated*
+ * work does NOT count: a `bun test` failure followed by an incidental `ls` leaves
+ * the failed test unresolved, so the run stays errored, even though the `ls`
+ * succeeded after it. A punt to a human is excluded twice over — human-facing
+ * tools are outside the substantive set, and they never match a failed signature.
+ *
+ * This is the single source of truth for "did this finish", shared by the
+ * false-termination phenotype below and `sync.ts`'s `deriveRunOutcome` — so a
+ * run's console outcome and its failure phenotype can never disagree about
+ * whether it recovered. It reads only the derived steps, never `meta.outcome`,
+ * precisely so `deriveRunOutcome` can call it while it is still *computing*
+ * `meta.outcome`.
+ */
+export function recoveredAfterErrors(session) {
+    const substantive = substantiveSteps(session);
+    if (substantive.length === 0)
+        return false;
+    const last = substantive[substantive.length - 1];
+    if (last.outcome === 'error')
+        return false;
+    const lastErrorOrdinal = lastStepOrdinalOf(session, (s) => s.outcome === 'error');
+    if (lastErrorOrdinal === undefined)
+        return true;
+    const failedSignatures = new Set();
+    for (const s of session.steps) {
+        if (s.outcome === 'error')
+            failedSignatures.add(workSignature(s));
+    }
+    return substantive.some((s) => s.ordinal > lastErrorOrdinal &&
+        s.outcome === 'ok' &&
+        !HUMAN_FACING_TOOLS.has(s.tool ?? s.lane) &&
+        failedSignatures.has(workSignature(s)));
+}
 /**
  * False-termination: the session stopped with an unresolved error.
  *
  * Rubric:
  * - meta outcome is `errored`, and
  * - at least one step outcome is `error`, and
- * - the last non-thinking step is an error or is followed by no successful recovery.
+ * - the run did not causally recover ({@link recoveredAfterErrors}).
  */
 function isFalseTermination(session) {
     if (session.meta.outcome !== 'errored')
         return false;
     if (session.meta.errorCount === 0)
         return false;
-    const substantive = substantiveSteps(session);
-    if (substantive.length === 0)
-        return true;
-    const last = substantive[substantive.length - 1];
-    if (last.outcome === 'error')
-        return true;
-    const lastErrorOrdinal = lastStepOrdinalOf(session, (s) => s.outcome === 'error');
-    if (lastErrorOrdinal === undefined)
-        return false;
-    const recoveryAfter = substantive.some((s) => s.ordinal > lastErrorOrdinal && s.outcome === 'ok' && !HUMAN_FACING_TOOLS.has(s.tool ?? s.lane));
-    return !recoveryAfter;
+    return !recoveredAfterErrors(session);
 }
 function reasonFalseTermination(session) {
     const substantive = substantiveSteps(session);
@@ -192,13 +237,21 @@ function reasonFalseTermination(session) {
     return 'errored with no successful recovery after the last error';
 }
 /**
- * Premature-completion: declared done while tests were failing or no verification
- * step ran for an engineering task.
+ * Premature-completion: declared done without a verification step for an
+ * engineering task.
  *
  * Rubric:
  * - meta outcome is `completed`, and
  * - the session performed write/edit work, and
- * - either errors were present or no test/build/lint verification step ran.
+ * - no test/build/lint verification step ran.
+ *
+ * `errorCount` is deliberately NOT a signal here. Under truthful outcomes
+ * (PHNX-3387) a `completed` run CAN carry `errorCount > 0` — that is precisely a
+ * recover-then-succeed run, where the errors were *resolved*, not left hanging.
+ * Keying prematurity off `errorCount > 0` would mislabel every such recovery as
+ * premature. (Under the pre-PHNX-3387 `errorCount > 0 ? errored : completed`
+ * derivation this branch was unreachable — a `completed` run always had
+ * `errorCount === 0` — so dropping it changes nothing for a clean-completed run.)
  */
 function isPrematureCompletion(session) {
     if (session.meta.outcome !== 'completed')
@@ -206,8 +259,6 @@ function isPrematureCompletion(session) {
     const didWriteEdit = session.steps.some((s) => WRITE_EDIT_TOOLS.has(s.tool ?? s.lane));
     if (!didWriteEdit)
         return false;
-    if (session.meta.errorCount > 0)
-        return true;
     const verified = session.steps.some((s) => {
         if (!SHELL_TOOLS.has(s.tool ?? s.lane))
             return false;
@@ -216,10 +267,7 @@ function isPrematureCompletion(session) {
     });
     return !verified;
 }
-function reasonPrematureCompletion(session) {
-    if (session.meta.errorCount > 0) {
-        return `declared completed with ${session.meta.errorCount} unresolved error(s)`;
-    }
+function reasonPrematureCompletion(_session) {
     return 'engineering work completed without a test/build/lint verification step';
 }
 /** Ordered rubric: the first matching phenotype wins. */
@@ -391,9 +439,9 @@ const OUTCOME_RULES = [
  * Classify the failure phenotype of a session from its derived trajectory.
  *
  * Definitions (from agent-failure research):
- * - `false-termination`  — stopped with an unresolved error.
- * - `premature-completion` — declared done while tests were failing or no
- *   verification step ran for the engineering work.
+ * - `false-termination`  — stopped with an unresolved error (did not causally recover).
+ * - `premature-completion` — declared done with no verification step for the
+ *   engineering work.
  * - `out-of-order` — a write/edit step occurred before any read/plan of the
  *   target.
  * - `failure-to-act` — stalled or produced no meaningful tool use.

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

@@ -49,6 +49,14 @@ export interface SyncResult {
     parseFailed: number;
     /** Parsed fine but the upload PUT failed (network/5xx) — retried on the next sync. */
     uploadFailed: number;
+    /**
+     * The index shard build or upload failed. Undefined on success. The per-session
+     * data still uploaded (that loop runs first), but the aggregated console shard —
+     * stats, needs-attention, failure clusters, latency — was NOT refreshed, so the
+     * console keeps serving the last good index. Surfaced (not swallowed) so a stale
+     * console is diagnosable instead of looking like a clean sync. See PHNX-3401.
+     */
+    indexError?: string;
 }
 /** Push derived, redacted trajectories for this device to the traces store. */
 export declare function syncTraces(opts?: SyncOpts): Promise<SyncResult>;
@@ -106,6 +114,13 @@ export interface ToolCallRow {
     session_id: string;
     ordinal: number;
     timestamp: string;
+    /**
+     * When the call's result arrived — its own end time (PHNX-3437). Optional
+     * because rows an older extractor stored, and calls that never produced a
+     * result, carry NULL; `computeInsights` falls back to the bounded inter-call
+     * gap when it is absent.
+     */
+    end_timestamp?: string | null;
     tool: string;
     outcome: string;
     exit_code: number | null;

package/dist/lib/traces/sync.js

@@ -22,7 +22,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { getDB, readSessionInsights, readSessionTopics, writeSessionInsights, writeSessionTopics, } from '../session/db.js';
+import { getDB, readSessionInsights, readSessionPhenotypes, readSessionTopics, writeSessionInsights, writeSessionPhenotypes, writeSessionTopics, } from '../session/db.js';
 import { parseSession } from '../session/parse.js';
 import { buildTrajectory } from '../session/trajectory.js';
 import { computeInsightFacets } from '../session/insights.js';
@@ -31,6 +31,7 @@ import { getRuntimeStateDir } from '../state.js';
 import { resolveTracesBackend } from './backend.js';
 import { classifyCause, classifyTopic, computeDriftSignal, } from './classify.js';
 import { computeInsights } from './insights.js';
+import { classifyPhenotype, recoveredAfterErrors } from './phenotype.js';
 /** Push derived, redacted trajectories for this device to the traces store. */
 export async function syncTraces(opts = {}) {
     const dryRun = opts.dryRun === true;
@@ -147,6 +148,7 @@ export async function syncTraces(opts = {}) {
             recordFailure(row, 'upload-failed', err);
         }
     }
+    let indexError;
     if (!opts.skipIndex) {
         try {
             const allRows = db
@@ -172,8 +174,13 @@ export async function syncTraces(opts = {}) {
                 await putIndexShard(backend, device, owner, shard);
             }
         }
-        catch {
-            // index PUT/write failure is not fatal — the per-session data is already written
+        catch (err) {
+            // Not fatal to the per-session upload (that loop already ran), but it DOES
+            // mean the console shard is now stale. Record it so the caller can surface a
+            // warning instead of reporting a clean, green sync — a silent swallow here is
+            // exactly what let a 59h-stale, insight-less index hide in plain sight
+            // (PHNX-3401). Do NOT re-throw: the session data is durable and worth keeping.
+            indexError = err instanceof Error ? err.message : String(err);
         }
     }
     // A dry-run never advances the incremental watermark: it is a read-only export.
@@ -203,6 +210,7 @@ export async function syncTraces(opts = {}) {
         transcriptUnavailable,
         parseFailed,
         uploadFailed,
+        indexError,
     };
 }
 function percentile(values, ratio) {
@@ -247,6 +255,32 @@ function attentionFlags(errorCount, facets) {
         flags.push(`${correctionCount} correction${correctionCount === 1 ? '' : 's'}`);
     return flags;
 }
+/**
+ * Persist a derived-cache warm-up (topics / insights) without letting a
+ * contended DB take down the whole index build.
+ *
+ * These write-backs only speed up the NEXT sync — the shard about to be built
+ * reads from the in-memory `topics` / `insights` maps that were already
+ * populated above, never from what this write persists. So the write is
+ * genuinely optional to the shard's correctness.
+ *
+ * Yet it was the single point that broke the console: on an active machine the
+ * Rush app holds `sessions.db`, this `BEGIN IMMEDIATE` waits out the 30s
+ * `busy_timeout` and throws `SQLITE_BUSY`, the throw escaped `buildIndexShard`,
+ * and `syncTraces` swallowed it — so the index (with wasted-time / failure
+ * clusters / latency) never re-uploaded and the dashboard sat 59h stale
+ * (PHNX-3401). Isolating the failure here keeps the index building; the warning
+ * makes the degraded cache visible instead of silent.
+ */
+function persistDerivedCache(label, write) {
+    try {
+        write();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`traces: ${label} cache warm-up skipped (${msg}) — index still built`);
+    }
+}
 /** Build the redacted rich console shard from indexed metadata and derived caches. */
 export function buildIndexShard(rows, device, owner, prevShard) {
     const db = getDB();
@@ -256,7 +290,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
     for (let i = 0; i < ids.length; i += 400) {
         const chunk = ids.slice(i, i + 400);
         calls.push(...db.prepare(`
-      SELECT session_id, ordinal, timestamp, tool, outcome, exit_code, status_code, error_code, error, parse_error
+      SELECT session_id, ordinal, timestamp, end_timestamp, tool, outcome, exit_code, status_code, error_code, error, parse_error
       FROM tool_calls
       WHERE session_id IN (${chunk.map(() => '?').join(',')})
     `).all(...chunk));
@@ -283,26 +317,52 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         topics.set(row.id, topic);
         return { id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, topic };
     });
-    writeSessionTopics(missingTopics);
+    persistDerivedCache('session-topics', () => writeSessionTopics(missingTopics));
+    // Insights (frictionSignals) and phenotype (false-termination / …) both need
+    // the parsed transcript, which flat tool_calls rows don't carry — so both are
+    // lazily derived per-session and cached by transcript mtime+size, then read for
+    // the WHOLE corpus (`rows` = allRows) every sync. That full-corpus read is what
+    // keeps the phenotype grouping dimension consistent: a session synced weeks ago
+    // still contributes its real phenotype from cache, so it can never fragment away
+    // from an identically-signatured session synced this run purely by *when* each
+    // was first seen (PHNX-3327). A cache-miss row is parsed at most once here even
+    // when both derivations are missing.
     const insights = readSessionInsights(ids);
+    const phenotypes = readSessionPhenotypes(ids);
     const missingInsights = [];
-    for (const row of rows.filter((candidate) => !insights.has(candidate.id))) {
+    const missingPhenotypes = [];
+    for (const row of rows) {
+        const needInsights = !insights.has(row.id);
+        const needPhenotype = !phenotypes.has(row.id);
+        if (!needInsights && !needPhenotype)
+            continue;
+        let events;
         try {
-            const events = parseSession(row.file_path, row.agent);
-            const facets = computeInsightFacets(events);
-            insights.set(row.id, facets);
-            missingInsights.push({
-                id: row.id,
-                fileMtimeMs: row.file_mtime_ms,
-                fileSize: row.file_size,
-                facets,
-            });
+            events = parseSession(row.file_path, row.agent);
         }
         catch {
-            continue;
+            continue; // gone/unreadable transcript — leave both uncached, same as before
+        }
+        if (needInsights) {
+            try {
+                const facets = computeInsightFacets(events);
+                insights.set(row.id, facets);
+                missingInsights.push({ id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, facets });
+            }
+            catch { /* leave this session's facets uncached; recompute next sync */ }
+        }
+        if (needPhenotype) {
+            try {
+                const traj = buildTrajectory(events, rowToMeta(row), { redact: true, knownSecrets });
+                const phenotype = classifyPhenotype(buildSessionDetail(traj));
+                phenotypes.set(row.id, phenotype);
+                missingPhenotypes.push({ id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, phenotype });
+            }
+            catch { /* leave this session's phenotype uncached; recompute next sync */ }
         }
     }
-    writeSessionInsights(missingInsights);
+    persistDerivedCache('session-insights', () => writeSessionInsights(missingInsights));
+    persistDerivedCache('session-phenotypes', () => writeSessionPhenotypes(missingPhenotypes));
     const needsAttention = rows.flatMap((row) => {
         const facets = insights.get(row.id);
         const errorCount = errorCounts.get(row.id) ?? 0;
@@ -361,7 +421,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
     const prevHistory = prevShard?.bucketHistory ?? [];
     const bucketHistory = [...prevHistory, todayStats].slice(-14);
     const driftSignals = computeDriftSignal(prevHistory, todayStats);
-    const patternInsights = computeInsights(rows, calls, prevShard);
+    const patternInsights = computeInsights(rows, calls, prevShard, phenotypes);
     return {
         schema: 1,
         device,
@@ -404,6 +464,31 @@ function buildWhereItWentWrong(traj) {
         return null;
     return `This run hit ${parts.join('; ')}.`;
 }
+/**
+ * Truthful run-level outcome (PHNX-3387).
+ *
+ * A run with zero tool errors `completed`. A run that hit tool errors is
+ * `completed` ONLY when it *causally recovered* — a substantive, non-human-facing
+ * tool step succeeded strictly after the last error AND resolved the failed work
+ * (its work signature matches an errored step's), the exact predicate the
+ * false-termination phenotype uses ({@link recoveredAfterErrors}). A run whose
+ * last substantive step is the error, whose only post-error steps are human-facing
+ * (a punt to `AskUserQuestion` — the case the broken "last tool call ok" heuristic
+ * mislabeled `completed`), or whose only post-error success is unrelated work (a
+ * failed `bun test` followed by an incidental `ls`) stays `errored`.
+ *
+ * This is what makes `surfacedToolFailures` on a `completed` run honest: those
+ * are failures the run recovered from, not a green status hiding an unresolved
+ * failure. It never flips a run that ended unresolved to `completed` (no
+ * regression vs the old `errorCount > 0 ? errored : completed`), and it does not
+ * flip a run whose failed work was never resolved just because some later,
+ * unrelated call happened to succeed.
+ */
+function deriveRunOutcome(traj) {
+    if (traj.errorCount === 0)
+        return 'completed';
+    return recoveredAfterErrors({ steps: traj.steps }) ? 'completed' : 'errored';
+}
 /**
  * Map the derived trajectory to the console's SessionDetail shape, stripping
  * local-machine PII (full cwd, account) that would expose filesystem paths if
@@ -423,7 +508,7 @@ export function buildSessionDetail(traj) {
             errorCount: traj.errorCount,
             tokens: stats.outputTokens ?? 0,
             costUsd: s.costUsd ?? 0,
-            outcome: traj.errorCount > 0 ? 'errored' : 'completed',
+            outcome: deriveRunOutcome(traj),
             repo,
             agent: s.agent,
             model: s.model ?? 'unknown',