chore: merge main into codex/audit-hopper-invocation-guidance

src/domain/analysisErrorPresentation.ts

@@ -73,7 +73,8 @@ export const analysisErrorRemediationAction = (
   error = resolvedAnalysisError(error);
   const continuing =
     callerLifetime === "continuing"
-      ? error.continuingCallerGuidance?.remediationAction
+      ? (error.continuingCallerGuidance?.remediationAction ??
+        hopperContinuingRecovery(error)?.remediationAction)
       : undefined;
   if (continuing !== undefined) return continuing;
   if (
@@ -162,11 +163,13 @@ export const analysisErrorRemediationAction = (
   if (error instanceof HopperTimeoutError)
     return error.operation === undefined
       ? HOPPER_STARTUP_TIMEOUT_REMEDIATION
-      : 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.";
+      : RERUN_HOPPER_INVOCATION;
   if (error instanceof HopperProcessError)
-    return hopperProcessRemediation(error);
+    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;
   if (error instanceof HopperStartError)
     return error.ownerRunId === undefined
       ? "Check the Hopper launcher and target details, then retry opening the target."
@@ -427,10 +430,19 @@ const analysisErrorUserMessageParts = (
 ): { readonly outcome: string; readonly continuing?: string } => {
   error = resolvedAnalysisError(error);
   const outcome = outcomeUserMessage(error);
-  const continuing = error.continuingCallerGuidance?.userMessage;
+  const continuing =
+    error.continuingCallerGuidance?.userMessage ??
+    hopperContinuingRecovery(error)?.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.
@@ -550,8 +562,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. 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.`;
+      ? `Hopper timed out during ${request} while the provider remained busy.`
+      : `Hopper timed out during ${request} before it started.`;
   }
   if (error instanceof HopperProcessError) return hopperProcessMessage(error);
   if (error instanceof HopperStartError)
@@ -567,16 +579,38 @@ 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 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 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 hopperProcessMessage = (error: HopperProcessError): string => {
@@ -596,15 +630,11 @@ const hopperProcessMessage = (error: HopperProcessError): string => {
           ? "no exit code was observed"
           : `signal ${signal}`
         : `exit code ${String(error.exitCode)}`;
-    const recovery =
-      error.failureCode === undefined && stage !== "launch"
-        ? ` ${RESTART_OWNED_PROVIDER}`
-        : "";
-    return `Hopper exited during ${where} (${exit}).${startup}${recovery}${request}`;
+    return `Hopper exited during ${where} (${exit}).${startup}${request}`;
   }
   if (error.providerState === "unreachable")
-    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}`;
+    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}`;
 };
 
 const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => {

src/domain/analysisErrorProjection.test.ts

@@ -1569,11 +1569,91 @@ describe("analysis error projection: caller lifetime", () => {
       applies_at: "next_invocation",
       environment: "REA_HOPPER_STARTUP_TIMEOUT_MS",
     });
-    // 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,
-    );
+  });
+});
+
+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 });
   });
 });
 

src/domain/analysisErrorProjection.ts

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