@llm-dev-ops/agentics-cli 2.5.4 → 2.6.0

package/dist/errors/transient.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ADR-PIPELINE-089 §1 — Centralized transient-failure classification.
+ *
+ * The retry loops in `executeNaturalLanguageRoute` (src/commands/agents.ts)
+ * used to inline a substring allowlist over `Error.message`:
+ *
+ *   const isRetryable = msg.includes('unavailable')
+ *     || msg.includes('timeout')
+ *     || msg.includes('rate exceeded')
+ *     || msg.includes('econnreset')
+ *     || msg.includes('econnrefused')
+ *     || msg.includes('network error')
+ *     || msg.includes('aborterror');
+ *
+ * Three problems with that shape:
+ *
+ * 1. `unreachable` is NOT on the list. Several adapter paths surface that
+ *    word when a Cloud Run backend is down, and the retry loop then bails
+ *    on attempt 1 — the exact field-report symptom on 2026-04-22.
+ * 2. It only looks at `.message`. Node/undici errors often carry the
+ *    transient signal on `.code` (ECONNRESET, ETIMEDOUT) or on a wrapped
+ *    HTTP `response.status` (503, 504). Both were invisible to the
+ *    substring check.
+ * 3. 400-class terminal failures (contract_violation, unauthorized) never
+ *    had an explicit short-circuit. A future drift that made their message
+ *    match a retryable substring would silently retry three times.
+ *
+ * This module exposes:
+ *   - isTransientFailure(err) — returns true when a retry has a reasonable
+ *     chance of succeeding (widened allowlist + code + status + cause-chain).
+ *   - isTerminalFailure(err) — returns true when retrying cannot help
+ *     (payload / auth / canonical-not-found). Takes precedence over
+ *     isTransientFailure when both match.
+ *
+ * Used by: the simulation retry loops at src/commands/agents.ts:4154 and
+ * :4505. Future sites should import and reuse the helper instead of
+ * re-inlining a substring list.
+ */
+/**
+ * True when the failure shape suggests a retry has a reasonable chance of
+ * succeeding: network resets, timeouts, 5xx, rate limits, cold-starts.
+ *
+ * Takes precedence over isTerminalFailure when inspecting a wrapped error:
+ * callers should test `isTerminalFailure(e)` first and short-circuit if true.
+ */
+export declare function isTransientFailure(err: unknown): boolean;
+/**
+ * True when retrying cannot help: bad payload, bad credentials, canonical
+ * 404. Callers should short-circuit their retry loop on true.
+ */
+export declare function isTerminalFailure(err: unknown): boolean;
+/**
+ * Best-effort classification used by the Phase 1 Health Gate when deciding
+ * whether a simulator-level failure should produce a `failed` vs `degraded`
+ * verdict.
+ *
+ *   - 'transient' → the retry loop gave up but the error was retryable;
+ *     environment-flake. Still counts as a failure for verdict purposes
+ *     (we already retried) but tags the degradation so the user knows a
+ *     re-run is likely to succeed.
+ *   - 'terminal'  → payload/credentials/canonical. Actionable by user.
+ *   - 'unknown'   → neither signature matched. Treat as terminal for
+ *     verdict purposes (do not recommend a re-run) but surface the raw
+ *     message so the user can see what happened.
+ */
+export declare function classifyFailure(err: unknown): 'transient' | 'terminal' | 'unknown';
+//# sourceMappingURL=transient.d.ts.map

package/dist/errors/transient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient.d.ts","sourceRoot":"","sources":["../../src/errors/transient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA0JH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAiCxD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAoBvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAIlF"}

package/dist/errors/transient.js

