@inflexa-ai/harness 0.4.1 → 0.4.2

package/dist/execution/post-step-pipeline.d.ts

@@ -60,9 +60,20 @@ export declare function generateStepSummaryAndWrite(deps: PostStepPipelineDeps,
  */
 export declare function reconcileAndRegisterStepArtifacts(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<readonly ArtifactManifestEntry[]>;
 /**
- * Vector-index the threaded file descriptions + summary into the per-analysis
- * pgvector store. Best-effort (see the artifact-manifest spec): indexing degrades on any failure
- * without failing the step — the internal try/catch logs + swallows.
+ * Vector-index the threaded file descriptions + the step summary into the
+ * per-analysis pgvector store. Best-effort (see the artifact-manifest spec):
+ * indexing degrades without failing the step.
+ *
+ * Degradation is per-item. Index setup (ensuring the index exists and building
+ * the store) is all-or-nothing — a setup failure logs and skips the stage,
+ * because without an index there is nowhere to index into. Past setup, each
+ * file description and the summary is embedded and upserted under its own
+ * failure boundary, so one rejected input (e.g. an over-length document the
+ * embedding backend rejects) costs only its own entry and every other item is
+ * still attempted. A partial index is invisible at the search surface — it
+ * returns fewer hits, never an error — so each per-item failure logs the item
+ * id and input text length, and when any item fails a final record carries the
+ * indexed/failed counts as the only signal that degradation occurred.
  */
 export declare function vectorIndexStepOutputs(deps: PostStepPipelineDeps, postCtx: PostStepContext, artifacts: PostStepArtifacts): Promise<void>;
 /**

package/dist/execution/post-step-pipeline.js

@@ -144,60 +144,88 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
     return reconciled.manifest;
 }
 /**
- * Vector-index the threaded file descriptions + summary into the per-analysis
- * pgvector store. Best-effort (see the artifact-manifest spec): indexing degrades on any failure
- * without failing the step — the internal try/catch logs + swallows.
+ * Vector-index the threaded file descriptions + the step summary into the
+ * per-analysis pgvector store. Best-effort (see the artifact-manifest spec):
+ * indexing degrades without failing the step.
+ *
+ * Degradation is per-item. Index setup (ensuring the index exists and building
+ * the store) is all-or-nothing — a setup failure logs and skips the stage,
+ * because without an index there is nowhere to index into. Past setup, each
+ * file description and the summary is embedded and upserted under its own
+ * failure boundary, so one rejected input (e.g. an over-length document the
+ * embedding backend rejects) costs only its own entry and every other item is
+ * still attempted. A partial index is invisible at the search surface — it
+ * returns fewer hits, never an error — so each per-item failure logs the item
+ * id and input text length, and when any item fails a final record carries the
+ * indexed/failed counts as the only signal that degradation occurred.
  */
 export async function vectorIndexStepOutputs(deps, postCtx, artifacts) {
     const { input } = postCtx;
     const { metadataEntries, summary, reconciledManifest } = artifacts;
+    const logger = (deps.logger ?? createNoopLogger()).named("post-step").named("vector-index").with({ runId: input.runId, stepId: input.stepId });
+    let vectorStore;
+    let indexName;
     try {
+        // Setup is all-or-nothing: without an index there is nothing to index into.
         await ensureSearchIndex(deps.pool, input.analysisId, deps.embedding.dimensions);
-        const vectorStore = createVectorStore(deps.pool);
-        const indexName = searchIndexName(input.analysisId);
-        const embedOne = async (text) => {
-            const [vec] = unwrapOrThrow(await deps.embedding.embed([text], postCtx.session));
-            if (!vec)
-                throw new Error("vectorIndexStepOutputs: empty embedding response");
-            return vec;
-        };
-        const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
-        const survivingPaths = new Set(reconciledManifest.map((a) => a.path));
-        const liveMetadata = metadataEntries.filter((e) => survivingPaths.has(e.dbPath.slice(dbPathPrefix.length)));
-        for (const entry of liveMetadata) {
-            const embedding = await embedOne(entry.description);
-            unwrapOrThrow(await vectorStore.upsert({
-                indexName,
-                vectors: [embedding],
-                metadata: [{ text: entry.description, type: "output", ...entry.metadata }],
-                ids: [`/${input.analysisId}/${entry.dbPath}`],
-            }));
+        vectorStore = createVectorStore(deps.pool);
+        indexName = searchIndexName(input.analysisId);
+    }
+    catch (err) {
+        logger.warn("indexing failed", logger.errorFields(err));
+        return;
+    }
+    const embedOne = async (text) => {
+        const [vec] = unwrapOrThrow(await deps.embedding.embed([text], postCtx.session));
+        if (!vec)
+            throw new Error("vectorIndexStepOutputs: empty embedding response");
+        return vec;
+    };
+    /** Index one item, absorbing its failure so the rest of the step still lands. */
+    const indexOne = async (id, text, metadata) => {
+        try {
+            const embedding = await embedOne(text);
+            unwrapOrThrow(await vectorStore.upsert({ indexName, vectors: [embedding], metadata: [metadata], ids: [id] }));
+            return true;
         }
-        if (summary && summary.markdown.trim().length > 0) {
-            const relPath = `runs/${input.runId}/${input.stepId}/output/summary.md`;
-            const summaryDbPath = `/${input.analysisId}/${relPath}`;
-            const summaryEmbedding = await embedOne(summary.markdown);
-            unwrapOrThrow(await vectorStore.upsert({
-                indexName,
-                vectors: [summaryEmbedding],
-                metadata: [
-                    {
-                        text: summary.markdown,
-                        type: "summary",
-                        stepId: input.stepId,
-                        runId: input.runId,
-                        agentId: input.agentId,
-                        path: relPath,
-                    },
-                ],
-                ids: [summaryDbPath],
-            }));
+        catch (err) {
+            // Text length rides as a field because over-length input is the known
+            // failure driver, and the description/summary itself stays out of logs.
+            logger.warn("indexing failed", { id, textLength: text.length, ...logger.errorFields(err) });
+            return false;
         }
+    };
+    const dbPathPrefix = `runs/${input.runId}/${input.stepId}/`;
+    const survivingPaths = new Set(reconciledManifest.map((a) => a.path));
+    const liveMetadata = metadataEntries.filter((e) => survivingPaths.has(e.dbPath.slice(dbPathPrefix.length)));
+    let indexed = 0;
+    let failed = 0;
+    for (const entry of liveMetadata) {
+        const ok = await indexOne(`/${input.analysisId}/${entry.dbPath}`, entry.description, { text: entry.description, type: "output", ...entry.metadata });
+        if (ok)
+            indexed++;
+        else
+            failed++;
     }
-    catch (err) {
-        const logger = (deps.logger ?? createNoopLogger()).named("post-step").named("vector-index");
-        logger.warn("indexing failed", { runId: input.runId, stepId: input.stepId, ...logger.errorFields(err) });
+    if (summary && summary.markdown.trim().length > 0) {
+        const relPath = `runs/${input.runId}/${input.stepId}/output/summary.md`;
+        const ok = await indexOne(`/${input.analysisId}/${relPath}`, summary.markdown, {
+            text: summary.markdown,
+            type: "summary",
+            stepId: input.stepId,
+            runId: input.runId,
+            agentId: input.agentId,
+            path: relPath,
+        });
+        if (ok)
+            indexed++;
+        else
+            failed++;
     }
+    // A partial index is invisible at the search surface — it returns fewer hits,
+    // never an error — so the count of what did not land is the only signal.
+    if (failed > 0)
+        logger.warn("indexed with failures", { indexed, failed });
 }
 /**
  * Assemble the step-detail payload (file tree, summary markdown, output file

package/dist/execution/reconcile-manifest.d.ts

@@ -17,9 +17,9 @@ export interface ReconcileManifestInput {
     /** Collector backing the manifest; mutated to reflect drops/rehashes. */
     collector: ProvenanceCollector;
     /**
-     * Operational logging seam; omitted falls back to no-op. Attestation is
-     * fail-fast, so what this records — which entry was dropped, which input
-     * could not be hashed — is the account of why a step died.
+     * Operational logging seam; omitted falls back to no-op. What this records
+     * — which entry or input was dropped, which input could not be hashed — is
+     * the sole account of why lineage changed or a step died.
      */
     logger?: Logger;
 }

package/dist/execution/reconcile-manifest.js

@@ -23,7 +23,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
-import { artifactReconcileDropped } from "../lib/metrics.js";
+import { artifactReconcileDropped, lineageInputDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
     const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
@@ -74,7 +74,7 @@ export async function reconcileManifestWithDisk(input) {
         const hash = await computeSha256File(absPath);
         reconciled.push({ ...entry, hash, size: info.size });
     }
-    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, logger);
+    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, agentId, logger);
     return { manifest: reconciled, droppedCount };
 }
 /**
@@ -87,35 +87,47 @@ export async function reconcileManifestWithDisk(input) {
  *
  * `artifacts`-source reads are the step's OWN files (mutating, dropped by the
  * registration translator), so they are not attested and not hashed here.
- * Lineage attestation is fail-fast: an input we cannot hash (gone, or resolving
- * outside the analysis tree) throws rather than registering a hashless edge.
+ * Lineage attestation is fail-fast for drift: an input that should be on disk
+ * and is not (ENOENT) throws rather than registering a hashless edge. A read
+ * that resolves OUTSIDE the analysis tree is dropped from lineage instead —
+ * the sandbox can legitimately open paths above its mount (`/{resourceId}/..`
+ * is the container root) and a capture layer may report them; that is out of
+ * scope, not drift, and failing the step over it killed real analyses in the
+ * field. Dropping still registers no hashless edge, which is the invariant.
  */
-async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, logger) {
+async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, agentId, logger) {
     const resourceRoot = path.resolve(workspaceRoot);
     for (const ref of collector.getTrackedInputs()) {
         if (ref.source === "artifacts")
             continue;
         if (hasValidContentHash(ref.hash))
             continue;
-        // Each throw below is logged before it is raised. The thrown message reaches
-        // `failStep` as one opaque string and everything downstream of that is
-        // scrubbed, so naming the site and the offending ref HERE is what makes a
-        // fail-fast attestation distinguishable from a registry rejection after the
-        // fact — the read's `source` in particular says whether the step declared
+        // Every throw below is logged before it is raised, and every drop is
+        // logged as it happens. The thrown message reaches `failStep` as one
+        // opaque string and everything downstream of that is scrubbed, so naming
+        // the site and the offending ref HERE is the only account of why a step
+        // died — the read's `source` in particular says whether the step declared
         // this input at all.
         const attestation = { path: ref.path, source: ref.source, refRunId: ref.runId, refStepId: ref.stepId };
         // `ref.path` is the absolute container path `/{resourceId}/...`; strip the
         // mount segment and map the tail onto the host workspace root. `path.join`
         // normalizes any `..`, and the bound confines the read to the analysis tree.
+        // An out-of-tree resolution is dropped, not thrown: it is not an attestable
+        // lineage edge, but it is also not drift — mirrors the out-of-bounds output
+        // skip in `reconcileManifestWithDisk` and the directory drop below.
         const containerPrefix = `/${resourceId}`;
         if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
-            logger.error("input read resolves outside the analysis tree", { ...attestation, throwSite: "container-prefix-bound" });
-            throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
+            logger.warn("dropping out-of-tree input from lineage", { ...attestation, boundSite: "container-prefix" });
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "container-prefix" });
+            collector.dropInput(ref);
+            continue;
         }
         const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
         if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
