@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,28 +1,8 @@
-/**
- * TracesBackend — token-source seam for `agents traces sync`.
- *
- * Managed path: signed in to Phoenix (`readSession() != null`), no BYO
- * override. Token is the Phoenix access_token; endpoint is the live
- * `traces.agents-cli.sh` Worker. Zero Cloudflare setup.
- *
- * BYO path (future): TRACES_BASE_URL + TRACES_WRITE_TOKEN env vars. Not
- * exposed in the CLI for M1 — follow-on milestone.
- */
 export declare const DEFAULT_TRACES_DOMAIN = "traces.agents-cli.sh";
 export interface TracesBackend {
-    /** Public base URL of the traces Worker, no trailing slash. */
     baseUrl: string;
-    /** Bearer sent as `Authorization`. Phoenix access_token. */
     token: string;
-    /** Phoenix userId — the R2 namespace prefix. */
     userId: string;
 }
-/**
- * Resolve the backend for the current machine. Throws when not signed in.
- *
- * BYO override env vars (for testing / self-hosted):
- *   AGENTS_TRACES_BASE_URL — Worker URL, no trailing slash
- *   AGENTS_TRACES_WRITE_TOKEN — static write token (bypasses Phoenix auth)
- */
 export declare function resolveTracesBackend(): TracesBackend;
 export declare function managedTracesBaseUrl(): string;

package/dist/lib/traces/backend.js

@@ -1,41 +1,18 @@
-/**
- * TracesBackend — token-source seam for `agents traces sync`.
- *
- * Managed path: signed in to Phoenix (`readSession() != null`), no BYO
- * override. Token is the Phoenix access_token; endpoint is the live
- * `traces.agents-cli.sh` Worker. Zero Cloudflare setup.
- *
- * BYO path (future): TRACES_BASE_URL + TRACES_WRITE_TOKEN env vars. Not
- * exposed in the CLI for M1 — follow-on milestone.
- */
 import { readSession } from '../identity/client.js';
 import { selectStorageBackendKind } from '../storage/selection.js';
 export const DEFAULT_TRACES_DOMAIN = 'traces.agents-cli.sh';