@@ -0,0 +1,260 @@
+/**
+ * ADR-PIPELINE-089 §1 — Centralized transient-failure classification.
+ *
+ * The retry loops in `executeNaturalLanguageRoute` (src/commands/agents.ts)
+ * used to inline a substring allowlist over `Error.message`:
+ *
+ *   const isRetryable = msg.includes('unavailable')
+ *     || msg.includes('timeout')
+ *     || msg.includes('rate exceeded')
+ *     || msg.includes('econnreset')
+ *     || msg.includes('econnrefused')
+ *     || msg.includes('network error')
+ *     || msg.includes('aborterror');
+ *
+ * Three problems with that shape:
+ *
+ * 1. `unreachable` is NOT on the list. Several adapter paths surface that
+ *    word when a Cloud Run backend is down, and the retry loop then bails
+ *    on attempt 1 — the exact field-report symptom on 2026-04-22.
+ * 2. It only looks at `.message`. Node/undici errors often carry the
+ *    transient signal on `.code` (ECONNRESET, ETIMEDOUT) or on a wrapped
+ *    HTTP `response.status` (503, 504). Both were invisible to the
+ *    substring check.
+ * 3. 400-class terminal failures (contract_violation, unauthorized) never
+ *    had an explicit short-circuit. A future drift that made their message
+ *    match a retryable substring would silently retry three times.
+ *
+ * This module exposes:
+ *   - isTransientFailure(err) — returns true when a retry has a reasonable
+ *     chance of succeeding (widened allowlist + code + status + cause-chain).
+ *   - isTerminalFailure(err) — returns true when retrying cannot help
+ *     (payload / auth / canonical-not-found). Takes precedence over
+ *     isTransientFailure when both match.
+ *
+ * Used by: the simulation retry loops at src/commands/agents.ts:4154 and
+ * :4505. Future sites should import and reuse the helper instead of
+ * re-inlining a substring list.
+ */
+// ============================================================================
+// Keyword sets — lowercase compares on error.message
+// ============================================================================
+const TRANSIENT_MESSAGE_KEYWORDS = [
+    'unavailable',
+    'service_unavailable',
+    'unreachable',
+    'timeout',
+    'timed out',
+    'etimedout',
+    'rate exceeded',
+    'rate limit',
+    'too many requests',
+    'econnreset',
+    'connection reset',
+    'econnrefused',
+    'connection refused',
+    'enotfound',
+    'eai_again',
+    'network error',
+    'aborterror',
+    'socket hang up',
+    'und_err_socket',
+    'upstream connect error',
+    'upstream request timeout',
+];
+const TERMINAL_MESSAGE_KEYWORDS = [
+    'contract_violation',
+    'contract violation',
+    'invalid_payload',
+    'bad request',
+    'malformed',
+    'unauthorized',
+    'forbidden',
+    'invalid api key',
+    'invalid credentials',
+    'payload_too_large',
+    'payload too large',
+];
+// ============================================================================
+// Error codes — exact match on error.code (typically Node/undici/fetch)
+// ============================================================================
+const TRANSIENT_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'ESOCKETTIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EPIPE',
+    'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'AbortError',
+]);
+// ============================================================================
+// HTTP statuses — exact match on error.status or error.response.status
+// ============================================================================
+const TRANSIENT_HTTP_STATUSES = new Set([
+    408, // Request Timeout
+    425, // Too Early
+    429, // Too Many Requests (retry-after)
+    500, // Internal Server Error (often transient in Cloud Run)
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504, // Gateway Timeout
+    522, // Cloudflare connection timeout
+    524, // Cloudflare a timeout occurred
+]);
+const TERMINAL_HTTP_STATUSES = new Set([
+    400, // Bad Request
+    401, // Unauthorized
+    403, // Forbidden
+    404, // Not Found (ambiguous — only terminal when path canonical; callers that know otherwise can override)
+    405, // Method Not Allowed
+    409, // Conflict
+    410, // Gone
+    413, // Payload Too Large
+    422, // Unprocessable Entity
+]);
+// ============================================================================
+// Unwrapping helpers
+// ============================================================================
+const MAX_CAUSE_DEPTH = 3;
+function extractStatus(err) {
+    if (typeof err.status === 'number')
+        return err.status;
+    if (typeof err.statusCode === 'number')
+        return err.statusCode;
+    const resp = err.response;
+    if (resp && typeof resp === 'object') {
+        if (typeof resp.status === 'number')
+            return resp.status;
+        if (typeof resp.statusCode === 'number')
+            return resp.statusCode;
+    }
+    // Parse "HTTP 503", "status 504", "504 Gateway Timeout" out of message
+    if (typeof err.message === 'string') {
+        const m = err.message.match(/\b(?:HTTP\s*)?(\d{3})\b/);
+        if (m) {
+            const n = Number(m[1]);
+            if (n >= 400 && n < 600)
+                return n;
+        }
+    }
+    return undefined;
+}
+function extractCode(err) {
+    if (typeof err.code === 'string')
+        return err.code;
+    return undefined;
+}
+function extractMessage(err) {
+    if (typeof err.message === 'string')
+        return err.message.toLowerCase();
+    return '';
+}
+/** Walk the `.cause` chain up to MAX_CAUSE_DEPTH levels, flattening fields into an array. */
+function unwrapChain(err) {
+    const chain = [];
+    let cur = err;
+    for (let i = 0; i <= MAX_CAUSE_DEPTH && cur; i++) {
+        if (cur && typeof cur === 'object') {
+            chain.push(cur);
+            cur = cur.cause;
+        }
+        else {
+            break;
+        }
+    }
+    return chain;
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * True when the failure shape suggests a retry has a reasonable chance of
+ * succeeding: network resets, timeouts, 5xx, rate limits, cold-starts.
+ *
+ * Takes precedence over isTerminalFailure when inspecting a wrapped error:
+ * callers should test `isTerminalFailure(e)` first and short-circuit if true.
+ */
+export function isTransientFailure(err) {
+    if (err == null)
+        return false;
+    // Raw string errors: substring match only.
+    if (typeof err === 'string') {
+        const lower = err.toLowerCase();
+        return TRANSIENT_MESSAGE_KEYWORDS.some(k => lower.includes(k));
+    }
+    if (typeof err !== 'object')
+        return false;
+    const chain = unwrapChain(err);
+    for (const link of chain) {
+        // HTTP status — strongest signal.
+        const status = extractStatus(link);
+        if (status !== undefined) {
+            if (TRANSIENT_HTTP_STATUSES.has(status))
+                return true;
+            // If the status is in the terminal set, the caller should have
+            // already short-circuited via isTerminalFailure. We do NOT return
+            // false here because a wrapper may carry a transient signal elsewhere
+            // in the chain (e.g. ETIMEDOUT wrapped as HTTP 500).
+        }
+        // Error code — Node/undici/fetch.
+        const code = extractCode(link);
+        if (code && TRANSIENT_ERROR_CODES.has(code))
+            return true;
+        // Message substring — widened keyword set.
+        const msg = extractMessage(link);
+        if (msg && TRANSIENT_MESSAGE_KEYWORDS.some(k => msg.includes(k)))
+            return true;
+    }
+    return false;
+}
+/**
+ * True when retrying cannot help: bad payload, bad credentials, canonical
+ * 404. Callers should short-circuit their retry loop on true.
+ */
+export function isTerminalFailure(err) {
+    if (err == null)
+        return false;
+    if (typeof err === 'string') {
+        const lower = err.toLowerCase();
+        return TERMINAL_MESSAGE_KEYWORDS.some(k => lower.includes(k));
+    }
+    if (typeof err !== 'object')
+        return false;
+    const chain = unwrapChain(err);
+    for (const link of chain) {
+        const status = extractStatus(link);
+        if (status !== undefined && TERMINAL_HTTP_STATUSES.has(status))
+            return true;
+        const msg = extractMessage(link);
+        if (msg && TERMINAL_MESSAGE_KEYWORDS.some(k => msg.includes(k)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Best-effort classification used by the Phase 1 Health Gate when deciding
+ * whether a simulator-level failure should produce a `failed` vs `degraded`
+ * verdict.
+ *
+ *   - 'transient' → the retry loop gave up but the error was retryable;
+ *     environment-flake. Still counts as a failure for verdict purposes
+ *     (we already retried) but tags the degradation so the user knows a
+ *     re-run is likely to succeed.
+ *   - 'terminal'  → payload/credentials/canonical. Actionable by user.
+ *   - 'unknown'   → neither signature matched. Treat as terminal for
+ *     verdict purposes (do not recommend a re-run) but surface the raw
+ *     message so the user can see what happened.
+ */
+export function classifyFailure(err) {
+    if (isTerminalFailure(err))
+        return 'terminal';
+    if (isTransientFailure(err))
+        return 'transient';
+    return 'unknown';
+}
+//# sourceMappingURL=transient.js.map

package/dist/errors/transient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient.js","sourceRoot":"","sources":["../../src/errors/transient.ts"],"names":[],"mappings":"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"}

package/dist/observability/degradations.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ADR-PIPELINE-089 §2 — Trace-scoped degradation sink.
+ *
+ * The Phase 1 Health Gate needs to know which degradations occurred during
+ * a run in order to classify the verdict as `healthy | degraded | failed`.
+ * Degradation signals come from multiple modules that do not share a call
+ * stack: the agent dispatcher (local-compute fallbacks), the consensus
+ * validator (`[pipeline-017]`), the pre-render pass (`[pipeline-072]`),
+ * and the LLM synthesis tag-survival check (`[exec-docs]`).
+ *
+ * Rather than thread a collector through every signature, this module
+ * exposes a process-local Map keyed by the correlation/trace id. Each
+ * emission site makes a one-line call:
+ *
+ *   recordDegradation(traceId, { code: 'local-fallback',
+ *                                 message: 'costops/attribution using local compute',
+ *                                 source: 'agents-dispatcher' });
+ *
+ * The verdict compute step at the end of `executeNaturalLanguageRoute`
+ * calls `drainDegradations(traceId)` to collect all entries and clear the
+ * bucket. Clearing is important so subsequent runs in the same process
+ * (tests, long-lived daemons) do not leak state.
+ *
+ * This is intentionally NOT a general-purpose telemetry channel. It
+ * captures pipeline-health-relevant signals only. High-volume logs keep
+ * going to stderr as before.
+ */
+export interface Degradation {
+    /** Short stable identifier. Used by UIs and tests to key off the failure class. */
+    code: DegradationCode;
+    /** Human-readable one-liner. Shown in the Phase 1 banner verbatim. */
+    message: string;
+    /** Which phase emitted the signal. `1` covers everything inside Phase 1. */
+    phase?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Optional module/domain that produced the signal — diagnosis aid. */
+    source?: string;
+}
+export type DegradationCode = 'local-fallback' | 'agent-error' | 'agent-preflight-unhealthy' | 'consensus-low' | 'sector-unknown' | 'tag-survival-failed' | 'artifact-missing' | 'simulator-transient' | 'simulator-terminal' | 'synthesis-unavailable';
+/**
+ * Record a degradation against a trace. Safe to call with an empty trace
+ * id — the call silently no-ops rather than binding to a shared ''
+ * bucket that would cross-contaminate runs.
+ */
+export declare function recordDegradation(traceId: string | undefined, d: Degradation): void;
+/**
+ * Return all degradations recorded against `traceId` (in insertion order)
+ * and clear the bucket. Returns an empty array if the trace has no entries.
+ */
+export declare function drainDegradations(traceId: string | undefined): Degradation[];
+/**
+ * Non-destructive read — for tests and for cases where the caller wants to
+ * inspect the bucket without draining (e.g. a post-phase snapshot without
+ * clearing state that later phases will add to).
+ */
+export declare function peekDegradations(traceId: string | undefined): readonly Degradation[];
+/** Test helper — clears ALL trace buckets. Do not use in production paths. */
+export declare function __resetDegradationsForTests(): void;
+//# sourceMappingURL=degradations.d.ts.map

package/dist/observability/degradations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradations.d.ts","sourceRoot":"","sources":["../../src/observability/degradations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,IAAI,EAAE,eAAe,CAAC;IACtB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,aAAa,GACb,2BAA2B,GAC3B,eAAe,GACf,gBAAgB,GAChB,qBAAqB,GACrB,kBAAkB,GAClB,qBAAqB,GACrB,oBAAoB,GACpB,uBAAuB,CAAC;AAQ5B;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI,CAQnF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,EAAE,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,WAAW,EAAE,CAGpF;AAED,8EAA8E;AAC9E,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/observability/degradations.js

@@ -0,0 +1,74 @@
+/**
+ * ADR-PIPELINE-089 §2 — Trace-scoped degradation sink.
+ *
+ * The Phase 1 Health Gate needs to know which degradations occurred during
+ * a run in order to classify the verdict as `healthy | degraded | failed`.
+ * Degradation signals come from multiple modules that do not share a call
+ * stack: the agent dispatcher (local-compute fallbacks), the consensus
+ * validator (`[pipeline-017]`), the pre-render pass (`[pipeline-072]`),
+ * and the LLM synthesis tag-survival check (`[exec-docs]`).
+ *
+ * Rather than thread a collector through every signature, this module
+ * exposes a process-local Map keyed by the correlation/trace id. Each
+ * emission site makes a one-line call:
+ *
+ *   recordDegradation(traceId, { code: 'local-fallback',
+ *                                 message: 'costops/attribution using local compute',
+ *                                 source: 'agents-dispatcher' });
+ *
+ * The verdict compute step at the end of `executeNaturalLanguageRoute`
+ * calls `drainDegradations(traceId)` to collect all entries and clear the
+ * bucket. Clearing is important so subsequent runs in the same process
+ * (tests, long-lived daemons) do not leak state.
+ *
+ * This is intentionally NOT a general-purpose telemetry channel. It
+ * captures pipeline-health-relevant signals only. High-volume logs keep
+ * going to stderr as before.
+ */
+// ============================================================================
+// Storage — process-local, trace-keyed.
+// ============================================================================
+const buckets = new Map();
+/**
+ * Record a degradation against a trace. Safe to call with an empty trace
+ * id — the call silently no-ops rather than binding to a shared ''
+ * bucket that would cross-contaminate runs.
+ */
+export function recordDegradation(traceId, d) {
+    if (!traceId)
+        return;
+    let bucket = buckets.get(traceId);
+    if (!bucket) {
+        bucket = [];
+        buckets.set(traceId, bucket);
+    }
+    bucket.push(d);
+}
+/**
+ * Return all degradations recorded against `traceId` (in insertion order)
+ * and clear the bucket. Returns an empty array if the trace has no entries.
+ */
+export function drainDegradations(traceId) {
+    if (!traceId)
+        return [];
+    const bucket = buckets.get(traceId);
+    if (!bucket)
+        return [];
+    buckets.delete(traceId);
+    return bucket;
+}
+/**
+ * Non-destructive read — for tests and for cases where the caller wants to
+ * inspect the bucket without draining (e.g. a post-phase snapshot without
+ * clearing state that later phases will add to).
+ */
+export function peekDegradations(traceId) {
+    if (!traceId)
+        return [];
+    return buckets.get(traceId) ?? [];
+}
+/** Test helper — clears ALL trace buckets. Do not use in production paths. */
+export function __resetDegradationsForTests() {
+    buckets.clear();
+}
+//# sourceMappingURL=degradations.js.map

package/dist/observability/degradations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradations.js","sourceRoot":"","sources":["../../src/observability/degradations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAyBH,+EAA+E;AAC/E,wCAAwC;AACxC,+EAA+E;AAE/E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B,EAAE,CAAc;IAC3E,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA2B;IAC1D,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,2BAA2B;IACzC,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/dist/pipeline/phase1-verdict.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ADR-PIPELINE-089 §2 — Phase 1 Health Gate.
+ *
+ * Classifies the outcome of `executeNaturalLanguageRoute` (Phase 1) into
+ * one of three verdicts:
+ *
+ *   - 'failed'   — auto-chain must be skipped; user sees the specific cause.
+ *   - 'degraded' — auto-chain proceeds, but we warn loudly about what is
+ *                  missing so the user can judge the output.
+ *   - 'healthy'  — all inputs intact; auto-chain proceeds silently.
+ *
+ * Inputs:
+ *   - invocations: the per-agent dispatch results (from RouteResult)
+ *   - degradations: the list drained from the degradation sink (tag
+ *                   survival, consensus, sector-classifier, local
+ *                   fallbacks, etc.)
+ *   - artifactFiles: the list of files the artifact generator wrote
+ *
+ * The verdict is computed structurally — no stderr parsing, no global
+ * state. Same inputs always produce the same verdict.
+ */
+import type { Degradation } from '../observability/degradations.js';
+export type Phase1Verdict = 'healthy' | 'degraded' | 'failed';
+export interface Phase1VerdictResult {
+    verdict: Phase1Verdict;
+    degradations: Degradation[];
+    /** Concise reason string for the banner — single sentence. */
+    reason: string;
+    /** Counts used by the classifier, preserved for status.json consumers. */
+    stats: {
+        totalAgents: number;
+        succeededAgents: number;
+        erroredAgents: number;
+        artifactCount: number;
+        simulatorStatus: 'succeeded' | 'failed-transient' | 'failed-terminal' | 'failed-unknown' | 'not-invoked';
+    };
+}
+interface InvocationLike {
+    intent: {
+        domain: string;
+        agent: string;
+    };
+    result: unknown;
+}
+/**
+ * Compute the Phase 1 verdict from structural dispatch results plus the
+ * drained degradation list.
+ *
+ * @param invocations Per-agent invocation results (as `multi.result.invocations`)
+ * @param degradations Collected degradation entries for this trace
+ * @param artifactFiles Files the artifact generator produced on disk
+ */
+export declare function computePhase1Verdict(invocations: readonly InvocationLike[], degradations: readonly Degradation[], artifactFiles: readonly string[]): Phase1VerdictResult;
+export {};
+//# sourceMappingURL=phase1-verdict.d.ts.map

package/dist/pipeline/phase1-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase1-verdict.d.ts","sourceRoot":"","sources":["../../src/pipeline/phase1-verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,WAAW,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,aAAa,CAAC;KAC1G,CAAC;CACH;AAED,UAAU,cAAc;IACtB,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,MAAM,EAAE,OAAO,CAAC;CACjB;AASD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,SAAS,cAAc,EAAE,EACtC,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,mBAAmB,CAoHrB"}