-            logger.error("input read resolves outside the analysis tree", { ...attestation, hostPath, throwSite: "workspace-root-bound" });
-            throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
+            logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "workspace-root" });
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "workspace-root" });
+            collector.dropInput(ref);
+            continue;
         }
         let info;
         try {
@@ -138,6 +150,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
             // as drift; a directory is not drift.
             logger.debug("dropping non-file input from lineage", attestation);
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "directory" });
             collector.dropInput(ref);
             continue;
         }

package/dist/lib/metrics.d.ts

@@ -3,5 +3,7 @@
  *
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
  */
 export declare const artifactReconcileDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const lineageInputDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;

package/dist/lib/metrics.js

@@ -3,6 +3,7 @@
  *
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
  */
 import { metrics } from "@opentelemetry/api";
 const meter = metrics.getMeter("cortex");
@@ -10,3 +11,8 @@ export const artifactReconcileDropped = meter.createCounter("cortex.artifact.rec
     description: "Manifest entries dropped because their on-disk file was missing at " +
         "registration time (writes-then-deletes, renames). Tagged by agent_id, step_id.",
 });
+export const lineageInputDropped = meter.createCounter("cortex.artifact.reconcile.input_dropped", {
+    description: "Tracked input reads dropped from lineage at reconcile because they are " +
+        "not content-attestable files of the analysis (directory reads, " +
+        "out-of-tree resolutions). Tagged by agent_id, step_id, reason.",
+});

