@phnx-labs/agents-cli 1.22.57 → 1.22.59

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

@@ -48,6 +48,16 @@ export interface PlacementOptions {
     /** Human label of the requested agent (e.g. `claude@2.1.112`) for the
      * fail-loud message. */
     agentLabel?: string;
+    /**
+     * Normalized hosts boosted with `auto-launch.preferred` (set by
+     * `agents devices prefer <name>`). A preferred device ranks ahead of a
+     * non-preferred one among the eligible survivors — after the signed-in tier
+     * (a preferred box that can't run the agent is still no use) and before load,
+     * so an operator boost overrides load-based ordering without overriding hard
+     * health. Empty/undefined leaves the ranking unchanged. See
+     * {@link autoLaunchPreferredSet}.
+     */
+    preferred?: ReadonlySet<string>;
 }
 /** Why a device was excluded from the viable set, for the fail-loud message. */
 export type ExclusionReason = 'unreachable' | 'overloaded' | 'capped' | 'not-installed';

package/dist/lib/teams/scheduler.js

@@ -266,6 +266,14 @@ export function pickBestDevice(devices, roster, opts) {
         const signedIn = (sa?.signedIn === true ? 0 : 1) - (sb?.signedIn === true ? 0 : 1);
         if (signedIn !== 0)
             return signedIn;
+        // (a2) operator-preferred device next — `agents devices prefer <name>`
+        // boosts a box above its load-equal peers, overriding load-based order.
+        const preferred = opts?.preferred;
+        if (preferred && preferred.size > 0) {
+            const pref = (preferred.has(a) ? 0 : 1) - (preferred.has(b) ? 0 : 1);
+            if (pref !== 0)
+                return pref;
+        }
         // (b) lower load — coarse headroom tier, then raw load cost.
         const tier = headroomTier(sa?.headroom) - headroomTier(sb?.headroom);
         if (tier !== 0)

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,

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.