@akagilnc/pi-workflow-roles 0.1.1883 → 0.1.1893

package/dist/reviewer-child-executor.js

@@ -6,7 +6,7 @@ import { executeEvidenceChild } from "./evidence-child-executor.js";
 export function projectSharedChildFailure(error) {
     if (typeof error === "object" && error !== null && "evidenceChildFailure" in error) {
         const classification = error.evidenceChildFailure;
-        if (classification === "provider" || classification === "child") {
+        if (classification === "provider" || classification === "child" || classification === "unknown") {
             Object.assign(error, { reviewerFailure: classification });
         }
     }

package/dist/typed-provider-http.js

@@ -0,0 +1,60 @@
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const TYPED_HTTP_FILE = "typed-provider-http.json";
+function typedProviderHttpPath(runDirectory) {
+  return join(runDirectory, TYPED_HTTP_FILE);
+}
+async function clearTypedProviderHttpObservation(runDirectory) {
+  try {
+    await unlink(typedProviderHttpPath(runDirectory));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+}
+async function recordTypedProviderHttpStatus(runDirectory, observation) {
+  if (observation.httpStatus >= 200 && observation.httpStatus < 300) {
+    await clearTypedProviderHttpObservation(runDirectory);
+    return;
+  }
+  const body = {
+    httpStatus: observation.httpStatus,
+    provider: observation.provider
+  };
+  await writeFile(
+    typedProviderHttpPath(runDirectory),
+    `${JSON.stringify(body)}
+`,
+    "utf8"
+  );
+}
+async function readLatestTypedProviderHttpObservation(runDirectory) {
+  let text;
+  try {
+    text = await readFile(typedProviderHttpPath(runDirectory), "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+  const raw = JSON.parse(text);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("typed provider HTTP observation must be a JSON object");
+  }
+  const record = raw;
+  if (typeof record.httpStatus !== "number") {
+    throw new Error("typed provider HTTP observation missing numeric httpStatus");
+  }
+  if (typeof record.provider !== "string" || record.provider.trim() === "") {
+    throw new Error("typed provider HTTP observation missing non-empty provider");
+  }
+  return { httpStatus: record.httpStatus, provider: record.provider };
+}
+export {
+  clearTypedProviderHttpObservation,
+  readLatestTypedProviderHttpObservation,
+  recordTypedProviderHttpStatus
+};

package/dist/upstream-error-testimony.js

@@ -0,0 +1,19 @@
+function isNonSuccessHttpStatus(status) {
+  return typeof status === "number" && (status < 200 || status >= 300);
+}
+function hasUpstreamErrorTestimony(input) {
+  if (isNonSuccessHttpStatus(input.httpStatus)) return true;
+  return Array.isArray(input.diagnostics) && input.diagnostics.length > 0;
+}
+function projectConfirmedRemotePayload(input) {
+  return {
+    ...input.body === void 0 ? {} : { body: input.body },
+    ...input.code === void 0 ? {} : { code: input.code },
+    ...input.errno === void 0 ? {} : { errno: input.errno }
+  };
+}
+export {
+  hasUpstreamErrorTestimony,
+  isNonSuccessHttpStatus,
+  projectConfirmedRemotePayload
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.1883",
+  "version": "0.1.1893",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/build-package.mjs

@@ -14,6 +14,8 @@ const entries = [
   "activation-reconciliation",
   "sitian-role-run-coordinates",
   "sitian-record-entry",
+  "typed-provider-http",
+  "upstream-error-testimony",
 ];
 
 /**

package/src/evidence-child-executor.ts

@@ -33,6 +33,11 @@ import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.ts";
 import type { ReviewerPromptText } from "./reviewer-prompt-identity.ts";
 import { createStreamIdleGuard, isStreamIdleTimeoutError } from "./stream-idle-guard.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT, type NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
+import {
+  hasUpstreamErrorTestimony,
+  isNonSuccessHttpStatus,
+  projectConfirmedRemotePayload,
+} from "./upstream-error-testimony.ts";
 
 // ── shared constants / types ──────────────────────────────────────────────
 
@@ -186,15 +191,25 @@ export async function createInheritedRuntime(options: InheritedRuntimeOptions):
         const idle = createStreamIdleGuard(
           options.signal === undefined ? {} : { parentSignal: options.signal },
         );
+        // Typed HTTP status observed via onResponse — never inferred from prose.
+        let observedHttpStatus: number | undefined;
         try {
           const requestSignal = request?.signal;
           const streamSignal = requestSignal === undefined
             ? idle.signal
             : AbortSignal.any([idle.signal, requestSignal]);
+          const priorOnResponse = request?.onResponse;
           const inheritedRequest = {
             ...(request ?? {}),
             ...(dispatch.auth.env === undefined ? {} : { env: dispatch.auth.env }),
             signal: streamSignal,
+            onResponse: async (
+              response: { status: number; headers: Record<string, string> },
+              model: Model<Api>,
+            ) => {
+              if (typeof response?.status === "number") observedHttpStatus = response.status;
+              await priorOnResponse?.(response, model);
+            },
           } as ProviderStreamOptions;
           if (options.runCompletion !== undefined) {
             await new Promise<void>((resolve) => setImmediate(resolve));
@@ -209,12 +224,12 @@ export async function createInheritedRuntime(options: InheritedRuntimeOptions):
               ),
               streamSignal,
             );
-            const response: AssistantMessage = {
+            const response: AssistantMessage = attachObservedHttpStatus({
               ...completed,
               api: model.api,
               provider: model.provider,
               model: model.id,
-            };
+            }, observedHttpStatus);
             if (response.stopReason === "error" || response.stopReason === "aborted") {
               wrapped.push({ type: "error", reason: response.stopReason, error: response });
             } else {
@@ -232,9 +247,12 @@ export async function createInheritedRuntime(options: InheritedRuntimeOptions):
             if (next.done) break;
             sawEvent = true;
             idle.poke();
-            wrapped.push(next.value as any);
+            wrapped.push(enrichStreamEvent(next.value, observedHttpStatus) as any);
           }
-          const response = await waitForStream(source.result(), idle.signal);
+          const response = attachObservedHttpStatus(
+            await waitForStream(source.result(), idle.signal),
+            observedHttpStatus,
+          );
           if (!sawEvent) wrapped.end(response);
           return;
         } catch (error) {
@@ -264,17 +282,26 @@ export async function createInheritedRuntime(options: InheritedRuntimeOptions):
             continue;
           }
           state.streamFailure = failure;
-          const response: AssistantMessage = {
-            role: "assistant",
-            content: [],
+          const projected = projectStructuredRemote(failure);
+          // Prefer structured fields on the thrown failure; fall back to onResponse observation.
+          const httpStatus = projected.httpStatus ?? numericHttpStatus(observedHttpStatus);
+          const response = {
+            role: "assistant" as const,
+            content: [] as [],
             api: model.api,
             provider: model.provider,
             model: model.id,
             usage: emptyUsage(),
-            stopReason: "error",
+            stopReason: "error" as const,
+            // Preserve the held failure message bytes — do not rewrite.
             errorMessage: failure instanceof Error ? failure.message : String(failure),
             timestamp: Date.now(),
-          };
+            ...(projected.diagnostics === undefined ? {} : { diagnostics: projected.diagnostics }),
+            ...(httpStatus === undefined ? {} : { status: httpStatus, statusCode: httpStatus }),
+            ...(projected.body === undefined ? {} : { body: projected.body }),
+            ...(projected.code === undefined ? {} : { code: projected.code }),
+            ...(projected.errno === undefined ? {} : { errno: projected.errno }),
+          } as unknown as AssistantMessage;
           wrapped.push({ type: "error", reason: "error", error: response });
           wrapped.end(response);
           return;
@@ -346,11 +373,114 @@ export async function createInheritedRuntime(options: InheritedRuntimeOptions):
   return state;
 }
 
+type EvidenceChildFailureClassification = "provider" | "child" | "unknown";
 type ClassifiedReviewerError = Error & Readonly<{
-  evidenceChildFailure: "provider" | "child";
+  evidenceChildFailure: EvidenceChildFailureClassification;
   evidenceChildOriginal?: unknown;
 }>;
-function classifiedError(error: unknown, evidenceChildFailure: "provider" | "child"): ClassifiedReviewerError {
+function numericHttpStatus(value: unknown): number | undefined {
+  return isNonSuccessHttpStatus(value) ? value : undefined;
+}
+
+type StructuredRemoteProjection = {
+  readonly hasTestimony: boolean;
+  readonly httpStatus?: number;
+  readonly diagnostics?: unknown;
+  readonly body?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+};
+
+/**
+ * Cause-chain reader over the shared upstream-testimony authority.
+ * Shape walking stays here; testimony + confirmed-remote payload rules are shared.
+ */
+function projectStructuredRemote(error: unknown): StructuredRemoteProjection {
+  let httpStatus: number | undefined;
+  let diagnostics: unknown;
+  let body: unknown;
+  let code: unknown;
+  let errno: unknown;
+  let cursor: unknown = error;
+  const seen = new Set<unknown>();
+  while (typeof cursor === "object" && cursor !== null && !seen.has(cursor)) {
+    seen.add(cursor);
+    const record = cursor as Record<string, unknown>;
+    const nodeStatus = numericHttpStatus(record.statusCode)
+      ?? numericHttpStatus(record.status)
+      ?? numericHttpStatus(record.httpStatus);
+    const nodeDiagnostics = Array.isArray(record.diagnostics) && record.diagnostics.length > 0
+      ? record.diagnostics
+      : undefined;
+    const nodeHasTestimony = hasUpstreamErrorTestimony({
+      ...(nodeStatus === undefined ? {} : { httpStatus: nodeStatus }),
+      ...(nodeDiagnostics === undefined ? {} : { diagnostics: nodeDiagnostics }),
+    });
+    if (httpStatus === undefined && nodeStatus !== undefined) httpStatus = nodeStatus;
+    if (diagnostics === undefined && nodeDiagnostics !== undefined) diagnostics = nodeDiagnostics;
+    // Payload only from confirmed-remote nodes — never arbitrary local Error.code.
+    if (nodeHasTestimony) {
+      const payload = projectConfirmedRemotePayload(record);
+      if (body === undefined && payload.body !== undefined) body = payload.body;
+      if (code === undefined && payload.code !== undefined) code = payload.code;
+      if (errno === undefined && payload.errno !== undefined) errno = payload.errno;
+    }
+    cursor = record.cause;
+  }
+  return {
+    hasTestimony: hasUpstreamErrorTestimony({
+      ...(httpStatus === undefined ? {} : { httpStatus }),
+      ...(diagnostics === undefined ? {} : { diagnostics }),
+    }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(diagnostics === undefined ? {} : { diagnostics }),
+    ...(body === undefined ? {} : { body }),
+    ...(code === undefined ? {} : { code }),
+    ...(errno === undefined ? {} : { errno }),
+  };
+}
+
+/**
+ * Attach a directly observed HTTP status onto an error/aborted assistant message.
+ * Does not invent status from errorMessage prose; skips when already held.
+ */
+function attachObservedHttpStatus<T extends AssistantMessage>(
+  message: T,
+  observedHttpStatus: number | undefined,
+): T {
+  if (observedHttpStatus === undefined) return message;
+  if (message.stopReason !== "error" && message.stopReason !== "aborted") return message;
+  if (numericHttpStatus(observedHttpStatus) === undefined) return message;
+  if (projectStructuredRemote(message).httpStatus !== undefined) return message;
+  return Object.assign(message, {
+    status: observedHttpStatus,
+    statusCode: observedHttpStatus,
+  });
+}
+function enrichStreamEvent(event: unknown, observedHttpStatus: number | undefined): unknown {
+  if (observedHttpStatus === undefined || event === null || typeof event !== "object") return event;
+  const record = event as Record<string, unknown>;
+  if (record.type === "error" && record.error !== null && typeof record.error === "object") {
+    return {
+      ...record,
+      error: attachObservedHttpStatus(record.error as AssistantMessage, observedHttpStatus),
+    };
+  }
+  if (record.type === "done" && record.message !== null && typeof record.message === "object") {
+    return {
+      ...record,
+      message: attachObservedHttpStatus(record.message as AssistantMessage, observedHttpStatus),
+    };
+  }
+  if (record.partial !== null && typeof record.partial === "object") {
+    return {
+      ...record,
+      partial: attachObservedHttpStatus(record.partial as AssistantMessage, observedHttpStatus),
+    };
+  }
+  return event;
+}
+function classifiedError(error: unknown, evidenceChildFailure: EvidenceChildFailureClassification): ClassifiedReviewerError {
   const diagnostic = typeof error === "object" && error !== null && typeof (error as { errorMessage?: unknown }).errorMessage === "string"
     ? (error as { errorMessage: string }).errorMessage
     : error === undefined ? "" : String(error);
@@ -359,7 +489,9 @@ function classifiedError(error: unknown, evidenceChildFailure: "provider" | "chi
     : Object.assign(new Error(diagnostic, { cause: error }), { evidenceChildOriginal: error });
   const classification = "evidenceChildFailure" in wrapped
     ? (wrapped as ClassifiedReviewerError).evidenceChildFailure
-    : evidenceChildFailure;
+    : evidenceChildFailure === "provider" && !projectStructuredRemote(error).hasTestimony
+      ? "unknown"
+      : evidenceChildFailure;
   return Object.assign(wrapped, { evidenceChildFailure: classification });
 }
 
@@ -461,13 +593,19 @@ export async function executeEvidenceChild(
         const lastAssistant = [...session.messages]
           .reverse()
           .find((message) => message.role === "assistant");
-        if (lastAssistant?.role === "assistant" && lastAssistant.stopReason === "error") {
+        // error|aborted assistant stops share the upstream-testimony rule: provider only
+        // with direct HTTP/SDK testimony, otherwise existing unknown. child is reserved
+        // for real local child/report failures (no assistant / blank report / cleanup).
+        if (
+          lastAssistant?.role === "assistant"
+          && (lastAssistant.stopReason === "error" || lastAssistant.stopReason === "aborted")
+        ) {
           throw classifiedError(
             new Error(lastAssistant.errorMessage ?? "", { cause: lastAssistant }),
-            "provider",
+            projectStructuredRemote(lastAssistant).hasTestimony ? "provider" : "unknown",
           );
         }
-        if (lastAssistant?.role !== "assistant" || lastAssistant.stopReason === "aborted") {
+        if (lastAssistant?.role !== "assistant") {
           throw classifiedError(
             new Error("Evidence child child terminated without a report", {
               cause: lastAssistant ?? session.messages,
@@ -820,22 +958,37 @@ export async function executeAuditorChild(
           else if (retentionFailure !== undefined) throw retentionFailure;
         } catch (retentionFailure) {
           if (response.stopReason !== "error") throw retentionFailure;
+          // Do not trim/rewrite the held errorMessage bytes.
+          const diagnostic = typeof response.errorMessage === "string" && response.errorMessage.trim() !== ""
+            ? response.errorMessage
+            : undefined;
+          const projected = projectStructuredRemote(response);
           const failure = new Error(
-            response.errorMessage?.trim() || "provider failure",
+            diagnostic ?? "",
             { cause: retentionFailure },
           ) as Error & {
-            knownCause: "provider";
+            knownCause: "provider" | "unrecognized";
             failureCode?: string;
             details: Record<string, unknown>;
           };
-          failure.name = response.model || response.provider || "Error";
-          failure.knownCause = "provider";
-          failure.failureCode = response.provider || response.model;
+          if (projected.hasTestimony && (response.model || response.provider)) {
+            failure.name = response.model || response.provider || "Error";
+            failure.failureCode = response.provider || response.model;
+          }
+          failure.knownCause = projected.hasTestimony ? "provider" : "unrecognized";
           const retentionError = retentionFailure instanceof Error ? retentionFailure : undefined;
           const retentionCause = retentionError?.cause;
           failure.details = {
-            ...(response.provider ? { provider: response.provider } : {}),
-            ...(response.model ? { model: response.model } : {}),
+            ...(diagnostic === undefined ? {} : { errorMessage: diagnostic }),
+            ...(projected.hasTestimony && response.provider ? { provider: response.provider } : {}),
+            ...(projected.hasTestimony && response.model ? { model: response.model } : {}),
+            ...(response.api ? { api: response.api } : {}),
+            ...(response.rawStopReason ? { rawStopReason: response.rawStopReason } : {}),
+            ...(projected.httpStatus === undefined ? {} : { httpStatus: projected.httpStatus }),
+            ...(projected.diagnostics === undefined ? {} : { diagnostics: projected.diagnostics }),
+            ...(projected.body === undefined ? {} : { body: projected.body }),
+            ...(projected.code === undefined ? {} : { code: projected.code }),
+            ...(projected.errno === undefined ? {} : { errno: projected.errno }),
             retentionFailure: {
               name: retentionError?.name ?? typeof retentionFailure,
               message: retentionError?.message ?? String(retentionFailure),
@@ -862,8 +1015,8 @@ export async function executeAuditorChild(
             parent: binding.parent,
             failure: {
               cause: failure.knownCause,
-              identity: { name: failure.name, code: failure.failureCode },
-              diagnostic: failure.message,
+              ...(failure.failureCode === undefined ? {} : { identity: { name: failure.name, code: failure.failureCode } }),
+              ...(failure.message === "" ? {} : { diagnostic: failure.message }),
               details: failure.details,
             },
           });

package/src/navigator-attendance.ts

@@ -18,6 +18,12 @@ import { renderPublicAkRoleCommand } from "./public-command-renderer.ts";
 import { issueRoot, subjectPath } from "./work-subject-identity.ts";
 import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
+import { recordTypedProviderHttpStatus } from "./typed-provider-http.ts";
+import {
+  hasUpstreamErrorTestimony,
+  isNonSuccessHttpStatus,
+  projectConfirmedRemotePayload,
+} from "./upstream-error-testimony.ts";
 
 export const NAVIGATOR_EVENT_TYPE = "ak-navigator-attendance" as const;
 export const NAVIGATOR_PREPARE_TOOL_NAME = "ak_navigator_prepare" as const;
@@ -1092,19 +1098,37 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
       }
       assignProviderFailure(navigatorProviderFailureFromStatus(status));
     };
-    const humanProviderError = <T extends Record<string, unknown>>(error: T): T => {
-      const human = { ...error };
-      delete human.statusCode;
-      delete human.code;
-      delete human.navigatorFailure;
-      return human;
+    /** Project only fields actually held on the call surface — never forge upstream payload. */
+    const projectHeldUpstream = (error: unknown): Record<string, unknown> => {
+      if (!exactRecord(error)) return {};
+      // Shape reading stays local; testimony + confirmed-remote payload use shared authority.
+      const status = typeof error.statusCode === "number"
+        ? error.statusCode
+        : typeof error.status === "number"
+          ? error.status
+          : typeof error.httpStatus === "number"
+            ? error.httpStatus
+            : undefined;
+      const httpStatus = isNonSuccessHttpStatus(status) ? status : undefined;
+      const diagnostics = Array.isArray(error.diagnostics) && error.diagnostics.length > 0
+        ? error.diagnostics
+        : undefined;
+      const testimony = hasUpstreamErrorTestimony({
+        ...(httpStatus === undefined ? {} : { httpStatus }),
+        ...(diagnostics === undefined ? {} : { diagnostics }),
+      });
+      return {
+        ...(httpStatus === undefined ? {} : { statusCode: httpStatus, status: httpStatus }),
+        ...(diagnostics === undefined ? {} : { diagnostics }),
+        ...(testimony ? projectConfirmedRemotePayload(error) : {}),
+      };
     };
-    let providerFailureEvidenceNumber = 0;
-    let providerFailureEvidence: { id: string; error: unknown } | undefined;
-    const retainProviderFailure = (error: unknown): string => {
-      const id = `navigator-provider-failure-${++providerFailureEvidenceNumber}`;
-      providerFailureEvidence = { id, error };
-      return id;
+    /** Keep held upstream fields; strip only the local navigatorFailure classification marker. */
+    const retainUpstreamMessage = <T extends Record<string, unknown>>(error: T): T => {
+      if (!("navigatorFailure" in error)) return error;
+      const copy = { ...error };
+      delete copy.navigatorFailure;
+      return copy;
     };
     const setupFailureMessage = (error: unknown) => ({
       role: "assistant" as const,
@@ -1115,15 +1139,27 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
       usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
       stopReason: "error" as const,
       errorMessage: error instanceof Error ? error.message : String(error),
-      navigatorFailureEvidenceId: retainProviderFailure(error),
       timestamp: Date.now(),
+      ...projectHeldUpstream(error),
     });
+    const persistNavigatorHttpObservation = async (
+      status: number,
+      model: unknown,
+    ): Promise<void> => {
+      const runDir = process.env.AK_ROLE_RUN_DIR;
+      if (typeof runDir !== "string" || runDir.trim() === "") return;
+      const provider = exactRecord(model) && typeof model.provider === "string" && model.provider.trim() !== ""
+        ? model.provider
+        : undefined;
+      if (provider === undefined) return;
+      await recordTypedProviderHttpStatus(runDir, { httpStatus: status, provider });
+    };
     const instrumentProvider = <TProvider extends NonNullable<typeof provider>>(sourceProvider: TProvider): TProvider => {
       type StreamFn = TProvider["stream"];
       type StreamSimpleFn = TProvider["streamSimple"];
       type StreamOptionsArg = Parameters<StreamFn>[2];
       type StreamSimpleOptionsArg = Parameters<StreamSimpleFn>[2];
-      const instrumentStreamOptions = <TOptions>(options: TOptions): TOptions => {
+      const instrumentStreamOptions = <TOptions>(options: TOptions, observedStatus: { value?: number }): TOptions => {
         const record = (exactRecord(options) ? options : {}) as Record<string, unknown>;
         const previous = typeof record.onResponse === "function"
           ? record.onResponse as (response: { status: number; headers: Record<string, string> }, model: unknown) => void | Promise<void>
@@ -1131,12 +1167,23 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
         return {
           ...record,
           onResponse: async (response: { status: number; headers: Record<string, string> }, model: unknown) => {
+            observedStatus.value = response.status;
             classifyProviderResponseStatus(response.status);
+            // Durable run-dossier sink for typed non-success HTTP (2xx clears).
+            await persistNavigatorHttpObservation(response.status, model);
             await previous?.(response, model);
           },
         } as TOptions;
       };
-      const wrapProviderStream = (source: ReturnType<StreamFn>): ReturnType<StreamFn> => {
+      /** Attach a directly observed non-success HTTP status when the terminal message lacks one. */
+      const withObservedStatus = <T extends Record<string, unknown>>(message: T, observedStatus: number | undefined): T => {
+        if (observedStatus === undefined || observedStatus >= 200 && observedStatus < 300) return message;
+        if (typeof message.statusCode === "number" || typeof message.status === "number" || typeof message.httpStatus === "number") {
+          return message;
+        }
+        return { ...message, statusCode: observedStatus, status: observedStatus };
+      };
+      const wrapProviderStream = (source: ReturnType<StreamFn>, observedStatus: { value?: number }): ReturnType<StreamFn> => {
         const wrapped = createAssistantMessageEventStream();
         void (async () => {
           let result: Awaited<ReturnType<typeof source.result>> | undefined;
@@ -1147,13 +1194,14 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
                 sawTerminal = true;
                 if (event.type === "done" && exactRecord(event.message)) {
                   assignProviderFailure(navigatorProviderFailureFromDiagnostics(event.message.diagnostics));
-                  result = humanProviderError(event.message) as typeof event.message;
+                  // Keep held message/status/body/code/errno/diagnostics on the session surface.
+                  result = withObservedStatus(retainUpstreamMessage(event.message), observedStatus.value) as typeof event.message;
                   wrapped.push({ ...event, message: result });
                   continue;
                 }
                 if (event.type === "error" && exactRecord(event.error)) {
                   classifyProviderStreamError(event.error);
-                  result = humanProviderError(event.error) as typeof event.error;
+                  result = withObservedStatus(retainUpstreamMessage(event.error), observedStatus.value) as typeof event.error;
                   wrapped.push({ ...event, error: result });
                   continue;
                 }
@@ -1163,24 +1211,24 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
             // Only await result after a terminal done/error event. end(undefined) leaves result() unresolved forever.
             if (sawTerminal) {
               const terminal = await source.result();
-              if (result === undefined && exactRecord(terminal)) result = humanProviderError(terminal) as typeof terminal;
-              else if (result === undefined) result = terminal;
+              if (result === undefined && exactRecord(terminal)) {
+                result = withObservedStatus(retainUpstreamMessage(terminal), observedStatus.value) as typeof terminal;
+              } else if (result === undefined) result = terminal;
             }
           } catch (error) {
-            // Contract: README.md#Navigator-attendance — synthetic provider errors retain a stable pointer to the raw rejection while exposing only human-safe text.
+            // Stream throw: project held upstream fields onto the synthetic terminal message (session is durable).
             classifyProviderStreamError(error);
-            if (providerFailure === undefined) providerFailure = { source: "transport", cause: "transport" };
+            if (providerFailure === undefined) providerFailure = { source: "unknown", cause: "unknown" };
             if (!sawTerminal) {
-              const message = setupFailureMessage(error);
+              const message = withObservedStatus(setupFailureMessage(error), observedStatus.value);
               wrapped.push({ type: "error", reason: "error", error: message });
               result = message;
               sawTerminal = true;
             }
           } finally {
-            // No terminal stream event means the provider produced no response.
-            // Emit a synthetic error so callers do not hang waiting for done/error, and never await an unresolved source.result().
+            // No terminal stream event: unknown only — do not forge upstream payload.
             if (!sawTerminal) {
-              if (providerFailure === undefined) providerFailure = { source: "transport", cause: "transport" };
+              if (providerFailure === undefined) providerFailure = { source: "unknown", cause: "unknown" };
               const message = setupFailureMessage(new Error("Navigator provider produced no response"));
               wrapped.push({ type: "error", reason: "error", error: message });
               result = message;
@@ -1191,15 +1239,16 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
         })();
         return wrapped as ReturnType<StreamFn>;
       };
-      const invokeInstrumentedStream = (invoke: () => ReturnType<StreamFn>): ReturnType<StreamFn> => {
+      const invokeInstrumentedStream = (invoke: (observedStatus: { value?: number }) => ReturnType<StreamFn>): ReturnType<StreamFn> => {
         // Reset before invoking the selected provider so setup throws cannot leave a prior call's fact.
         providerFailure = undefined;
+        const observedStatus: { value?: number } = {};
         try {
-          return wrapProviderStream(invoke());
+          return wrapProviderStream(invoke(observedStatus), observedStatus);
         } catch (error) {
-          // Contract: README.md#Navigator-attendance — setup failures become terminal synthetic errors, with the raw rejection retained by stable evidence pointer.
+          // Setup failures become terminal synthetic errors with held upstream fields projected when present.
           classifyProviderStreamError(error);
-          if (providerFailure === undefined) providerFailure = { source: "transport", cause: "transport" };
+          if (providerFailure === undefined) providerFailure = { source: "unknown", cause: "unknown" };
           const wrapped = createAssistantMessageEventStream();
           const message = setupFailureMessage(error);
           queueMicrotask(() => {
@@ -1212,12 +1261,16 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
       return {
         ...sourceProvider,
         stream(model: Parameters<StreamFn>[0], streamContext: Parameters<StreamFn>[1], options: StreamOptionsArg) {
-          const instrumented = instrumentStreamOptions(options);
-          return invokeInstrumentedStream(() => sourceProvider.stream(model, streamContext, instrumented) as ReturnType<StreamFn>) as ReturnType<StreamFn>;
+          return invokeInstrumentedStream((observedStatus) => {
+            const instrumented = instrumentStreamOptions(options, observedStatus);
+            return sourceProvider.stream(model, streamContext, instrumented) as ReturnType<StreamFn>;
+          }) as ReturnType<StreamFn>;
         },
         streamSimple(model: Parameters<StreamSimpleFn>[0], streamContext: Parameters<StreamSimpleFn>[1], options: StreamSimpleOptionsArg) {
-          const instrumented = instrumentStreamOptions(options);
-          return invokeInstrumentedStream(() => sourceProvider.streamSimple(model, streamContext, instrumented) as ReturnType<StreamFn>) as ReturnType<StreamSimpleFn>;
+          return invokeInstrumentedStream((observedStatus) => {
+            const instrumented = instrumentStreamOptions(options, observedStatus);
+            return sourceProvider.streamSimple(model, streamContext, instrumented) as ReturnType<StreamFn>;
+          }) as ReturnType<StreamSimpleFn>;
         },
       } as TProvider;
     };