package/dist/provenance/collector.d.ts

@@ -86,7 +86,9 @@ export declare class ProvenanceCollector {
      * Called by sandbox exec provenance frame processing.
      *
      * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root
+     * @param relativePath - Path relative to the mount root; or, for a frame
+     *   report naming somewhere outside the mount, the verbatim absolute path
+     *   (see `stripMountPrefix`)
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
@@ -124,10 +126,11 @@ export declare class ProvenanceCollector {
      * Drop an input ref from lineage entirely — removes it from the tracked-input
      * map and from every record's `inputs` array (identity match, since the refs
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
-     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
-     * inotify frame tracks the open, but a directory is not a content-attestable
-     * file artifact and must never reach registration. Mirrors the output-side
-     * non-file drop.
+     * is not a content-attestable file of this analysis: one resolving to a
+     * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
+     * tracks as an open), or one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root). Neither may reach registration.
+     * Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref: InputRef): void;
     /**

package/dist/provenance/collector.js

@@ -121,7 +121,9 @@ export class ProvenanceCollector {
      * Called by sandbox exec provenance frame processing.
      *
      * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root
+     * @param relativePath - Path relative to the mount root; or, for a frame
+     *   report naming somewhere outside the mount, the verbatim absolute path
+     *   (see `stripMountPrefix`)
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
@@ -133,7 +135,12 @@ export class ProvenanceCollector {
             return existing;
         // Use explicit context if provided, otherwise fall back to path classification
         const classification = context ?? classifyReadPath(relativePath, this.stepId, this.runId, this.dependsOn);
-        const fullPath = `${mountPath}/${relativePath}`;
+        // A still-absolute `relativePath` is a report the caller could not
+        // relativize — it names somewhere outside the mount. It rides verbatim:
+        // prepending the mount root would forge an in-tree name for a foreign
+        // path, and reconcile would then see phantom drift (a missing file,
+        // which fails the step) instead of an out-of-tree read (which it drops).
+        const fullPath = relativePath.startsWith("/") ? relativePath : `${mountPath}/${relativePath}`;
         // Resolve fileId for data-source inputs via materialized file metadata map
         let fileId;
         if (classification.source === "data" && this.inputFileIdMap) {
@@ -240,10 +247,11 @@ export class ProvenanceCollector {
      * Drop an input ref from lineage entirely — removes it from the tracked-input
      * map and from every record's `inputs` array (identity match, since the refs
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
-     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
-     * inotify frame tracks the open, but a directory is not a content-attestable
-     * file artifact and must never reach registration. Mirrors the output-side
-     * non-file drop.
+     * is not a content-attestable file of this analysis: one resolving to a
+     * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
+     * tracks as an open), or one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root). Neither may reach registration.
+     * Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref) {
         for (const [key, val] of this.inputAccesses) {

package/dist/provenance/exec-frame.d.ts

@@ -14,7 +14,13 @@
  */
 import type { ProvenanceFrame } from "../sandbox/types.js";
 import { type ProvenanceCollector } from "./collector.js";
