fix(python): validate shared pyc header facts

src/application/python/PythonPycService.test.ts

@@ -66,6 +66,28 @@ const report: PythonPyc = {
   ],
 };
 
+it.each([
+  {
+    flags: 1,
+    hash_based: true,
+    source_hash_hex: "",
+    source_mtime: null,
+    source_size: null,
+  },
+  { flags: 1 },
+])("refuses inconsistent provider header facts %j", async (header) => {
+  const result = await new PythonPycService({
+    close: async () => {},
+    identity,
+    inspect: async () =>
+      ok({ ...report, header: { ...report.header, ...header } }),
+  }).inspect({ path: report.artifact.path });
+  expect(result).toMatchObject({
+    ok: false,
+    error: { _tag: "AnalysisOutputError" },
+  });
+});
+
 it("rejects a relative path and extra arguments before reading", async () => {
   let calls = 0;
   const service = new PythonPycService({

src/domain/analysisErrorPresentation.ts

@@ -73,8 +73,7 @@ export const analysisErrorRemediationAction = (
   error = resolvedAnalysisError(error);
   const continuing =
     callerLifetime === "continuing"
-      ? (error.continuingCallerGuidance?.remediationAction ??
-        hopperContinuingRecovery(error)?.remediationAction)
+      ? error.continuingCallerGuidance?.remediationAction
       : undefined;
   if (continuing !== undefined) return continuing;
   if (
@@ -163,13 +162,11 @@ export const analysisErrorRemediationAction = (
   if (error instanceof HopperTimeoutError)
     return error.operation === undefined
       ? HOPPER_STARTUP_TIMEOUT_REMEDIATION
-      : RERUN_HOPPER_INVOCATION;
+      : error.providerState === "busy"
+        ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
+        : "Check binary_session for Hopper health, then retry the operation.";
   if (error instanceof HopperProcessError)
-    return error.failureCode !== undefined && error.userMessage !== undefined
-      ? error.userMessage
-      : error.stage === "launch"
-        ? "Review the captured launcher diagnostics and Hopper setup, then retry opening the target."
-        : RERUN_HOPPER_INVOCATION;
+    return hopperProcessRemediation(error);
   if (error instanceof HopperStartError)
     return error.ownerRunId === undefined
       ? "Check the Hopper launcher and target details, then retry opening the target."
@@ -430,19 +427,10 @@ const analysisErrorUserMessageParts = (
 ): { readonly outcome: string; readonly continuing?: string } => {
   error = resolvedAnalysisError(error);
   const outcome = outcomeUserMessage(error);
-  const continuing =
-    error.continuingCallerGuidance?.userMessage ??
-    hopperContinuingRecovery(error)?.userMessage;
+  const continuing = error.continuingCallerGuidance?.userMessage;
   return continuing === undefined ? { outcome } : { outcome, continuing };
 };
 
-/** Whether a child diagnostic needs a distinct continuing guidance snapshot. */
-export const hasAnalysisContinuingCallerGuidance = (
-  error: AnalysisError,
-): boolean =>
-  error.continuingCallerGuidance !== undefined ||
-  hopperContinuingRecovery(error) !== undefined;
-
 /**
  * Re-attribute one failure's message and another's remediation to a composed
  * error, keeping the form each caller lifetime receives.
@@ -562,8 +550,8 @@ const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
       return "REA timed out waiting for Hopper bridge readiness, which includes initial analysis. Hopper may still be analyzing the target or waiting for a loader, demo, or license dialog. Review the captured launcher outcome and resolve retained cleanup before retrying.";
     const request = error.operation;
     return error.providerState === "busy"
-      ? `Hopper timed out during ${request} while the provider remained busy.`
-      : `Hopper timed out during ${request} before it started.`;
+      ? `Hopper timed out during ${request} while the provider remained busy. Check binary_session.analysis_activity, wait for the active request to finish, then retry.`
+      : `Hopper timed out during ${request} before it started. Check binary_session for provider health, then retry.`;
   }
   if (error instanceof HopperProcessError) return hopperProcessMessage(error);
   if (error instanceof HopperStartError)
@@ -579,38 +567,16 @@ const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
 const RESTART_OWNED_PROVIDER =
   "Restart the owned provider by calling close_binary, then open the target again and retry.";
 const RESTART_UNREACHABLE_HOPPER = `${RESTART_OWNED_PROVIDER} close_binary preserves retained Evidence and Unknown history on this connection; export_evidence_bundle before ending the REA process if you need to resume later.`;
-const RERUN_HOPPER_INVOCATION =
-  "Review the reported Hopper state and resolve any incomplete cleanup before rerunning the command.";
 
-const hopperContinuingRecovery = (
-  error: AnalysisError,
-): AnalysisContinuingCallerGuidance | undefined => {
-  if (error instanceof HopperTimeoutError && error.operation !== undefined) {
-    const action =
-      error.providerState === "busy"
-        ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
-        : "Check binary_session for Hopper health, then retry the operation.";
-    return { userMessage: action, remediationAction: action };
-  }
-  if (!(error instanceof HopperProcessError)) return undefined;
-  if (
-    error.providerState === "exited" &&
-    (error.stage === "launch" || error.failureCode !== undefined)
-  )
-    return undefined;
-  const action =
-    error.providerState === "unreachable"
-      ? RESTART_UNREACHABLE_HOPPER
-      : providerRetryAction(error.providerState) === "restart_provider"
-        ? RESTART_OWNED_PROVIDER
-        : "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
-  return {
-    userMessage: action,
-    ...(error.stage === "launch" ||
-    (error.failureCode !== undefined && error.userMessage !== undefined)
-      ? {}
-      : { remediationAction: action }),
-  };
+const hopperProcessRemediation = (error: HopperProcessError): string => {
+  if (error.failureCode !== undefined && error.userMessage !== undefined)
+    return error.userMessage;
+  if (error.stage === "launch")
+    return "Review the captured launcher diagnostics and Hopper setup, then retry opening the target.";
+  if (error.providerState === "unreachable") return RESTART_UNREACHABLE_HOPPER;
+  if (providerRetryAction(error.providerState) === "restart_provider")
+    return RESTART_OWNED_PROVIDER;
+  return "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
 };
 
 const hopperProcessMessage = (error: HopperProcessError): string => {
@@ -630,11 +596,15 @@ const hopperProcessMessage = (error: HopperProcessError): string => {
           ? "no exit code was observed"
           : `signal ${signal}`
         : `exit code ${String(error.exitCode)}`;
-    return `Hopper exited during ${where} (${exit}).${startup}${request}`;
+    const recovery =
+      error.failureCode === undefined && stage !== "launch"
+        ? ` ${RESTART_OWNED_PROVIDER}`
+        : "";
+    return `Hopper exited during ${where} (${exit}).${startup}${recovery}${request}`;
   }
   if (error.providerState === "unreachable")
-    return `Hopper became unreachable during ${where}; its process exit was not observed.${startup}${request}`;
-  return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup}${request}`;
+    return `Hopper became unreachable during ${where}; its process exit was not observed. ${RESTART_UNREACHABLE_HOPPER}${startup}${request}`;
+  return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup} Read binary_session.provider_operation_health for this request before retrying or restarting.${request}`;
 };
 
 const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => {

src/domain/analysisErrorProjection.test.ts

@@ -1569,91 +1569,11 @@ describe("analysis error projection: caller lifetime", () => {
       applies_at: "next_invocation",
       environment: "REA_HOPPER_STARTUP_TIMEOUT_MS",
     });
-  });
-});
-
-describe("analysis error projection: Hopper caller lifetime", () => {
-  it.each([
-    [
-      new HopperProcessError(7, { operation: "search_strings", requestId: 4 }),
-      "close_binary",
-      "exit code 7",
-    ],
-    [
-      new HopperProcessError(null, {
-        operation: "search_strings",
-        providerState: "unreachable",
-      }),
-      "export_evidence_bundle",
-      "process exit was not observed",
-    ],
-    [
-      new HopperProcessError(null, { operation: "search_strings" }),
-      "binary_session.provider_operation_health",
-      "could not determine",
-    ],
-    [
-      new HopperTimeoutError(30_000, "search_strings", 42, "busy"),
-      "binary_session.analysis_activity",
-      "remained busy",
-    ],
-    [
-      new HopperTimeoutError(30_000, "search_strings", 42, "not_started"),
-      "binary_session",
-      "before it started",
-    ],
-  ] as const)(
-    "keeps Hopper outcome facts and scopes request recovery to the caller",
-    (error, continuingTool, outcome) => {
-      const continuing = projectAnalysisError(error);
-      const invocation = projectAnalysisError(error, "invocation");
-      expect(continuing.message).toContain(continuingTool);
-      expect(continuing.remediation.action).toContain(continuingTool);
-      expect(invocation.message).toContain(outcome);
-      expect(invocation.message).not.toContain(continuingTool);
-      expect(invocation.remediation.action).toContain("rerunning the command");
-      expect(invocation.remediation.action).not.toContain(continuingTool);
-      expect(invocation.details).toEqual(continuing.details);
-      expect(invocation.code).toBe(continuing.code);
-      expect(invocation.category).toBe(continuing.category);
-      expect(invocation.retryable).toBe(continuing.retryable);
-      expect(analysisErrorProjectionSchema.parse(invocation)).toEqual(
-        invocation,
-      );
-    },
-  );
-
-  it("keeps Hopper recovery scoped through composed cleanup and its history", () => {
-    const primary = new HopperProcessError(null, {
-      operation: "search_strings",
-      providerState: "unreachable",
-    });
-    const cleanup = new ProviderCleanupError("hopper", ["hopper-bridge"], {});
-    const composed = analysisErrorWithCleanupFailure(
-      primary,
-      cleanup,
-    ).bindCleanupDependencies([cleanup]);
-    const invocationPrimary = projectAnalysisError(primary, "invocation");
-    const continuingPrimary = projectAnalysisError(primary);
-    const invocation = projectAnalysisError(composed, "invocation");
-    const continuing = projectAnalysisError(composed);
-    expect(invocation.message).toBe(invocationPrimary.message);
-    expect(continuing.message).toBe(continuingPrimary.message);
-    expect(invocation.details).toMatchObject({
-      resources: ["hopper-bridge"],
-      diagnostics: { primary_error: invocationPrimary },
-    });
-    expect(continuing.details).toMatchObject({
-      diagnostics: { primary_error: continuingPrimary },
-    });
-
-    cleanup.resolveCleanup();
-    expect(
-      projectAnalysisError(composed, "invocation").details?.cleanup_history,
-    ).toMatchObject({ primary_error: invocationPrimary });
-    expect(
-      projectAnalysisError(composed).details?.cleanup_history,
-    ).toMatchObject({ primary_error: continuingPrimary });
+    // A busy request is not a startup: it carries no lifetime-specific text.
+    const busy = new HopperTimeoutError(30_000, "trace_feature", 42, "busy");
+    expect(projectAnalysisError(busy, "invocation").remediation).toEqual(
+      projectAnalysisError(busy).remediation,
+    );
   });
 });
 

src/domain/analysisErrorProjection.ts

@@ -13,7 +13,6 @@ import {
   analysisErrorRemediationAction,
   analysisErrorUserMessage,
   assertKnownAnalysisErrorTag,
-  hasAnalysisContinuingCallerGuidance,
 } from "./analysisErrorPresentation.js";
 import {
   AnalysisAccessDeniedError,
@@ -319,7 +318,7 @@ const projectionDependsOnCallerLifetime = (
     )
       if (
         node.limit !== undefined ||
-        hasAnalysisContinuingCallerGuidance(node) ||
+        node.continuingCallerGuidance !== undefined ||
         node.invocationDiagnostics !== undefined ||
         node.workflowUnknownPublication !== undefined
       )

src/domain/python/pythonPyc.test.ts

@@ -3,9 +3,49 @@ import {
   inspectPythonPycInputSchema,
   pythonPycMarshalProfile,
   PYTHON_PYC_MARSHAL_PROFILES,
+  pythonPycHeaderSchema,
 } from "./pythonPyc.js";
 import { pythonBytecodeIdentity } from "./pythonBytecodeIdentity.js";
 
+const hashHeader = {
+  magic: 3531,
+  python_version: "3.12",
+  code_layout: "py311",
+  flags: 3,
+  hash_based: true,
+  check_source: true,
+  source_hash_hex: "0123456789abcdef",
+  source_mtime: null,
+  source_size: null,
+};
+
+it.each(["", "ab", "g".repeat(16)])(
+  "rejects an invalid source hash %j",
+  (source_hash_hex) => {
+    expect(
+      pythonPycHeaderSchema.safeParse({ ...hashHeader, source_hash_hex })
+        .success,
+    ).toBe(false);
+  },
+);
+
+it.each([
+  { hash_based: false },
+  { check_source: false },
+  { source_hash_hex: null },
+  { source_mtime: 0 },
+  { source_size: 0 },
+])("keeps header facts consistent with the recorded flags: %j", (changed) => {
+  expect(
+    pythonPycHeaderSchema.safeParse({ ...hashHeader, ...changed }).success,
+  ).toBe(false);
+});
+
+it("preserves unknown raw header flags and valid hash bytes", () => {
+  const header = { ...hashHeader, flags: 0x80000003 };
+  expect(pythonPycHeaderSchema.parse(header)).toEqual(header);
+});
+
 it("keeps pinned CPython identity separate from standalone marshal coverage", () => {
   expect(pythonPycMarshalProfile(3394)).toEqual({
     code_layout: "py37",

src/domain/python/pythonPyc.ts

@@ -205,17 +205,53 @@ const pythonCodeObjectSchema = z.strictObject({
 });
 export type PythonPycCodeObject = z.infer<typeof pythonCodeObjectSchema>;
 
-export const pythonPycHeaderSchema = z.strictObject({
-  magic: z.number().int().min(0).max(0xffff),
-  python_version: z.string().min(1),
-  code_layout: z.enum(PYTHON_PYC_CODE_LAYOUTS),
-  flags: uint,
-  hash_based: z.boolean(),
-  check_source: z.boolean(),
-  source_hash_hex: z.string().nullable(),
-  source_mtime: uint.nullable(),
-  source_size: uint.nullable(),
-});
+export const pythonPycHeaderSchema = z
+  .strictObject({
+    magic: z.number().int().min(0).max(0xffff),
+    python_version: z.string().min(1),
+    code_layout: z.enum(PYTHON_PYC_CODE_LAYOUTS),
+    flags: uint,
+    hash_based: z.boolean(),
+    check_source: z.boolean(),
+    source_hash_hex: z
+      .string()
+      .regex(/^[0-9a-f]{16}$/u)
+      .nullable(),
+    source_mtime: uint.nullable(),
+    source_size: uint.nullable(),
+  })
+  .superRefine((header, context) => {
+    for (const [field, flag] of [
+      ["hash_based", PYTHON_PYC_HASH_BASED],
+      ["check_source", PYTHON_PYC_CHECK_SOURCE],
+    ] as const)
+      if (header[field] !== ((header.flags & flag) !== 0))
+        context.addIssue({
+          code: "custom",
+          path: [field],
+          message: `${field} disagrees with its recorded header flag.`,
+        });
+    if (header.hash_based === (header.source_hash_hex === null))
+      context.addIssue({
+        code: "custom",
+        path: ["source_hash_hex"],
+        message:
+          "Hash-based pycs require an 8-byte source hash; others must omit it.",
+      });
+    if (header.hash_based === (header.source_mtime !== null))
+      context.addIssue({
+        code: "custom",
+        path: ["source_mtime"],
+        message: "Timestamp pycs require mtime; hash-based pycs must omit it.",
+      });
+    if (header.hash_based === (header.source_size !== null))
+      context.addIssue({
+        code: "custom",
+        path: ["source_size"],
+        message:
+          "Timestamp pycs require source_size; hash-based pycs must omit it.",
+      });
+  });
 
 /** Bounded CPython 3.7–3.13 pyc observation; marshal is walked, bytecode is not decompiled. */
 export const pythonPycSchema = z
@@ -253,29 +289,6 @@ export const pythonPycSchema = z
         message: "Marshal byte count disagrees with the header-stripped file.",
       });
     }
-    if (report.header.hash_based === (report.header.source_hash_hex === null)) {
-      context.addIssue({
-        code: "custom",
-        path: ["header", "source_hash_hex"],
-        message:
-          "Hash-based pycs require an 8-byte source hash; others must omit it.",
-      });
-    }
-    if (report.header.hash_based === (report.header.source_mtime !== null)) {
-      context.addIssue({
-        code: "custom",
-        path: ["header", "source_mtime"],
-        message: "Timestamp pycs require mtime; hash-based pycs must omit it.",
-      });
-    }
-    if (report.header.hash_based === (report.header.source_size !== null)) {
-      context.addIssue({
-        code: "custom",
-        path: ["header", "source_size"],
-        message:
-          "Timestamp pycs require source_size; hash-based pycs must omit it.",
-      });
-    }
     if (report.coverage.code_objects !== report.code_objects.length) {
       context.addIssue({
         code: "custom",