@stigmer/runner 3.11.0 → 3.11.1-dev.20260812192248

package/src/activities/__tests__/error-classifier.test.ts

@@ -7,7 +7,13 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent } from "../execute-cursor/error-classifier.js";
+import {
+  synthesizeError,
+  formatClassifiedError,
+  shouldRetryWithFreshAgent,
+  DETAIL_FREE_FALLBACK_USER_PREFIX,
+  TRANSPORT_TIMEOUT_USER_PREFIX,
+} from "../execute-cursor/error-classifier.js";
 
 describe("synthesizeError", () => {
   let consoleLogSpy: ReturnType<typeof vi.spyOn>;
@@ -213,7 +219,7 @@ describe("synthesizeError", () => {
 
     expect(result.category).toBe("unknown");
     expect(result.source).toBe("fallback");
-    expect(result.message).toContain("no detail from SDK");
+    expect(result.message).toContain(DETAIL_FREE_FALLBACK_USER_PREFIX);
     expect(result.message).toContain("claude-sonnet-4");
   });
 
@@ -261,6 +267,92 @@ describe("synthesizeError", () => {
     expect(result.message).toContain("agentId=agent-123");
   });
 
+  // The exact prod shape from oss#492: the Composer 2.5 capacity incident
+  // rejected every run with a bare { status: "error" } — all five detail
+  // channels empty, fresh agent (the poisoned-handle retry produces this
+  // same shape with isResumedHandle: false). End users read this message
+  // verbatim in embedded surfaces, so it must lead with actionable copy,
+  // keep the diagnostic parenthetical for operators, and be retryable
+  // (provider capacity is transient).
+  it("detail-free failure on a fresh agent leads with user-facing copy and is retryable (oss#492)", () => {
+    const result = synthesizeError({
+      sdkError: undefined,
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      conversationErrorText: undefined,
+      isResumedHandle: false,
+      fallbackContext: { model: "composer-2.5", mode: "local", agentId: "agent-abc" },
+    });
+
+    expect(result.category).toBe("unknown");
+    expect(result.source).toBe("fallback");
+    expect(result.retryable).toBe(true);
+    expect(result.message.startsWith(DETAIL_FREE_FALLBACK_USER_PREFIX)).toBe(true);
+    // Diagnostic context survives for operators (and the env integration
+    // test's Model= matcher).
+    expect(result.message).toContain("Model=composer-2.5");
+    expect(result.message).toContain("mode=local");
+    expect(result.message).toContain("agentId=agent-abc");
+  });
+
+  // sdk-react's isInterruptedError reframes any error containing the phrase
+  // "retry or resume" as a neutral resumable notice instead of a failure
+  // alert. A capacity failure must render as a failure — guard the copy
+  // (formatted end-to-end, tail included) against ever matching that regex.
+  it("user-facing fallback copy never trips the sdk-react interrupted-error reframe", () => {
+    const interruptedReframe = /\[StallTimeoutError\]|execution interrupted|retry or resume/i;
+    for (const prefix of [DETAIL_FREE_FALLBACK_USER_PREFIX, TRANSPORT_TIMEOUT_USER_PREFIX]) {
+      expect(prefix).not.toMatch(interruptedReframe);
+    }
+    const formatted = formatClassifiedError(synthesizeError({
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext,
+    }));
+    expect(formatted).not.toMatch(interruptedReframe);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Transport-timeout heuristic (0 messages, ~default SDK timeout)
+  // ---------------------------------------------------------------------------
+
+  it("classifies a 0-message ~30s failure as retryable network with user-facing copy", () => {
+    const result = synthesizeError({
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext,
+      durationMs: 30012,
+      messageCount: 0,
+    });
+
+    expect(result.category).toBe("network");
+    expect(result.source).toBe("fallback");
+    expect(result.retryable).toBe(true);
+    expect(result.message.startsWith(TRANSPORT_TIMEOUT_USER_PREFIX)).toBe(true);
+    expect(result.message).toContain("30012ms");
+    expect(result.message).toContain("Model=claude-sonnet-4");
+  });
+
+  it("does not apply the transport heuristic outside the default-timeout window", () => {
+    const result = synthesizeError({
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext,
+      durationMs: 120000,
+      messageCount: 0,
+    });
+
+    expect(result.category).toBe("unknown");
+    expect(result.message.startsWith(DETAIL_FREE_FALLBACK_USER_PREFIX)).toBe(true);
+  });
+
   // ---------------------------------------------------------------------------
   // Source priority
   // ---------------------------------------------------------------------------

package/src/activities/__tests__/run-command.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Env contract tests for the workflow `run` task (oss#384).
+ *
+ * These spawn REAL subprocesses through the RunShell / RunScript
+ * activities and inspect the environment the child actually received —
+ * the leak-reproduction style established by the #256 fix (PR #383).
+ * Subprocess output is env variable NAMES only, never values.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createRunCommandActivities } from "../run-command.js";
+import { buildRunEnv, RUN_ENV_BASE_KEYS } from "../run-env.js";
+import { RuntimePlaceholderResolutionError } from "../../workflow-engine/resolve.js";
+
+/**
+ * Credentials planted into the runner process env before each test.
+ * Includes a name outside every known denylist to prove the contract
+ * is declare-to-receive, not deny-known-names.
+ */
+const PLANTED_SENTINELS: Record<string, string> = {
+  STIGMER_RUNNER_HITL_SECRET: "sentinel-hitl",
+  STIGMER_TOKEN: "sentinel-token",
+  CURSOR_API_KEY: "sentinel-cursor",
+  ANTHROPIC_API_KEY: "sentinel-anthropic",
+  OPERATOR_PRIVATE_CREDENTIAL: "sentinel-arbitrary",
+};
+
+const PRINT_ENV_KEYS_SHELL = `node -p 'JSON.stringify(Object.keys(process.env))'`;
+const PRINT_ENV_KEYS_SCRIPT = `console.log(JSON.stringify(Object.keys(process.env)))`;
+
+const activities = createRunCommandActivities();
+
+async function childEnvKeysViaShell(
+  environment?: Record<string, string>,
+  runtimeEnv: Record<string, unknown> = {},
+): Promise<string[]> {
+  const stdout = await activities.RunShell({
+    mode: "shell",
+    command: PRINT_ENV_KEYS_SHELL,
+    environment,
+    runtimeEnv,
+  });
+  return JSON.parse(String(stdout)) as string[];
+}
+
+async function childEnvKeysViaScript(
+  environment?: Record<string, string>,
+  runtimeEnv: Record<string, unknown> = {},
+): Promise<string[]> {
+  const stdout = await activities.RunScript({
+    mode: "script",
+    language: "js",
+    code: PRINT_ENV_KEYS_SCRIPT,
+    environment,
+    runtimeEnv,
+  });
+  return JSON.parse(String(stdout)) as string[];
+}
+
+describe("run task env contract (oss#384)", () => {
+  const saved: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const [key, value] of Object.entries(PLANTED_SENTINELS)) {
+      saved[key] = process.env[key];
+      process.env[key] = value;
+    }
+  });
+
+  afterEach(() => {
+    for (const key of Object.keys(PLANTED_SENTINELS)) {
+      if (saved[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = saved[key];
+      }
+    }
+  });
+
+  describe("RunShell", () => {
+    it("does not leak runner process credentials to the child", async () => {
+      const keys = await childEnvKeysViaShell();
+
+      for (const sentinel of Object.keys(PLANTED_SENTINELS)) {
+        expect(keys, `runner credential "${sentinel}" leaked to shell child`)
+          .not.toContain(sentinel);
+      }
+    });
+
+    it("provides the minimal base env and the declared overlay", async () => {
+      const keys = await childEnvKeysViaShell({ DECLARED_VAR: "value" });
+
+      for (const base of RUN_ENV_BASE_KEYS) {
+        if (process.env[base] !== undefined) {
+          expect(keys, `base key "${base}" missing from shell child`).toContain(base);
+        }
+      }
+      expect(keys).toContain("DECLARED_VAR");
+    });
+
+    it("resolves ${.secrets.KEY} placeholders in declared values just-in-time", async () => {
+      const stdout = await activities.RunShell({
+        mode: "shell",
+        command: `node -p 'process.env.API_KEY'`,
+        environment: { API_KEY: "${.secrets.TEST_API_KEY}" },
+        runtimeEnv: { TEST_API_KEY: "resolved-secret-value" },
+      });
+
+      expect(stdout).toBe("resolved-secret-value");
+    });
+
+    it("fails non-retryably, naming the variable, when a placeholder key is missing", async () => {
+      await expect(
+        activities.RunShell({
+          mode: "shell",
+          command: "true",
+          environment: { API_KEY: "${.secrets.NOT_PROVIDED}" },
+          runtimeEnv: {},
+        }),
+      ).rejects.toMatchObject({
+        nonRetryable: true,
+        type: "RUN_ENV_UNRESOLVED_PLACEHOLDER",
+        message: expect.stringContaining("NOT_PROVIDED"),
+      });
+    });
+  });
+
+  describe("RunScript", () => {
+    it("does not leak runner process credentials to the child", async () => {
+      const keys = await childEnvKeysViaScript();
+
+      for (const sentinel of Object.keys(PLANTED_SENTINELS)) {
+        expect(keys, `runner credential "${sentinel}" leaked to script child`)
+          .not.toContain(sentinel);
+      }
+    });
+
+    it("provides the minimal base env and the declared overlay", async () => {
+      const keys = await childEnvKeysViaScript({ DECLARED_VAR: "value" });
+
+      for (const base of RUN_ENV_BASE_KEYS) {
+        if (process.env[base] !== undefined) {
+          expect(keys, `base key "${base}" missing from script child`).toContain(base);
+        }
+      }
+      expect(keys).toContain("DECLARED_VAR");
+    });
+
+    it("resolves ${.env_vars.KEY} placeholders in declared values just-in-time", async () => {
+      const stdout = await activities.RunScript({
+        mode: "script",
+        language: "js",
+        code: "console.log(process.env.REGION)",
+        environment: { REGION: "${.env_vars.DEPLOY_REGION}" },
+        runtimeEnv: { DEPLOY_REGION: "us-east-1" },
+      });
+
+      expect(stdout).toBe("us-east-1");
+    });
+  });
+});
+
+describe("buildRunEnv", () => {
+  it("copies only the base keys present in the runner env", () => {
+    const base = {
+      PATH: "/usr/bin",
+      HOME: "/home/runner",
+      TERM: "xterm",
+    };
+
+    const env = buildRunEnv(undefined, {}, base);
+
+    expect(env).toEqual({ PATH: "/usr/bin", HOME: "/home/runner", TERM: "xterm" });
+  });
+
+  it("never copies undeclared runner variables — the oss#384 tripwire", () => {
+    // Guards against a future reintroduction of `{ ...process.env }`:
+    // credentials must be structurally absent, whatever their names.
+    const base = {
+      PATH: "/usr/bin",
+      STIGMER_RUNNER_HITL_SECRET: "secret",
+      ANY_FUTURE_CREDENTIAL: "secret",
+    };
+
+    const env = buildRunEnv({ DECLARED: "yes" }, {}, base);
+
+    expect(Object.keys(env).sort()).toEqual(["DECLARED", "PATH"]);
+  });
+
+  it("lets a declared variable override a base variable", () => {
+    const base = { PATH: "/usr/bin" };
+
+    const env = buildRunEnv({ PATH: "/custom/bin" }, {}, base);
+
+    expect(env.PATH).toBe("/custom/bin");
+  });
+
+  it("passes non-placeholder declared values through untouched", () => {
+    const env = buildRunEnv(
+      { LITERAL: "plain-value", TEMPLATED: "prefix-${.secrets.KEY}-suffix" },
+      { KEY: "mid" },
+      {},
+    );
+
+    expect(env.LITERAL).toBe("plain-value");
+    expect(env.TEMPLATED).toBe("prefix-mid-suffix");
+  });
+
+  it("throws a named error for a missing placeholder key", () => {
+    expect(() =>
+      buildRunEnv({ API_KEY: "${.secrets.MISSING}" }, {}, {}),
+    ).toThrowError(RuntimePlaceholderResolutionError);
+
+    try {
+      buildRunEnv({ API_KEY: "${.secrets.MISSING}" }, {}, {});
+    } catch (err) {
+      expect((err as RuntimePlaceholderResolutionError).variableName).toBe("MISSING");
+      expect((err as Error).message).toContain('environment "API_KEY"');
+    }
+  });
+});

package/src/activities/discover-mcp-server.ts

@@ -81,6 +81,13 @@ const PLATFORM_INJECTABLE_MAP: Record<string, string> = {
 export interface DiscoverMcpServerInput {
   mcpServerId: string;
   executionContextId?: string | null;
+  /**
+   * Execution-scoped token unlocking the connect EC's decrypted credentials
+   * (oss#535). Minted by the OSS handler and carried with the work item —
+   * discovery has no execution of its own to exchange for one. Absent on
+   * cloud, where the ambient connect_sandbox credential decrypts.
+   */
+  executionContextToken?: string | null;
   invokerIdentityAccountId?: string | null;
 }
 
@@ -280,7 +287,7 @@ export async function discoverMcpServer(
   input: DiscoverMcpServerInput,
   deps: DiscoverDeps,
 ): Promise<DiscoverMcpServerOutput> {
-  const { mcpServerId, executionContextId } = input;
+  const { mcpServerId, executionContextId, executionContextToken } = input;
   const { stigmerClient } = deps;
 
   console.log(
@@ -301,6 +308,7 @@ export async function discoverMcpServer(
   const envVars = await resolveEnvVarsForDiscovery(
     stigmerClient,
     executionContextId ?? null,
+    executionContextToken ?? null,
     slug,
     declaredEnv,
   );
@@ -382,6 +390,7 @@ export async function discoverMcpServer(
 async function resolveEnvVarsForDiscovery(
   client: StigmerClient,
   executionContextId: string | null,
+  executionContextToken: string | null,
   slug: string,
   declaredEnv: Record<string, EnvVarDeclaration>,
 ): Promise<Record<string, string>> {
@@ -394,7 +403,12 @@ async function resolveEnvVarsForDiscovery(
 
   let execCtx: Awaited<ReturnType<typeof client.getExecutionContextByExecutionId>>;
   try {
-    execCtx = await client.getExecutionContextByExecutionId(executionContextId);
+    // The payload-carried token authenticates the read on OSS (oss#535);
+    // undefined on cloud, where the ambient credential applies instead.
+    execCtx = await client.getExecutionContextByExecutionId(
+      executionContextId,
+      executionContextToken ?? undefined,
+    );
   } catch (err) {
     const cause = err instanceof Error ? err.message : String(err);
     if (credentialsExpected) {

package/src/activities/emit-event.ts

@@ -9,12 +9,24 @@
  *
  * Supported delivery targets:
  * - webhook: HTTP POST with Content-Type: application/cloudevents+json
- * - signal:  Temporal signal to another running workflow's listen task
+ * - signal:  signal to another workflow execution's listen task, routed
+ *            through the server's SendSignal lane
+ *
+ * Signal delivery is deliberately server-mediated (oss#517): a direct
+ * Temporal client here would bypass the authorization boundary (any
+ * workflow could signal any workflow id in the namespace) and is
+ * structurally incompatible with payload encryption — emit→listen is
+ * the platform's only runner-to-runner channel, and under per-identity
+ * runner keys a sender-encrypted signal fails closed at a receiver
+ * holding a different key. The server re-produces the payload, so each
+ * side's codec passes it through.
  *
  * CloudEvents spec: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
  */
 
 import { randomUUID } from "node:crypto";
+import type { JsonObject } from "@bufbuild/protobuf";
+import { StigmerClient } from "../client/stigmer-client.js";
 import { loadConfig } from "../config.js";
 import { resolveRuntimePlaceholders } from "../workflow-engine/resolve.js";
 
@@ -24,7 +36,9 @@ export interface WebhookDeliveryTarget {
 }
 
 export interface SignalDeliveryTarget {
-  readonly workflow_id: string;
+  /** Target workflow execution id ("wfx_..."), as returned by run/create. */
+  readonly execution_id: string;
+  /** Signal name matching the target's listen task event id (verbatim). */
   readonly signal_name: string;
 }
 
@@ -54,6 +68,11 @@ export interface EmitEventResult {
 
 const WEBHOOK_TIMEOUT_MS = 30_000;
 
+// Delivery is best-effort by contract, so no single target may consume the
+// CallFunction activity's whole 5m startToClose budget. Same bound as the
+// webhook arm.
+const SIGNAL_TIMEOUT_MS = 30_000;
+
 function buildEnvelope(
   config: EmitEventConfig,
   executionId: string,
@@ -120,33 +139,53 @@ async function deliverWebhook(
   }
 }
 
+function buildClient(): StigmerClient {
+  const config = loadConfig();
+  return new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+  });
+}
+
 async function deliverSignal(
   envelope: Record<string, unknown>,
   target: SignalDeliveryTarget,
+  client: StigmerClient,
 ): Promise<DeliveryError | null> {
-  try {
-    const { Connection, Client } = await import("@temporalio/client");
-
-    // Resolve Temporal coordinates through the central config layer rather than
-    // reading env directly: signal delivery must dial the SAME cluster/namespace
-    // the worker connected with. config.ts is the single source of truth for the
-    // canonical TEMPORAL_SERVICE_ADDRESS / TEMPORAL_NAMESPACE resolution — reading
-    // env here would diverge (and previously dialed localhost via a stale name).
-    const config = loadConfig();
-    const temporalAddress = config.temporalAddress;
-    const temporalNamespace = config.temporalNamespace;
-
-    const connection = await Connection.connect({ address: temporalAddress });
-    const client = new Client({ connection, namespace: temporalNamespace });
-
-    const handle = client.workflow.getHandle(target.workflow_id);
-    await handle.signal(target.signal_name, envelope);
+  // Refuse the pre-oss#517 field by name: direct-addressing raw Temporal
+  // workflow ids is exactly the capability server mediation removes.
+  const legacyWorkflowId = (target as { workflow_id?: unknown }).workflow_id;
+  if (!target.execution_id) {
+    const reason = legacyWorkflowId
+      ? "signal delivery addresses workflow executions by 'execution_id' (\"wfx_...\"); 'workflow_id' is not supported"
+      : "signal delivery requires 'execution_id'";
+    return {
+      target: `signal:${String(legacyWorkflowId ?? "")}/${target.signal_name ?? ""}`,
+      error: reason,
+    };
+  }
+  if (!target.signal_name) {
+    return {
+      target: `signal:${target.execution_id}/`,
+      error: "signal delivery requires 'signal_name'",
+    };
+  }
 
+  try {
+    await client.sendWorkflowSignal(
+      target.execution_id,
+      target.signal_name,
+      envelope as JsonObject,
+      { timeoutMs: SIGNAL_TIMEOUT_MS },
+    );
     return null;
   } catch (err) {
+    // Server refusals arrive as ConnectErrors whose messages carry the code
+    // (e.g. [not_found], [failed_precondition] for terminal executions) —
+    // surfaced verbatim in delivery_errors, same contract as the webhook arm.
     const message = err instanceof Error ? err.message : String(err);
     return {
-      target: `signal:${target.workflow_id}/${target.signal_name}`,
+      target: `signal:${target.execution_id}/${target.signal_name}`,
       error: message,
     };
   }
@@ -173,13 +212,18 @@ export async function emitEventAction(
   const errors: DeliveryError[] = [];
   const env = runtimeEnv ?? {};
 
+  // One client serves all signal targets of this emit; constructed lazily so
+  // webhook-only emits never pay for a gRPC transport.
+  let client: StigmerClient | undefined;
+
   for (const target of config.delivery) {
     let err: DeliveryError | null = null;
 
     if ("webhook" in target) {
       err = await deliverWebhook(envelope, target.webhook, env);
     } else if ("signal" in target) {
-      err = await deliverSignal(envelope, target.signal);
+      client ??= buildClient();
+      err = await deliverSignal(envelope, target.signal, client);
     }
 
     if (err) {

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -14,7 +14,7 @@ import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agen
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 
-import { buildPrompt, isHitlReinvocation } from "../index.js";
+import { appendStructuredOutputDirective, buildPrompt, isHitlReinvocation, primarySendCarriesImages } from "../index.js";
 import type { BuildPromptInput } from "../index.js";
 import { buildReinvocationPrompt, formatInteractionModePrefix, formatImplementPlanSection, formatToolApprovalProtocol, buildToolApprovalRuleFile } from "../prompt-builder.js";
 import { PLAN_MODE_DIRECTIVE } from "../../../shared/plan-mode-prompt.js";
@@ -255,7 +255,7 @@ describe("buildPrompt", () => {
   });
 });
 
-describe("isHitlReinvocation (the single discriminator for message-accompanied payloads)", () => {
+describe("isHitlReinvocation (paired with resolution.reason at every consumer — issue #366)", () => {
   it("is false with no decisions and false with an empty map", () => {
     expect(isHitlReinvocation(undefined)).toBe(false);
     expect(isHitlReinvocation(new Map())).toBe(false);
@@ -268,6 +268,115 @@ describe("isHitlReinvocation (the single discriminator for message-accompanied p
   });
 });
 
+describe("HITL recovery — fresh agent mid-HITL (issue #366)", () => {
+  const decisions = () =>
+    new Map<string, ApprovalAction>([["tool-call-1", ApprovalAction.APPROVE]]);
+  const approvals = () => [
+    create(PendingApprovalSchema, {
+      toolCallId: "tool-call-1",
+      toolName: "Write",
+      message: "Write file: gated.txt",
+    }),
+  ];
+  const recoveryInput = (overrides: Partial<BuildPromptInput> = {}) =>
+    input({
+      resolution: resolution("local", "created_after_resume_failure"),
+      approvalDecisions: decisions(),
+      pendingApprovals: approvals(),
+      ...overrides,
+    });
+
+  it("keeps the resumed-HITL prompt byte-identical to the bare reinvocation prompt (regression guard)", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        approvalDecisions: decisions(),
+        pendingApprovals: approvals(),
+      }),
+    );
+    expect(prompt).toBe(buildReinvocationPrompt(approvals(), decisions()));
+  });
+
+  it("rebuilds full context for a fresh agent mid-HITL: instructions, the ORIGINAL user message, the state-loss disclosure, and the decisions", () => {
+    const prompt = buildPrompt(recoveryInput());
+    // The pre-fix failure mode: bare decisions with no story.
+    expect(prompt).not.toBe(buildReinvocationPrompt(approvals(), decisions()));
+    expect(prompt).toContain("<agent_instructions>");
+    expect(prompt).toContain("<tool_approval_protocol>");
+    expect(prompt).toContain(`<user_request>\n${USER_MESSAGE}\n</user_request>`);
+    expect(prompt).toContain("<turn_recovery>");
+    expect(prompt).toContain("Write file: gated.txt");
+    expect(prompt).toContain("APPROVED");
+    // The opaque tool-call id must not leak into the prompt (reinvocation rule).
+    expect(prompt).not.toContain("tool-call-1");
+  });
+
+  it("orders the recovery chronologically: request, then the recovered work, then the decisions, ending on the continue directive", () => {
+    const prompt = buildPrompt(
+      recoveryInput({ turnRecoveryDigest: "Tool: Write file: draft.txt — completed" }),
+    );
+    const requestIdx = prompt.indexOf("<user_request>");
+    const recoveryIdx = prompt.indexOf("<turn_recovery>");
+    const decisionsIdx = prompt.indexOf("APPROVED");
+    expect(requestIdx).toBeGreaterThan(-1);
+    expect(recoveryIdx).toBeGreaterThan(requestIdx);
+    expect(decisionsIdx).toBeGreaterThan(recoveryIdx);
+    expect(prompt).toContain("Tool: Write file: draft.txt — completed");
+    expect(prompt.trimEnd().endsWith("do not ask the user for permission in prose.")).toBe(true);
+  });
+
+  it("discloses the state loss even with NO transcript — otherwise the decisions read as reactions to proposals this agent never made", () => {
+    const prompt = buildPrompt(recoveryInput({ turnRecoveryDigest: undefined }));
+    expect(prompt).toContain("<turn_recovery>");
+    expect(prompt).toContain("no transcript of your progress is available");
+  });
+
+  it("preserves already-applied semantics: exact-applied writes are described as done, not as work to redo", () => {
+    const prompt = buildPrompt(
+      recoveryInput({ appliedToolCallIds: new Set(["tool-call-1"]) }),
+    );
+    expect(prompt).toContain("ALREADY applied");
+    expect(prompt).not.toContain("Carry them out now");
+  });
+
+  it("carries the session-standing context a first turn would get — the replacement agent inherits the whole story, not just the blueprint", () => {
+    const prompt = buildPrompt(
+      recoveryInput({ contextBridge: "User: earlier thread\nAssistant: earlier reply" }),
+    );
+    expect(prompt).toContain("<previous_conversation_context>");
+    expect(prompt).toContain("User: earlier thread");
+  });
+
+  it("selects the recovery shape for ANY non-resumed reason — decisions-only is safe only when native context is guaranteed", () => {
+    // created_first_execution + decisions cannot happen in practice
+    // (decisions are reconstructed from a persisted transcript, which
+    // implies a prior invocation) — but if it ever did, the bare decisions
+    // prompt would reproduce the #366 amnesia. Fail safe.
+    const prompt = buildPrompt(
+      recoveryInput({ resolution: resolution("local", "created_first_execution") }),
+    );
+    expect(prompt).toContain("<turn_recovery>");
+    expect(prompt).toContain("<agent_instructions>");
+  });
+
+  it("primary send skips images ONLY for a resumed HITL agent (which holds them natively); every fresh agent gets the re-delivery", () => {
+    expect(primarySendCarriesImages(decisions(), "resumed_successfully")).toBe(false);
+    // The #366 vision corollary: fresh agent mid-HITL after a
+    // resolution-time resume failure.
+    expect(primarySendCarriesImages(decisions(), "created_after_resume_failure")).toBe(true);
+    // Non-HITL turns always carry the message's images, resumed or not.
+    expect(primarySendCarriesImages(undefined, "resumed_successfully")).toBe(true);
+    expect(primarySendCarriesImages(undefined, "created_first_execution")).toBe(true);
+  });
+
+  it("the structured-output directive is a pure append shared by the primary and recovery sends — absent schema, absent suffix", () => {
+    expect(appendStructuredOutputDirective("base", undefined)).toBe("base");
+    const withSchema = appendStructuredOutputDirective("base", { type: "object" });
+    expect(withSchema.startsWith("base\n\n---\nCRITICAL OUTPUT REQUIREMENT:")).toBe(true);
+    expect(withSchema).toContain('"type": "object"');
+  });
+});
+
 describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)", () => {
   const RESUMED = { resolution: resolution("local", "resumed_successfully") };