-/**
- * Resolve the backend for the current machine. Throws when not signed in.
- *
- * BYO override env vars (for testing / self-hosted):
- *   AGENTS_TRACES_BASE_URL — Worker URL, no trailing slash
- *   AGENTS_TRACES_WRITE_TOKEN — static write token (bypasses Phoenix auth)
- */
 export function resolveTracesBackend() {
     const envBase = (process.env['AGENTS_TRACES_BASE_URL'] ?? '').replace(/\/+$/, '').trim();
     const envToken = (process.env['AGENTS_TRACES_WRITE_TOKEN'] ?? '').trim();
-    // The traces surface's only BYO signal is the full BASE_URL + WRITE_TOKEN env
-    // pair; the managed-vs-BYO decision itself is the shared selection policy.
     const byoOverride = Boolean(envBase && envToken);
     if (selectStorageBackendKind({ byoOverride }) === 'byo') {
         if (byoOverride) {
             return { baseUrl: envBase, token: envToken, userId: 'byo' };
         }
-        // Not signed in and no BYO env pair — the managed principal is the only one
-        // this surface exposes, so fail loud with the login hint.
         throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
     }
     const session = readSession();
     if (!session) {
-        // selectStorageBackendKind read the same session and returned 'managed', so a
-        // null here means it was cleared between the two reads — treat as signed out.
         throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
     }
     if (!session.access_token) {

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

@@ -1,28 +1,15 @@
 export type TraceTopicGroup = 'code' | 'research' | 'review' | 'content' | 'ops';
-/**
- * `real`/`guard`/`hook` are the cause buckets of a FAILED tool call (`classifyCause`).
- * `behavioral` is different in kind: a silent failure with no error code at all — the
- * agent went idle after its last event and a human had to nudge it. It is derived from
- * per-session friction facets (`computeBehavioralPatterns` in `insights.ts`), never from
- * `classifyCause`, so a failed-tool-call classifier never returns it.
- */
 export type TraceFailureCause = 'real' | 'guard' | 'hook' | 'behavioral';
-/** Per-bucket aggregate stats for one day, stored in the rolling bucketHistory. */
 export interface BucketStats {
     key: string;
     date: string;
     count: number;
-    /** Tool-error count / total tool calls in this session set (0–1). */
     errorRate: number;
-    /** Sessions with ≥1 stall friction signal / total sessions in bucket (0–1). */
     stallRate: number;
 }
-/** Movement signal for one topic bucket compared to its 7-day rolling average. */
 export interface DriftSignal {
     bucket: string;
-    /** current errorRate − 7d average (positive = degrading). */
     errorDelta: number;
-    /** current stallRate − 7d average (positive = degrading). */
     stallDelta: number;
     severity: 'degrading' | 'stable' | 'improving';
 }
@@ -47,14 +34,7 @@ interface ToolCallFailure {
     parse_error?: string | null;
     outcome?: string | null;
 }
-/** Classify a session from metadata and aggregate tool names; never reads transcript text. */
 export declare function classifyTopic(input: TopicEvidence): ClassifiedTopic;
-/** Bucket a failed tool call without inspecting raw tool input or transcript text. */
 export declare function classifyCause(call: ToolCallFailure): TraceFailureCause;
-/**
- * Compare today's per-bucket stats to the last 7 days of history and return
- * movement signals. Buckets with fewer than 3 historical days are skipped —
- * not enough signal to distinguish noise from drift.
- */
 export declare function computeDriftSignal(history: BucketStats[][], today: BucketStats[]): DriftSignal[];
 export {};

package/dist/lib/traces/classify.js

@@ -24,7 +24,6 @@ const TOPIC_RULES = [
     { group: 'code', key: 'feature', label: 'Feature work',
         text: /\b(feat|feature|implement|add|build|code|test)\b/, tool: /edit|write|apply_patch|exec|bash|shell/ },
 ];
-/** Classify a session from metadata and aggregate tool names; never reads transcript text. */
 export function classifyTopic(input) {
     const text = normalizedEvidence(input);
     const tools = Object.keys(input.toolMix ?? {}).map((tool) => tool.toLowerCase());
@@ -35,7 +34,6 @@ export function classifyTopic(input) {
     }
     return { group: 'research', key: 'general', label: 'General' };
 }
-/** Bucket a failed tool call without inspecting raw tool input or transcript text. */
 export function classifyCause(call) {
     const evidence = [call.error_code, call.error, call.parse_error]
         .filter((value) => typeof value === 'string')
@@ -49,11 +47,6 @@ export function classifyCause(call) {
     return 'real';
 }
 const DRIFT_THRESHOLD = 0.20;
-/**
- * Compare today's per-bucket stats to the last 7 days of history and return
- * movement signals. Buckets with fewer than 3 historical days are skipped —
- * not enough signal to distinguish noise from drift.
- */
 export function computeDriftSignal(history, today) {
     const signals = [];
     for (const stat of today) {

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

@@ -1,113 +1,30 @@
-/**
- * Cross-session failure clustering + time-wasted attribution for the traces
- * insight engine (PHNX-3141) — the piece that turns per-tool error counts
- * into "here is your #1 systemic problem and what it cost."
- *
- * Pure and SQL-shaped: it consumes the same `SyncRow[]` + `tool_calls` rows
- * `buildIndexShard` already loads (no re-parsing of transcripts), so cost
- * stays proportional to this sync's row count, never the full corpus.
- *
- * `tool_calls` rows carry `ordinal`/`timestamp` per call within a session
- * (`db.ts`'s `idx_tool_calls_session ON tool_calls(session_id, ordinal)`), which
- * is enough to reconstruct per-session call order and inter-call gaps without a
- * full `SessionTrajectory` — that is what makes this incremental at scale.
- *
- * 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';
-import type { InsightFacets } from '../session/insights.js';
+import type { InsightFacets } from '@phnx-labs/sessions-cli/reader';
 export interface FailureSignature {
     tool: string;
     cause: TraceFailureCause;
-    /** Normalized error text — volatile tokens (ids, counts, countdowns) stripped so instances fold together. */
     key: string;
 }
 export interface FailurePattern {
-    /** 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. */
     occurrences: number;
-    /** Estimated ms of retry/stall time attributable to this pattern (see attribution rule below). */
     wastedMs: number;
-    /** Bounded example session ids for drill-down. */
     exampleSessionIds: string[];
-    /** Movement vs the same pattern id in the previous shard. */
     drift: 'up' | 'flat' | 'down';
 }
 interface ComputedInsights {
-    /** Top-K patterns ranked by wastedMs (impact) — a rare 1-occurrence/8h loop still surfaces. */
     failurePatterns: FailurePattern[];
-    /** Sum of wastedMs across every cluster found this sync, not just the top-K rows above. */
     wastedMsTotal: number;
     latency: LatencyInsight;
 }
-/** Strip volatile tokens from a failure's evidence text so repeat instances hash identically. */
 export declare function normalizeErrorKey(desc: string, raw: string | null): string;
-/**
- * Cluster failed tool calls into ranked patterns and estimate the wasted time
- * behind each, plus device-wide time-to-first-tool latency.
- *
- * 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, phenotypes?: ReadonlyMap<string, FailurePhenotype | null>, behavioralPatterns?: readonly FailurePattern[]): ComputedInsights;
-/**
- * Promote the per-session silent-stall friction signals — already computed by
- * `computeInsightFacets` in `session/insights.ts` and keyed `silent stall: <bucket>`
- * — into cross-session behavioral `FailurePattern`s. These are silent failures
- * with NO error code: the agent went idle after its last event and a human had to
- * nudge it. They never surface through `computeInsights` (which only clusters
- * `outcome === 'error'` tool calls) and were previously only a `needsAttention`
- * friction counter, never a ranked issue. Cause is `behavioral`; the signature
- * `tool` is the synthetic `silent-stall` and `key` is the duration bucket.
- */
 export declare function computeBehavioralPatterns(facetsBySession: ReadonlyMap<string, Pick<InsightFacets, 'frictionSignals'>>, prevShard?: TracesIndexShard | null): FailurePattern[];
 export {};

package/dist/lib/traces/insights.js

@@ -1,62 +1,10 @@
-/**
- * Cross-session failure clustering + time-wasted attribution for the traces
- * insight engine (PHNX-3141) — the piece that turns per-tool error counts
- * into "here is your #1 systemic problem and what it cost."
- *
- * Pure and SQL-shaped: it consumes the same `SyncRow[]` + `tool_calls` rows
- * `buildIndexShard` already loads (no re-parsing of transcripts), so cost
- * stays proportional to this sync's row count, never the full corpus.
- *
- * `tool_calls` rows carry `ordinal`/`timestamp` per call within a session
- * (`db.ts`'s `idx_tool_calls_session ON tool_calls(session_id, ordinal)`), which
- * is enough to reconstruct per-session call order and inter-call gaps without a
- * full `SessionTrajectory` — that is what makes this incremental at scale.
- *
- * 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';
 import { failureDescription } from './sync.js';
-// ---------------------------------------------------------------------------
-// Tunables
-// ---------------------------------------------------------------------------
-/** Bounded shard size — patterns, not sessions, so 738 or 738k render identically. */
 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
-// ---------------------------------------------------------------------------
 const VOLATILE_TOKEN_PATTERNS = [
     { pattern: /\bfor user [\w.-]+/gi, replacement: 'for user _' },
     { pattern: /\btry again in [\w.]+s?\b/gi, replacement: 'try again in _s' },
@@ -64,7 +12,6 @@ const VOLATILE_TOKEN_PATTERNS = [
     { pattern: /\b[\w.-]+@[\w.-]+\.\w+\b/gi, replacement: '_email_' },
     { pattern: /\b\d+\b/g, replacement: '_n_' },
 ];
-/** Strip volatile tokens from a failure's evidence text so repeat instances hash identically. */
 export function normalizeErrorKey(desc, raw) {
     let text = (raw && raw.trim().length > 0 ? raw : desc).toLowerCase();
     for (const { pattern, replacement } of VOLATILE_TOKEN_PATTERNS) {
@@ -80,9 +27,6 @@ function hashSignature(tool, cause, key, phenotype) {
     }
     return hash.toString(16).padStart(8, '0');
 }
-// ---------------------------------------------------------------------------
-// Label rules — a table, not an if/else-by-name chain (matches segments.ts's TASK_TYPE_RULES)
-// ---------------------------------------------------------------------------
 const LABEL_RULES = [
     { pattern: /rate limit/i, label: 'rate limit back-off loop' },
     { pattern: /permission denied/i, label: 'permission denied' },
@@ -99,39 +43,6 @@ function labelFor(tool, cause, key) {
     const rule = LABEL_RULES.find((row) => row.pattern.test(key));
     return `${tool}: ${rule ? rule.label : key.slice(0, 48)}`;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Cluster failed tool calls into ranked patterns and estimate the wasted time
- * behind each, plus device-wide time-to-first-tool latency.
- *
- * 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, phenotypes, behavioralPatterns = []) {
     const bySession = new Map();
     for (const call of calls) {
@@ -143,10 +54,6 @@ export function computeInsights(rows, calls, prevShard, phenotypes, behavioralPa
     }
     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++) {
@@ -166,9 +73,6 @@ export function computeInsights(rows, calls, prevShard, phenotypes, behavioralPa
             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);
@@ -177,9 +81,6 @@ export function computeInsights(rows, calls, prevShard, phenotypes, behavioralPa
                 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;
@@ -192,13 +93,9 @@ export function computeInsights(rows, calls, prevShard, phenotypes, behavioralPa
                 classifyCause(next) === cause &&
                 normalizeErrorKey(failureDescription(next, cause), next.error) === key;
             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);
             }
         }
@@ -226,9 +123,6 @@ export function computeInsights(rows, calls, prevShard, phenotypes, behavioralPa
             drift,
         };
     });
-    // Behavioral patterns (silent stalls — no failed tool call, so absent from the
-    // error-anchored clustering above) join the SAME ranking and total, so the top-K
-    // is by impact across both kinds and `wastedMsTotal` counts the idle time too.
     const combined = [...allPatterns, ...behavioralPatterns];
     const wastedMsTotal = combined.reduce((sum, p) => sum + p.wastedMs, 0);
     const failurePatterns = [...combined]
@@ -237,30 +131,11 @@ export function computeInsights(rows, calls, prevShard, phenotypes, behavioralPa
     const latency = computeLatency(firstToolSegments(rows, bySession));
     return { failurePatterns, wastedMsTotal, latency };
 }
-// ---------------------------------------------------------------------------
-// Behavioral patterns — silent failures with no error code
-// ---------------------------------------------------------------------------
-/**
- * Estimated agent-owned idle ms per silent-stall bucket. A bucket's midpoint,
- * capped at MAX_GAP_ATTRIBUTION_MS exactly like the tool-error gap attribution
- * above so one long overnight stall can't book hours of "waste" — the same
- * honesty bound the error path uses. The open-ended buckets are the cap.
- */
 const SILENT_STALL_WASTED_MS = {
     '5-15m': 10 * 60_000,
     '15-60m': MAX_GAP_ATTRIBUTION_MS,
     '1h+': MAX_GAP_ATTRIBUTION_MS,
 };
-/**
- * Promote the per-session silent-stall friction signals — already computed by
- * `computeInsightFacets` in `session/insights.ts` and keyed `silent stall: <bucket>`
- * — into cross-session behavioral `FailurePattern`s. These are silent failures
- * with NO error code: the agent went idle after its last event and a human had to
- * nudge it. They never surface through `computeInsights` (which only clusters
- * `outcome === 'error'` tool calls) and were previously only a `needsAttention`
- * friction counter, never a ranked issue. Cause is `behavioral`; the signature
- * `tool` is the synthetic `silent-stall` and `key` is the duration bucket.
- */
 export function computeBehavioralPatterns(facetsBySession, prevShard) {
     const groups = new Map();
     for (const [sessionId, facets] of facetsBySession) {
@@ -308,7 +183,6 @@ export function computeBehavioralPatterns(facetsBySession, prevShard) {
         };
     });
 }
-/** Synthesize one-step SegmentSessions carrying only the time-to-first-tool offset, for computeLatency() reuse. */
 function firstToolSegments(rows, bySession) {
     return rows.flatMap((row) => {
         const sessionCalls = bySession.get(row.id);

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

@@ -1,30 +1,5 @@
-/**
- * Failure phenotype classifier + outcome taxonomy for the traces insight engine.
- *
- * Both functions are pure: they take a redacted {@link SessionDetail} (the same
- * shape the traces sync writes to `sessions/<id>.json`) and return a decision
- * derived only from the already-derived step/gap/meta signal. They never read
- * raw transcript text and never fabricate a signal that is not in the data.
- *
- * The rubrics are expressed as data-driven tables of conditions, not as
- * if/else-by-name chains. Each table row is a named phenotype/outcome with a
- * declarative predicate; the classifier walks the table in priority order and
- * returns the first match, or the honest lower-confidence default when no
- * high-confidence signal is present.
- */
 import type { SessionDetail } from './sync.js';
-/** A failure mode detectable from the derived trajectory of a session. */
 export type FailurePhenotype = 'false-termination' | 'premature-completion' | 'out-of-order' | 'failure-to-act';
-/**
- * The coarse outcome of a session's work.
- *
- * - `merged`       : explicit PR/branch merge signal in the steps (high confidence).
- * - `tests-green`  : explicit test command returned ok with no later failure (high confidence).
- * - `partial`      : progress was made but no landing/test signal is present (low confidence default).
- * - `abandoned`    : errored, stalled, and unresolved.
- * - `human-takeover`: the final substantive action was a human-facing ask/wait.
- * - `invalid-env`  : environment/setup failures dominated the session.
- */
 type TraceOutcome = 'merged' | 'tests-green' | 'partial' | 'abandoned' | 'human-takeover' | 'invalid-env';
 interface PhenotypeResult {
     phenotype: FailurePhenotype | null;
@@ -35,53 +10,9 @@ 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 (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.
- *
- * Returns `null` when none of the failure phenotypes apply.
- */
 export declare function classifyPhenotype(session: SessionDetail): FailurePhenotype | null;
-/** Detailed phenotype result with a human-readable reason. */
 export declare function classifyPhenotypeDetailed(session: SessionDetail): PhenotypeResult;
-/**
- * Derive the coarse outcome of a session from its end state + tool signals.
- *
- * `merged` and `tests-green` are high-confidence only when an explicit signal
- * is present in the derived steps. When that signal is genuinely not in the
- * data, the function returns the honest lower-confidence value (`partial` for
- * completed work without a landing signal, `abandoned` for errored/unresolved
- * work, `invalid-env` for setup-dominant failures, `human-takeover` when the
- * session ends on a human-facing ask).
- */
 export declare function deriveOutcome(session: SessionDetail): TraceOutcome;
-/** Detailed outcome result with confidence and a human-readable reason. */
 export declare function deriveOutcomeDetailed(session: SessionDetail): OutcomeResult;
 export type { SessionDetail } from './sync.js';