@akagilnc/pi-workflow-roles 0.1.1883 → 0.1.1893

package/src/public-cli/coder-run.ts

@@ -41,11 +41,11 @@ import {
   markRunResumable,
   markRunRunning,
   markRunTerminal,
-  readTypedHttp429Observation,
   renderResumeCommand,
   RESUME_TRANSPORT_ENVELOPE,
   RunWriterLeaseHeldError,
   type RunWriterLease,
+  type TypedProviderHttpObservation,
 } from "./run-lifecycle.ts";
 import {
   classifyPostAdmissionFailure,
@@ -58,7 +58,9 @@ import {
   presentFailureTerminal,
   presentStructuralRejection,
   explicitInternalKnownFailureClassificationInput,
-  resolveAuditedRunnerKnownFailure,
+  resolveAuditedRunnerFailureResolution,
+  resolveControlledFailureResumeObservation,
+  controlledFailureInputFromResolution,
   settleFailureTerminalResult,
   trySettleCoderTerminalResult,
 } from "./settlement.ts";
@@ -196,6 +198,8 @@ async function presentControlledFailure(
       readonly code?: string | number;
     };
     knownDiagnostic?: string;
+    typedHttpObservationSettled?: true;
+    typedHttpObservation?: TypedProviderHttpObservation;
   },
   io: CliIo,
 ): Promise<{
@@ -204,10 +208,23 @@ async function presentControlledFailure(
   terminal: TerminalResult;
 }> {
   const hasThrown = Object.hasOwn(failureInput, "thrown");
+  const resumeObservation = await resolveControlledFailureResumeObservation({
+    runDirectory: admitted.runDirectory,
+    ...(failureInput.typedHttpObservationSettled === true
+      ? {
+        typedHttpObservationSettled: true as const,
+        ...(failureInput.typedHttpObservation === undefined
+          ? {}
+          : { typedHttpObservation: failureInput.typedHttpObservation }),
+      }
+      : {}),
+  });
+  const knownFailure =
+    failureInput.knownFailure ?? resumeObservation.observationReadFailure;
   const session =
     !hasThrown &&
     !failureInput.timedOut &&
-    failureInput.knownFailure === undefined &&
+    knownFailure === undefined &&
     failureInput.knownCause === undefined
       ? await inspectJudgeSession(admitted.sessionFile)
       : undefined;
@@ -216,7 +233,7 @@ async function presentControlledFailure(
     code: failureInput.code,
     stderr: failureInput.stderr,
     ...(hasThrown ? { thrown: failureInput.thrown } : {}),
-    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
+    ...explicitInternalKnownFailureClassificationInput(knownFailure),
     ...(failureInput.knownCause === undefined
       ? {}
       : { knownCause: failureInput.knownCause }),
@@ -230,7 +247,7 @@ async function presentControlledFailure(
   });
 
   const hasLawfulTerminalResult = await hasLawfulCoderTerminalResult(admitted);
-  const typedHttp429 = await readTypedHttp429Observation(admitted.runDirectory);
+  const typedHttp429 = resumeObservation.typedHttp429;
   const sessionPrincipalAvailable = await isSessionPrincipalAvailable(
     admitted.sessionFile,
   );
@@ -369,10 +386,11 @@ async function dispatchAdmittedCoder(input: {
       env.model,
       env.credentials,
     );
-    const knownFailure = await resolveAuditedRunnerKnownFailure({
+    const resolution = await resolveAuditedRunnerFailureResolution({
       runner: result.knownFailure,
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
+      runDirectory: admitted.runDirectory,
     });
     return await presentControlledFailure(
       admitted,
@@ -380,7 +398,7 @@ async function dispatchAdmittedCoder(input: {
         timedOut: result.timedOut,
         code: result.code,
         stderr: result.stderr,
-        ...(knownFailure === undefined ? {} : { knownFailure }),
+        ...controlledFailureInputFromResolution(resolution),
       },
       io,
     );

package/src/public-cli/collector-run.ts

@@ -299,6 +299,7 @@ async function dispatchAdmittedCollector(input: {
             }),
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
+      runDirectory: admitted.runDirectory,
     });
     return await presentControlledFailure(
       admitted,

package/src/public-cli/doctor-run.ts

@@ -280,6 +280,7 @@ async function dispatchAdmittedDoctor(input: {
       runner: result.knownFailure,
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
+      runDirectory: admitted.runDirectory,
     });
     return await presentControlledFailure(
       admitted,

package/src/public-cli/explicit-internal.ts

@@ -21,6 +21,12 @@ import {
   type ReviewerPreflightViolation,
 } from "../reviewer-dispatch.ts";
 import type { ControlledFailureCause } from "./terminal.ts";
+import {
+  hasUpstreamErrorTestimony,
+  projectConfirmedRemotePayload,
+} from "../upstream-error-testimony.ts";
+
+export { hasUpstreamErrorTestimony } from "../upstream-error-testimony.ts";
 
 /** Durable Reviewer-rejection child→parent page under AK_ROLE_RUN_DIR. */
 const REVIEWER_DISPATCH_REJECTION_FILE = "typed-known-failure.json";
@@ -147,34 +153,70 @@ export type ExplicitInternalKnownFailure = {
   readonly details?: Readonly<Record<string, unknown>>;
 };
 
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+function sessionStopDetails(input: {
+  readonly errorMessage?: string | null;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly api?: string;
+  readonly rawStopReason?: string;
+  readonly httpStatus?: number;
+  readonly diagnostics?: unknown;
+  readonly body?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+}): Record<string, unknown> {
+  const details: Record<string, unknown> = {};
+  const errorMessage = nonEmptyString(input.errorMessage);
+  if (errorMessage !== undefined) details.errorMessage = errorMessage;
+  const api = nonEmptyString(input.api);
+  if (api !== undefined) details.api = api;
+  const rawStopReason = nonEmptyString(input.rawStopReason);
+  if (rawStopReason !== undefined) details.rawStopReason = rawStopReason;
+  const testimony = hasUpstreamErrorTestimony(input);
+  if (testimony) {
+    const provider = nonEmptyString(input.provider);
+    if (provider !== undefined) details.provider = provider;
+    const model = nonEmptyString(input.model);
+    if (model !== undefined) details.model = model;
+  }
+  if (typeof input.httpStatus === "number") details.httpStatus = input.httpStatus;
+  if (input.diagnostics !== undefined) details.diagnostics = input.diagnostics;
+  // SDK structured payload fields: project only when held on a confirmed-remote node.
+  if (testimony) Object.assign(details, projectConfirmedRemotePayload(input));
+  return details;
+}
+
 /**
- * Produce a typed provider knownFailure from a native session assistant stop.
- * Source fields are session-typed (stopReason / errorMessage / provider) — never
- * child stderr prose. Used by the public classifier after a real Pi child exits.
+ * Project a native session assistant stop onto the existing knownFailure chain.
+ * Classification follows two-way testimony: typed HTTP status or SDK structure
+ * keeps provider; stopReason, configured provider/model, or errorMessage prose
+ * alone is the existing unrecognized value. Present upstream payload is preserved
+ * in details without rewriting; missing fields are omitted.
  */
 export function knownFailureFromProviderStop(input: {
   readonly stopReason?: string;
   readonly errorMessage?: string | null;
   readonly provider?: string;
   readonly model?: string;
+  readonly api?: string;
+  readonly rawStopReason?: string;
+  readonly httpStatus?: number;
+  readonly diagnostics?: unknown;
+  readonly body?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
 }): ExplicitInternalKnownFailure | undefined {
-  if (input.stopReason !== "error") return undefined;
-  const diagnostic =
-    typeof input.errorMessage === "string" && input.errorMessage.trim() !== ""
-      ? input.errorMessage.trim()
-      : "provider failure";
-  const identity: { name: string; code?: string } = {
-    name: "ProviderStopError",
-  };
-  if (typeof input.provider === "string" && input.provider.trim() !== "") {
-    identity.code = input.provider;
-  } else if (typeof input.model === "string" && input.model.trim() !== "") {
-    identity.code = input.model;
-  }
+  if (input.stopReason !== "error" && input.stopReason !== "aborted") return undefined;
+  const diagnostic = nonEmptyString(input.errorMessage);
+  const details = sessionStopDetails(input);
   return {
-    cause: "provider",
-    identity,
-    diagnostic,
+    cause: hasUpstreamErrorTestimony(input) ? "provider" : "unrecognized",
+    ...(diagnostic === undefined ? {} : { diagnostic }),
+    ...(Object.keys(details).length === 0 ? {} : { details }),
   };
 }
 

package/src/public-cli/fixer-run.ts

@@ -47,7 +47,7 @@ import {
   RESUME_TRANSPORT_ENVELOPE,
   RunWriterLeaseHeldError,
   type RunWriterLease,
-  readTypedHttp429Observation,
+  type TypedProviderHttpObservation,
 } from "./run-lifecycle.ts";
 import {
   classifyPostAdmissionFailure,
@@ -59,7 +59,9 @@ import {
   isLawfulTypedTerminalOutcome,
   presentFailureTerminal,
   presentStructuralRejection,
-  resolveAuditedRunnerKnownFailure,
+  resolveAuditedRunnerFailureResolution,
+  resolveControlledFailureResumeObservation,
+  controlledFailureInputFromResolution,
   explicitInternalKnownFailureClassificationInput,
   settleFailureTerminalResult,
   trySettleFixerTerminalResult,
@@ -205,6 +207,8 @@ async function presentControlledFailure(
     stderr: string;
     thrown?: unknown;
     knownFailure?: ExplicitInternalKnownFailure;
+    typedHttpObservationSettled?: true;
+    typedHttpObservation?: TypedProviderHttpObservation;
   },
   io: CliIo,
 ): Promise<{
@@ -213,10 +217,23 @@ async function presentControlledFailure(
   terminal: TerminalResult;
 }> {
   const hasThrown = Object.hasOwn(failureInput, "thrown");
+  const resumeObservation = await resolveControlledFailureResumeObservation({
+    runDirectory: admitted.runDirectory,
+    ...(failureInput.typedHttpObservationSettled === true
+      ? {
+        typedHttpObservationSettled: true as const,
+        ...(failureInput.typedHttpObservation === undefined
+          ? {}
+          : { typedHttpObservation: failureInput.typedHttpObservation }),
+      }
+      : {}),
+  });
+  const knownFailure =
+    failureInput.knownFailure ?? resumeObservation.observationReadFailure;
   const session =
     !hasThrown &&
     !failureInput.timedOut &&
-    failureInput.knownFailure === undefined
+    knownFailure === undefined
       ? await inspectJudgeSession(admitted.sessionFile)
       : undefined;
   const failure = classifyPostAdmissionFailure({
@@ -224,12 +241,12 @@ async function presentControlledFailure(
     code: failureInput.code,
     stderr: failureInput.stderr,
     ...(hasThrown ? { thrown: failureInput.thrown } : {}),
-    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
+    ...explicitInternalKnownFailureClassificationInput(knownFailure),
     ...(session === undefined ? {} : { session }),
   });
 
   const hasLawfulTerminalResult = await hasLawfulFixerTerminalResult(admitted);
-  const typedHttp429 = await readTypedHttp429Observation(admitted.runDirectory);
+  const typedHttp429 = resumeObservation.typedHttp429;
   const sessionPrincipalAvailable = await isSessionPrincipalAvailable(
     admitted.sessionFile,
   );
@@ -386,10 +403,11 @@ async function dispatchAdmittedFixer(input: {
       env.model,
       env.credentials,
     );
-    const knownFailure = await resolveAuditedRunnerKnownFailure({
+    const resolution = await resolveAuditedRunnerFailureResolution({
       runner: result.knownFailure,
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
+      runDirectory: admitted.runDirectory,
     });
     return await presentControlledFailure(
       admitted,
@@ -397,7 +415,7 @@ async function dispatchAdmittedFixer(input: {
         timedOut: result.timedOut,
         code: result.code,
         stderr: result.stderr,
-        ...(knownFailure === undefined ? {} : { knownFailure }),
+        ...controlledFailureInputFromResolution(resolution),
       },
       io,
     );

package/src/public-cli/judge-run.ts

@@ -36,8 +36,8 @@ import {
   markRunResumable,
   markRunRunning,
   markRunTerminal,
-  readTypedHttp429Observation,
   renderResumeCommand,
+  type TypedProviderHttpObservation,
   RESUME_TRANSPORT_ENVELOPE,
   RunWriterLeaseHeldError,
   type RunWriterLease,
@@ -52,7 +52,9 @@ import {
   isLawfulTypedTerminalOutcome,
   presentFailureTerminal,
   presentStructuralRejection,
-  resolveAuditedRunnerKnownFailure,
+  resolveAuditedRunnerFailureResolution,
+  resolveControlledFailureResumeObservation,
+  controlledFailureInputFromResolution,
   explicitInternalKnownFailureClassificationInput,
   settleJudgeFailureTerminalResult,
   trySettleJudgeTerminalResult,
@@ -171,6 +173,9 @@ async function presentControlledFailure(
     stderr: string;
     thrown?: unknown;
     knownFailure?: ExplicitInternalKnownFailure;
+    /** Pre-resolved typed-HTTP outcome — no second sidecar read when settled. */
+    typedHttpObservationSettled?: true;
+    typedHttpObservation?: TypedProviderHttpObservation;
   },
   io: CliIo,
 ): Promise<{
@@ -180,10 +185,25 @@ async function presentControlledFailure(
 }> {
   // Own-key presence, not value: `throw undefined` must not look like "no throw".
   const hasThrown = Object.hasOwn(failureInput, "thrown");
+  // v1 resume observation: reuse audited resolution when present; otherwise one
+  // controlled read. Non-absence failures fold into knownFailure — never escape.
+  const resumeObservation = await resolveControlledFailureResumeObservation({
+    runDirectory: admitted.runDirectory,
+    ...(failureInput.typedHttpObservationSettled === true
+      ? {
+        typedHttpObservationSettled: true as const,
+        ...(failureInput.typedHttpObservation === undefined
+          ? {}
+          : { typedHttpObservation: failureInput.typedHttpObservation }),
+      }
+      : {}),
+  });
+  const knownFailure =
+    failureInput.knownFailure ?? resumeObservation.observationReadFailure;
   const session =
     !hasThrown &&
     !failureInput.timedOut &&
-    failureInput.knownFailure === undefined
+    knownFailure === undefined
       ? await inspectJudgeSession(admitted.sessionFile)
       : undefined;
   const failure = classifyPostAdmissionFailure({
@@ -191,7 +211,7 @@ async function presentControlledFailure(
     code: failureInput.code,
     stderr: failureInput.stderr,
     ...(hasThrown ? { thrown: failureInput.thrown } : {}),
-    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
+    ...explicitInternalKnownFailureClassificationInput(knownFailure),
     ...(session === undefined ? {} : { session }),
   });
 
@@ -199,7 +219,7 @@ async function presentControlledFailure(
   // absence of a lawful Judge result, and a durable exact Pi session principal.
   // Lawful presence is session-owned and must not depend on artifact publication.
   const hasLawfulTerminalResult = await hasLawfulJudgeTerminalResult(admitted);
-  const typedHttp429 = await readTypedHttp429Observation(admitted.runDirectory);
+  const typedHttp429 = resumeObservation.typedHttp429;
   const sessionPrincipalAvailable = await isSessionPrincipalAvailable(
     admitted.sessionFile,
   );
@@ -355,10 +375,11 @@ async function dispatchAdmittedJudge(input: {
       env.model,
       env.credentials,
     );
-    const knownFailure = await resolveAuditedRunnerKnownFailure({
+    const resolution = await resolveAuditedRunnerFailureResolution({
       runner: result.knownFailure,
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
+      runDirectory: admitted.runDirectory,
     });
     return await presentControlledFailure(
       admitted,
@@ -366,7 +387,7 @@ async function dispatchAdmittedJudge(input: {
         timedOut: result.timedOut,
         code: result.code,
         stderr: result.stderr,
-        ...(knownFailure === undefined ? {} : { knownFailure }),
+        ...controlledFailureInputFromResolution(resolution),
       },
       io,
     );

package/src/public-cli/merger-run.ts

@@ -50,7 +50,7 @@ import {
   RESUME_TRANSPORT_ENVELOPE,
   RunWriterLeaseHeldError,
   type RunWriterLease,
-  readTypedHttp429Observation,
+  type TypedProviderHttpObservation,
 } from "./run-lifecycle.ts";
 import {
   classifyPostAdmissionFailure,
@@ -62,7 +62,9 @@ import {
   presentFailureTerminal,
   presentStructuralRejection,
   explicitInternalKnownFailureClassificationInput,
-  resolveAuditedRunnerKnownFailure,
+  resolveAuditedRunnerFailureResolution,
+  resolveControlledFailureResumeObservation,
+  controlledFailureInputFromResolution,
   settleFailureTerminalResult,
   trySettleMergerTerminalResult,
 } from "./settlement.ts";
@@ -192,6 +194,8 @@ async function presentControlledFailure(
       readonly code?: string | number;
     };
     knownDiagnostic?: string;
+    typedHttpObservationSettled?: true;
+    typedHttpObservation?: TypedProviderHttpObservation;
   },
   io: CliIo,
 ): Promise<{
@@ -200,10 +204,23 @@ async function presentControlledFailure(
   terminal: TerminalResult;
 }> {
   const hasThrown = Object.hasOwn(failureInput, "thrown");
+  const resumeObservation = await resolveControlledFailureResumeObservation({
+    runDirectory: admitted.runDirectory,
+    ...(failureInput.typedHttpObservationSettled === true
+      ? {
+        typedHttpObservationSettled: true as const,
+        ...(failureInput.typedHttpObservation === undefined
+          ? {}
+          : { typedHttpObservation: failureInput.typedHttpObservation }),
+      }
+      : {}),
+  });
+  const knownFailure =
+    failureInput.knownFailure ?? resumeObservation.observationReadFailure;
   const session =
     !hasThrown &&
     !failureInput.timedOut &&
-    failureInput.knownFailure === undefined &&
+    knownFailure === undefined &&
     failureInput.knownCause === undefined
       ? await inspectJudgeSession(admitted.sessionFile)
       : undefined;
@@ -212,7 +229,7 @@ async function presentControlledFailure(
     code: failureInput.code,
     stderr: failureInput.stderr,
     ...(hasThrown ? { thrown: failureInput.thrown } : {}),
-    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
+    ...explicitInternalKnownFailureClassificationInput(knownFailure),
     ...(failureInput.knownCause === undefined
       ? {}
       : { knownCause: failureInput.knownCause }),
@@ -226,7 +243,7 @@ async function presentControlledFailure(
   });
 
   const hasLawfulTerminalResult = await hasLawfulMergerTerminalResult(admitted);
-  const typedHttp429 = await readTypedHttp429Observation(admitted.runDirectory);
+  const typedHttp429 = resumeObservation.typedHttp429;
   const sessionPrincipalAvailable = await isSessionPrincipalAvailable(
     admitted.sessionFile,
   );
@@ -367,10 +384,11 @@ async function dispatchAdmittedMerger(input: {
       env.model,
       env.credentials,
     );
-    const knownFailure = await resolveAuditedRunnerKnownFailure({
+    const resolution = await resolveAuditedRunnerFailureResolution({
       runner: result.knownFailure,
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
+      runDirectory: admitted.runDirectory,
     });
     return await presentControlledFailure(
       admitted,
@@ -378,7 +396,7 @@ async function dispatchAdmittedMerger(input: {
         timedOut: result.timedOut,
         code: result.code,
         stderr: result.stderr,
-        ...(knownFailure === undefined ? {} : { knownFailure }),
+        ...controlledFailureInputFromResolution(resolution),
       },
       io,
     );

package/src/public-cli/reviewer-run.ts

@@ -44,11 +44,11 @@ import {
   markRunResumable,
   markRunRunning,
   markRunTerminal,
-  readTypedHttp429Observation,
   renderResumeCommand,
   RESUME_TRANSPORT_ENVELOPE,
   RunWriterLeaseHeldError,
   type RunWriterLease,
+  type TypedProviderHttpObservation,
 } from "./run-lifecycle.ts";
 import {
   classifyPostAdmissionFailure,
@@ -60,7 +60,9 @@ import {
   isLawfulTypedTerminalOutcome,
   presentFailureTerminal,
   presentStructuralRejection,
-  resolveAuditedRunnerKnownFailure,
+  resolveAuditedRunnerFailureResolution,
+  resolveControlledFailureResumeObservation,
+  controlledFailureInputFromResolution,
   explicitInternalKnownFailureClassificationInput,
   settleFailureTerminalResult,
   trySettleReviewerTerminalResult,
@@ -186,6 +188,8 @@ async function presentControlledFailure(
     stderr: string;
     thrown?: unknown;
     knownFailure?: ExplicitInternalKnownFailure;
+    typedHttpObservationSettled?: true;
+    typedHttpObservation?: TypedProviderHttpObservation;
   },
   io: CliIo,
 ): Promise<{
@@ -194,10 +198,23 @@ async function presentControlledFailure(
   terminal: TerminalResult;
 }> {
   const hasThrown = Object.hasOwn(failureInput, "thrown");
+  const resumeObservation = await resolveControlledFailureResumeObservation({
+    runDirectory: admitted.runDirectory,
+    ...(failureInput.typedHttpObservationSettled === true
+      ? {
+        typedHttpObservationSettled: true as const,
+        ...(failureInput.typedHttpObservation === undefined
+          ? {}
+          : { typedHttpObservation: failureInput.typedHttpObservation }),
+      }
+      : {}),
+  });
+  const knownFailure =
+    failureInput.knownFailure ?? resumeObservation.observationReadFailure;
   const session =
     !hasThrown &&
     !failureInput.timedOut &&
-    failureInput.knownFailure === undefined
+    knownFailure === undefined
       ? await inspectJudgeSession(admitted.sessionFile)
       : undefined;
   const failure = classifyPostAdmissionFailure({
@@ -205,12 +222,12 @@ async function presentControlledFailure(
     code: failureInput.code,
     stderr: failureInput.stderr,
     ...(hasThrown ? { thrown: failureInput.thrown } : {}),
-    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
+    ...explicitInternalKnownFailureClassificationInput(knownFailure),
     ...(session === undefined ? {} : { session }),
   });
 
   const hasLawfulTerminalResult = await hasLawfulReviewerTerminalResult(admitted);
-  const typedHttp429 = await readTypedHttp429Observation(admitted.runDirectory);
+  const typedHttp429 = resumeObservation.typedHttp429;
   const sessionPrincipalAvailable = await isSessionPrincipalAvailable(
     admitted.sessionFile,
   );
@@ -367,7 +384,7 @@ async function dispatchAdmittedReviewer(input: {
       env.model,
       env.credentials,
     );
-    const knownFailure = await resolveAuditedRunnerKnownFailure({
+    const resolution = await resolveAuditedRunnerFailureResolution({
       runner: result.knownFailure,
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
@@ -379,7 +396,7 @@ async function dispatchAdmittedReviewer(input: {
         timedOut: result.timedOut,
         code: result.code,
         stderr: result.stderr,
-        ...(knownFailure === undefined ? {} : { knownFailure }),
+        ...controlledFailureInputFromResolution(resolution),
       },
       io,
     );