-/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+/**
+ * Strip the `/{resourceId}/` mount prefix from an absolute frame path.
+ * Separators doubled at the boundary collapse (`/{rid}//a` → `a`) so an
+ * in-mount name lands on its canonical relative form. A path not under the
+ * mount comes back unchanged — still absolute — and the collector carries it
+ * verbatim (see `trackInputAccess`).
+ */
 export declare function stripMountPrefix(mountRoot: string, absPath: string): string;
 export interface FeedExecFrameArgs {
     readonly collector: ProvenanceCollector;

package/dist/provenance/exec-frame.js

@@ -13,10 +13,16 @@
  * It never throws — provenance is best-effort and must not fail an exec.
  */
 import { classifyReadPath } from "./collector.js";
-/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+/**
+ * Strip the `/{resourceId}/` mount prefix from an absolute frame path.
+ * Separators doubled at the boundary collapse (`/{rid}//a` → `a`) so an
+ * in-mount name lands on its canonical relative form. A path not under the
+ * mount comes back unchanged — still absolute — and the collector carries it
+ * verbatim (see `trackInputAccess`).
+ */
 export function stripMountPrefix(mountRoot, absPath) {
     const prefix = mountRoot.endsWith("/") ? mountRoot : `${mountRoot}/`;
-    return absPath.startsWith(prefix) ? absPath.slice(prefix.length) : absPath;
+    return absPath.startsWith(prefix) ? absPath.slice(prefix.length).replace(/^\/+/, "") : absPath;
 }
 /**
  * Translate one exec's frame into a collector record. Per-command input

package/dist/providers/errors.d.ts

@@ -10,9 +10,12 @@
  * is required to disambiguate): the gateway emits `402` exclusively for
  * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
  * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all.
+ * network error with no status at all. A `401` is `auth`: the credential the
+ * host put behind the call is expired, revoked, or absent, and only a human
+ * re-authenticating fixes it — which is a different remedy from every other
+ * non-retryable 4xx, so it is a different kind.
  */
-export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
+export type ProviderErrorKind = "auth" | "budget" | "tenant-blocked" | "provider";
 /**
  * The provider error value channel — a `DomainError`-conforming
  * discriminated union mirroring `ProviderErrorKind`. `chat` / `embed` return
@@ -23,6 +26,11 @@ export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
  * step boundary.
  */
 export type ProviderError = {
+    readonly type: "auth";
+    readonly retryable: false;
+    readonly message: string;
+    readonly cause?: unknown;
+} | {
     readonly type: "budget";
     readonly retryable: false;
     readonly message: string;
@@ -72,6 +80,7 @@ export interface ProviderErrorClassification {
 /**
  * Classify a provider failure by origin.
  *
+ * - Provider `401` → `auth`, not retryable.
  * - Billing-gateway `402` → `budget`, not retryable.
  * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.

package/dist/providers/errors.js

@@ -10,7 +10,10 @@
  * is required to disambiguate): the gateway emits `402` exclusively for
  * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
  * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all.
+ * network error with no status at all. A `401` is `auth`: the credential the
+ * host put behind the call is expired, revoked, or absent, and only a human
+ * re-authenticating fixes it — which is a different remedy from every other
+ * non-retryable 4xx, so it is a different kind.
  */
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
@@ -22,7 +25,9 @@ export function isProviderError(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const v = value;
-    return (v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") && typeof v.retryable === "boolean" && typeof v.message === "string";
+    return ((v.type === "auth" || v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") &&
+        typeof v.retryable === "boolean" &&
+        typeof v.message === "string");
 }
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
@@ -42,6 +47,14 @@ export function toProviderError(e, workload) {
         return e;
     const { kind, retryable } = classifyProviderError(e);
     const detail = e instanceof Error ? e.message : String(e);
+    if (kind === "auth") {
+        return {
+            type: "auth",
+            retryable: false,
+            message: `Provider rejected the credential for ${workload} — it is expired, revoked, or absent: ${detail}`,
+            cause: e,
+        };
+    }
     if (kind === "budget") {
         return {
             type: "budget",
@@ -109,6 +122,7 @@ function looksLikeConnectionError(err) {
 /**
  * Classify a provider failure by origin.
  *
+ * - Provider `401` → `auth`, not retryable.
  * - Billing-gateway `402` → `budget`, not retryable.
  * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
@@ -116,6 +130,13 @@ function looksLikeConnectionError(err) {
  */
 export function classifyProviderError(e) {
     const status = extractStatus(e);
+    // `auth` is its own kind rather than a plain non-retryable 4xx because the
+    // remedy is categorically different: the request was well-formed and the
+    // credential behind it is not, so no amount of re-issuing or rephrasing
+    // helps — a human has to re-authenticate. Callers surface that; the generic
+    // 4xx branch below would tell them the request was wrong, which is false.
+    if (status === 401)
+        return { kind: "auth", retryable: false };
     if (status === 402)
         return { kind: "budget", retryable: false };
     if (status === 403)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.4.1",
+    "version": "0.4.2",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",