@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/src/activities/execute-deep-agent/subagent-transformer.ts

@@ -15,12 +15,15 @@
  *   no approval gate — see deepagents-profiles.ts for the suppression half)
  * - Sub-agent backends are shell-capable outside plan mode (issue #248), mirroring
  *   the parent's backend selection in setup.ts
+ * - Sub-agent graphs carry the parent's filesystem permissions explicitly
+ *   (issue #255): pre-built CompiledSubAgents never inherit them, so plan
+ *   mode's deny-all-writes rule is baked into each graph at compile time
  * - Invalid configurations are logged and skipped (graceful degradation)
  * - Empty subagent list returns null (no subagents configured)
  */
 
 import { createDeepAgent, FilesystemBackend, LocalShellBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT } from "deepagents";
-import type { CompiledSubAgent } from "deepagents";
+import type { CompiledSubAgent, FilesystemPermission } from "deepagents";
 import type { StructuredTool } from "@langchain/core/tools";
 import type { RunnableConfig } from "@langchain/core/runnables";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
@@ -180,6 +183,18 @@ export interface SubagentTransformOptions {
    * backends, exactly like the parent's backend selection.
    */
   readonly shellEnv?: Record<string, string>;
+  /**
+   * Filesystem permission rules baked into each compiled sub-agent graph,
+   * inherited from the parent's rules in setup.ts (plan mode's deny-all-writes
+   * today). Required because deepagents' parent-permission inheritance covers
+   * only spec-style sub-agents — pre-built CompiledSubAgents bypass it, so
+   * without this a plan-mode sub-agent could still write (issue #255).
+   *
+   * Must not be combined with `shellEnv`: deepagents rejects permissions on an
+   * execution-capable backend (see the cas-capture-backend.ts header). Plan
+   * mode guarantees that by construction — it is the mode that clears shellEnv.
+   */
+  readonly permissions?: FilesystemPermission[];
 }
 
 // =========================================================================
@@ -525,6 +540,8 @@ export async function compileSubagents(
     readonly modelFactory?: (modelName: string) => Promise<BaseChatModel>;
     /** Shell env for `execute`; see {@link SubagentTransformOptions.shellEnv}. */
     readonly shellEnv?: Record<string, string>;
+    /** Per-graph filesystem rules; see {@link SubagentTransformOptions.permissions}. */
+    readonly permissions?: FilesystemPermission[];
   },
 ): Promise<CompiledSubAgent[]> {
   if (transformed.length === 0) return [];
@@ -537,11 +554,17 @@ export async function compileSubagents(
       // Structural coupling (DD-19): a sub-agent gate flows gitignored writes into
       // CAS iff a CAS observer backs that sub-agent's filesystem backend. Deriving
       // both from the same `casObserver` makes "unobserved unreviewable bytes"
-      // impossible by construction.
+      // impossible by construction. Same idiom for path normalization
+      // (issue #429): derived from the same `permissions` baked into the graph
+      // below, so a rule-bearing graph always carries the shim that keeps
+      // prompt-compliant relative paths from dying in rule validation.
       const middleware = buildSubAgentMiddleware({
         costCap: opts.costCap,
         approvalGate: opts.approvalGate,
         captureIgnored: !!opts.casObserver,
+        ...(opts.permissions?.length
+          ? { pathNormalization: { rootDir: opts.workspaceRootDir } }
+          : {}),
       });
 
       const modelName = spec.model ?? opts.parentModelName;
@@ -560,6 +583,9 @@ export async function compileSubagents(
         tools: spec.tools.length > 0 ? spec.tools : undefined,
         middleware: middleware as unknown[],
         backend,
+        // Enforced inside this graph's own filesystem tools — and inherited by
+        // any spec-style sub-agent deepagents auto-injects one level deeper.
+        ...(opts.permissions ? { permissions: opts.permissions } : {}),
       } as Parameters<typeof createDeepAgent>[0]);
 
       const gatedRunnable = gate.wrapRunnable(
@@ -623,6 +649,7 @@ export async function transformAndCompileSubagents(
     costCap,
     modelFactory,
     shellEnv,
+    permissions,
   } = options;
 
   if (subAgents.length === 0 && !workspaceBackend.rootDir) {
@@ -743,6 +770,7 @@ export async function transformAndCompileSubagents(
     casObserver,
     modelFactory,
     shellEnv,
+    permissions,
   });
 
   if (compiled.length === 0) {

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -2,6 +2,12 @@
  * Sub-agent middleware composition for ExecuteDeepAgent.
  *
  * Each sub-agent gets its own middleware stack with:
+ * - Path normalization (issue #429), FIRST and only on permission-rule-
+ *   bearing graphs (plan mode) — workspace-relative paths are rewritten to
+ *   workspace-absolute before deepagents' permission validation refuses
+ *   them, exactly as on the parent. `compileSubagents` derives it from the
+ *   same `permissions` option it bakes into the graph, keeping the rules
+ *   and their normalization shim coupled.
  * - Fresh loop detection (independent cycle tracking)
  * - Fresh tool truncation (same limits as parent)
  * - Periodic execution budget (interval=30, max=4 advisories)
@@ -9,11 +15,16 @@
  *   bypassed) — installed only when the parent itself is gated
  *   (`approvalGate` present; absent under auto-approve-all)
  * - Shared cost cap view (parent's budget, no reset on sub-agent start)
+ * - Error hints (issue #255): a thrown tool error becomes a recoverable
+ *   ToolMessage exactly as on the parent. Without it, any tool throw — a
+ *   plan-mode permission denial, an MCP hiccup — propagated out of the
+ *   sub-agent graph and killed the whole delegated task, losing all its
+ *   accumulated work, where the parent's identical error is one failed
+ *   tool round the model adapts to.
  *
  * The sub-agent middleware stack does NOT include:
  * - Graceful stop (parent handles STOP signal propagation)
  * - OTel spans (parent's OTel context propagates automatically)
- * - Error hints (applied at tool level, not sub-agent level)
  *
  * Approval-gate note: the gate is what *creates* the LangGraph `interrupt()`.
  * A sub-agent's interrupt does surface at the parent checkpoint and resumes
@@ -22,8 +33,13 @@
  * the live HITL bypass this wiring closes.
  */
 
-import type { StigmerMiddleware, ToolTruncationConfig } from "../../middleware/types.js";
+import type {
+  StigmerMiddleware,
+  ToolTruncationConfig,
+  PathNormalizationConfig,
+} from "../../middleware/types.js";
 import type { CostCapMiddleware } from "../../middleware/index.js";
+import { createPathNormalizationMiddleware } from "../../middleware/path-normalization.js";
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
 import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
@@ -31,6 +47,7 @@ import {
   createApprovalGateMiddleware,
   type ApprovalGateConfig,
 } from "../../middleware/approval-gate.js";
+import { createErrorHintsMiddleware } from "../../middleware/error-hints.js";
 
 const SUB_AGENT_ADVISORY_INTERVAL = 30;
 const SUB_AGENT_MAX_ADVISORIES = 4;
@@ -53,22 +70,36 @@ export interface SubAgentMiddlewareOptions {
    * unobserved backend would apply unreviewable bytes.
    */
   readonly captureIgnored?: boolean;
+  /**
+   * Workspace-relative path normalization (issue #429). Present iff this
+   * sub-agent's graph carries filesystem permission rules — the caller
+   * derives it from the same `permissions` value it bakes into the graph.
+   */
+  readonly pathNormalization?: PathNormalizationConfig;
 }
 
 /**
  * Build the middleware stack for a single sub-agent.
  *
  * Returns an ordered array mirroring the parent composition:
- * loop detection → execution budget (periodic) → tool truncation →
- * [approval gate] → cost cap view. The gate sits before the cost-cap view so an
- * approval pause happens before budget accounting, matching the parent order
- * (…→ truncation → graceful-stop → approval gate → cost cap …).
+ * [path normalization] → loop detection → execution budget (periodic) →
+ * tool truncation → [approval gate] → cost cap view → error hints.
+ * Normalization is outermost so everything downstream observes canonical
+ * workspace-absolute paths (matching the parent). The gate sits before the
+ * cost-cap view so an approval pause happens before budget accounting, and
+ * error hints come after the gate — both matching the parent order
+ * (…→ truncation → graceful-stop → approval gate → cost cap → error hints …),
+ * which keeps the gate's HITL interrupt outside the hints' try/catch.
  */
 export function buildSubAgentMiddleware(
   options: SubAgentMiddlewareOptions = {},
 ): StigmerMiddleware[] {
   const stack: StigmerMiddleware[] = [];
 
+  if (options.pathNormalization) {
+    stack.push(createPathNormalizationMiddleware(options.pathNormalization));
+  }
+
   stack.push(createLoopDetectionMiddleware({ enabled: true }));
 
   stack.push(createExecutionBudgetMiddleware({
@@ -99,5 +130,7 @@ export function buildSubAgentMiddleware(
     stack.push(options.costCap.forSubAgent());
   }
 
+  stack.push(createErrorHintsMiddleware());
+
   return stack;
 }

package/src/activities/hydrate-workflow-execution.ts

@@ -265,9 +265,14 @@ async function fetchAndFlattenEnv(
   client: StigmerClient,
   executionId: string,
 ): Promise<Record<string, unknown>> {
-  // A desktop runner exchanges its bootstrap credential for a token scoped to
-  // this workflow execution, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // The runner acquires a token scoped to this workflow execution so the
+  // server's decrypt gate binds the read: a desktop runner exchanges its
+  // bootstrap credential (#156, hard error on failure — the bootstrap
+  // credential no longer decrypts since stigmer-cloud#218, so proceeding
+  // would hydrate redacted placeholders), and an OSS runner asks the
+  // credential-less best-effort exchange (oss#535 — the OSS server redacts
+  // EC reads by default and mints execution-scoped tokens). No-op for cloud
+  // sandbox runners, whose ambient credential is already scoped.
   const scopedToken = await client.acquireScopedRunnerToken({
     workflowExecutionId: executionId,
   });

package/src/activities/run-command.ts

@@ -5,8 +5,11 @@
  * - RunScript: writes inline code to a temp file, executes via node/python
  * - RunShell: executes a shell command directly
  *
- * Both resolve runtime placeholders (JIT secrets) before execution
- * and capture stdout as the activity result.
+ * The child environment follows the declare-to-receive contract in
+ * run-env.ts: a minimal base plus the task's declared `environment`,
+ * with runtime placeholders (JIT secrets) resolved here in the activity
+ * so secret values never enter Temporal history. Both activities capture
+ * stdout as the activity result.
  */
 
 import { execFile, exec } from "node:child_process";
@@ -16,7 +19,9 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { ApplicationFailure } from "@temporalio/activity";
 import type { RunCommandConfig } from "../workflow-engine/types.js";
+import { RuntimePlaceholderResolutionError } from "../workflow-engine/resolve.js";
 import { startHeartbeat } from "../shared/heartbeat.js";
+import { buildRunEnv } from "./run-env.js";
 
 const execFileAsync = promisify(execFile);
 const execAsync = promisify(exec);
@@ -49,7 +54,7 @@ async function runScriptImpl(config: RunCommandConfig): Promise<unknown> {
 
   const language = config.language!;
   const code = config.code!;
-  const env = buildEnv(config.environment);
+  const env = buildTaskEnv(config);
 
   const ext = language === "js" ? ".js" : ".py";
   const interpreter = language === "js" ? "node" : "python3";
@@ -94,7 +99,7 @@ async function runShellImpl(config: RunCommandConfig): Promise<unknown> {
   const fullCommand = args.length > 0
     ? `${command} ${args.join(" ")}`
     : command;
-  const env = buildEnv(config.environment);
+  const env = buildTaskEnv(config);
 
   try {
     const { stdout } = await execAsync(fullCommand, {
@@ -116,16 +121,24 @@ async function runShellImpl(config: RunCommandConfig): Promise<unknown> {
   }
 }
 
-function buildEnv(
-  taskEnv?: Record<string, string>,
-): Record<string, string | undefined> {
-  const base = { ...process.env };
-  if (taskEnv) {
-    for (const [k, v] of Object.entries(taskEnv)) {
-      base[k] = v;
+/**
+ * Build the child env per the run-env.ts contract, translating a missing
+ * placeholder key into a non-retryable failure — retrying cannot conjure
+ * a variable the workflow's runtime env does not have.
+ */
+function buildTaskEnv(config: RunCommandConfig): Record<string, string> {
+  try {
+    return buildRunEnv(config.environment, config.runtimeEnv);
+  } catch (err: unknown) {
+    if (err instanceof RuntimePlaceholderResolutionError) {
+      throw ApplicationFailure.nonRetryable(
+        err.message,
+        "RUN_ENV_UNRESOLVED_PLACEHOLDER",
+        { variable: err.variableName },
+      );
     }
+    throw err;
   }
-  return base;
 }
 
 function buildArgsList(args: unknown): string[] {

package/src/activities/run-env.ts

@@ -0,0 +1,79 @@
+/**
+ * Environment contract for the workflow `run` task (shell and script modes).
+ *
+ * Declare-to-receive, the same rule the stdio MCP contract adopted after
+ * #256 (PR #383): the child process sees ONLY
+ *
+ *   1. a minimal base copied from the runner process
+ *      ({@link RUN_ENV_BASE_KEYS} — the six variables the MCP SDK pins),
+ *   2. the task's declared `environment` map, with `${.secrets.KEY}` /
+ *      `${.env_vars.KEY}` placeholders resolved just-in-time from the
+ *      workflow's runtime env. Resolution happens here in the activity,
+ *      never in the deterministic workflow phase, so secret values stay
+ *      out of Temporal history.
+ *
+ * Runner credentials (STIGMER_TOKEN, the HITL secret, provider keys) are
+ * structurally absent rather than denylisted — a workflow-authored
+ * `printenv` cannot read what was never passed (oss#384). A missing
+ * placeholder key fails loudly: running a command with a silently-empty
+ * credential produces cryptic downstream failures.
+ *
+ * Placeholders resolve only in declared environment VALUES, never in
+ * `command` / `code` strings — argv is visible to `ps` on the host, so
+ * the environment is the sanctioned channel for secrets.
+ */
+
+import { resolveRuntimePlaceholdersStrict } from "../workflow-engine/resolve.js";
+
+/**
+ * Base variables copied from the runner process when present — the same
+ * six the MCP SDK provides to stdio servers, so "undeclared subprocess
+ * environment" has one platform-wide answer. `PATH` keeps interpreters
+ * and tools findable; the rest keep shells and language runtimes sane.
+ */
+export const RUN_ENV_BASE_KEYS: readonly string[] = [
+  "HOME",
+  "LOGNAME",
+  "PATH",
+  "SHELL",
+  "TERM",
+  "USER",
+];
+
+/**
+ * Build the environment for a run task's child process: minimal base +
+ * declared overlay with strict placeholder resolution (declared wins on
+ * conflict with the base).
+ *
+ * @throws RuntimePlaceholderResolutionError when a declared value
+ *   references a runtime key that does not exist.
+ */
+export function buildRunEnv(
+  declaredEnv: Readonly<Record<string, string>> | undefined,
+  runtimeEnv: Readonly<Record<string, unknown>>,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of RUN_ENV_BASE_KEYS) {
+    const value = baseEnv[key];
+    if (value !== undefined) env[key] = value;
+  }
+
+  if (!declaredEnv || Object.keys(declaredEnv).length === 0) {
+    // The only case whose behavior changed in oss#384 (previously the
+    // child inherited the full runner env) — leave a trace for operators.
+    console.log("run task declares no environment — child receives the minimal base env only");
+    return env;
+  }
+
+  for (const [key, value] of Object.entries(declaredEnv)) {
+    env[key] = resolveRuntimePlaceholdersStrict(
+      value,
+      runtimeEnv,
+      `environment "${key}"`,
+    );
+  }
+
+  return env;
+}

package/src/activities/workflow-event-activities.ts

@@ -3,8 +3,12 @@
  *
  * Converts plain event descriptors (safe for the Temporal deterministic
  * sandbox) into WorkflowExecutionEvent proto objects and sends them
- * alongside a status update via gRPC. Best-effort — failures are logged
- * but do not fail the activity.
+ * alongside a status update via gRPC. Failures propagate so the local
+ * activity's retry policy fires — safe because sequence numbers are
+ * workflow-assigned (stable across attempts) and the store skips
+ * already-persisted sequences, making retries idempotent. The workflow's
+ * emit wrappers catch after retries are exhausted; event emission never
+ * fails a run.
  *
  * Registered as proxyLocalActivities in engine-core.ts so the workflow
  * sandbox can emit events at task boundaries and approval gates.
@@ -140,6 +144,17 @@ function buildClient(): StigmerClient {
   });
 }
 
+/**
+ * LEGACY sequence assignment — only for descriptors that arrive without a
+ * workflow-assigned `sequenceNumber`, i.e. replays of histories recorded
+ * before the "workflow-assigned-event-sequences" patch (see
+ * engine-core.ts). This counter is process-global: it is shared across
+ * every execution on the worker and resets on worker restart, which is
+ * the root cause of oss#308's silent event loss. Deliberately NOT fixed —
+ * pre-patch executions keep their old (flawed) behavior for the
+ * migration window. Delete together with the patch gate once pre-patch
+ * executions have drained.
+ */
 let sequenceCounter = 0;
 
 function nextSequence(): bigint {
@@ -148,33 +163,44 @@ function nextSequence(): bigint {
 }
 
 /**
- * Initialize the event sequence counter from the persisted high-water mark.
+ * Return the persisted event-log high-water mark for the execution, and
+ * seed the legacy process-global counter from it.
  *
- * On first run (no prior events), the counter stays at 0 and the first
- * event gets sequence_number = 1 — identical to the original behavior.
+ * The workflow seeds its own sequence counter from the returned value
+ * (patched path); the legacy global seed remains for pre-patch replays,
+ * whose emit path still assigns sequences here in the activity.
  *
- * On recovery (events already persisted from a failed run), the counter
- * is set to the highest persisted sequence_number so that new events
- * continue from N+1, avoiding duplicate-key collisions in storage.
+ * On first run (no prior events) returns 0, so the first event gets
+ * sequence_number = 1. On recovery (events already persisted from a
+ * failed run) returns the highest persisted sequence_number, so new
+ * events continue from N+1.
  *
  * When executionId is empty (direct executeServerlessWorkflow without a
- * persisted execution), the counter resets to 0 as a safe fallback.
+ * persisted execution), returns 0 as a safe fallback.
+ *
+ * Returns a plain number — the value crosses back into the workflow
+ * through Temporal's JSON payload converter, which cannot carry BigInt.
  */
-export async function initSequenceFromEventLog(executionId: string): Promise<void> {
+export async function initSequenceFromEventLog(executionId: string): Promise<number> {
   if (!executionId) {
     sequenceCounter = 0;
-    return;
+    return 0;
   }
   const client = buildClient();
   const highWaterMark = await client.getEventLogHighWaterMark(executionId);
   sequenceCounter = Number(highWaterMark);
+  return sequenceCounter;
 }
 
 /** @internal Exported for unit testing only. */
 export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEvent {
   const base = create(WorkflowExecutionEventSchema, {
     eventId: crypto.randomUUID(),
-    sequenceNumber: nextSequence(),
+    // Workflow-assigned sequence when present (stable across activity
+    // retries); legacy activity-side assignment only for pre-patch replays.
+    sequenceNumber: desc.sequenceNumber !== undefined
+      ? BigInt(desc.sequenceNumber)
+      : nextSequence(),
     occurredAt: desc.occurredAt,
     taskName: desc.taskName ?? "",
   });
@@ -382,6 +408,14 @@ export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEv
   return base;
 }
 
+/**
+ * Emit workflow events (with the accompanying status snapshot) to the
+ * server. Errors propagate so the local activity retry policy fires;
+ * retries are idempotent because workflow-assigned sequence numbers are
+ * stable across attempts and the store skips already-persisted ones. The
+ * workflow-side emit wrappers absorb the failure after retries are
+ * exhausted, so a broken timeline write never fails the run.
+ */
 export async function emitWorkflowEvents(
   executionId: string,
   events: WorkflowEventDescriptor[],
@@ -389,64 +423,57 @@ export async function emitWorkflowEvents(
 ): Promise<void> {
   if (!executionId || events.length === 0) return;
 
-  try {
-    const client = buildClient();
-    const protoEvents = events.map(toProtoEvent);
-
-    const protoTasks = (taskStatuses ?? []).map(ts =>
-      create(WorkflowTaskSchema, {
-        taskId: ts.taskId ?? "",
-        taskName: ts.taskName,
-        taskType: TASK_KIND_TO_TYPE_MAP[ts.taskKind] ?? WorkflowTaskType.WORKFLOW_TASK_TYPE_UNSPECIFIED,
-        status: TASK_STATUS_MAP[ts.status],
-        startedAt: ts.startedAt ?? "",
-        completedAt: ts.completedAt ?? "",
-        error: ts.error ?? "",
-        input: toJsonObject(ts.input),
-        output: toJsonObject(ts.output),
-        metadata: toJsonObject(ts.metadata),
-        costMicros: BigInt(ts.costMicros ?? 0),
-        inputTokens: BigInt(ts.inputTokens ?? 0),
-        outputTokens: BigInt(ts.outputTokens ?? 0),
-        uiHint: ts.uiHint ?? "",
-      }),
-    );
-
-    const startedEvent = events.find(e => e.type === "execution_started");
-    const completedEvent = events.find(e => e.type === "execution_completed");
-    const failedEvent = events.find(e => e.type === "execution_failed");
-
-    const statusFields: Record<string, unknown> = { tasks: protoTasks };
-
-    if (startedEvent) {
-      statusFields.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
-      statusFields.startedAt = startedEvent.occurredAt;
-    }
-    if (completedEvent && completedEvent.type === "execution_completed") {
-      statusFields.phase = ExecutionPhase.EXECUTION_COMPLETED;
-      statusFields.completedAt = completedEvent.occurredAt;
-      statusFields.totalCostMicros = BigInt(completedEvent.totalCostMicros);
-      statusFields.totalInputTokens = BigInt(completedEvent.totalInputTokens ?? 0);
-      statusFields.totalOutputTokens = BigInt(completedEvent.totalOutputTokens ?? 0);
-    }
-    if (failedEvent && failedEvent.type === "execution_failed") {
-      statusFields.phase = ExecutionPhase.EXECUTION_FAILED;
-      statusFields.completedAt = failedEvent.occurredAt;
-      statusFields.error = failedEvent.error;
-    }
-
-    const input = create(WorkflowExecutionUpdateStatusInputSchema, {
-      executionId,
-      status: create(WorkflowExecutionStatusSchema, statusFields as Parameters<typeof create>[1]),
-      events: protoEvents,
-    });
-    await client.workflowExecutionCommand.updateStatus(input);
-  } catch (err) {
-    console.error(
-      `Failed to emit ${events.length} workflow event(s) for ${executionId}:`,
-      err,
-    );
+  const client = buildClient();
+  const protoEvents = events.map(toProtoEvent);
+
+  const protoTasks = (taskStatuses ?? []).map(ts =>
+    create(WorkflowTaskSchema, {
+      taskId: ts.taskId ?? "",
+      taskName: ts.taskName,
+      taskType: TASK_KIND_TO_TYPE_MAP[ts.taskKind] ?? WorkflowTaskType.WORKFLOW_TASK_TYPE_UNSPECIFIED,
+      status: TASK_STATUS_MAP[ts.status],
+      startedAt: ts.startedAt ?? "",
+      completedAt: ts.completedAt ?? "",
+      error: ts.error ?? "",
+      input: toJsonObject(ts.input),
+      output: toJsonObject(ts.output),
+      metadata: toJsonObject(ts.metadata),
+      costMicros: BigInt(ts.costMicros ?? 0),
+      inputTokens: BigInt(ts.inputTokens ?? 0),
+      outputTokens: BigInt(ts.outputTokens ?? 0),
+      uiHint: ts.uiHint ?? "",
+    }),
+  );
+
+  const startedEvent = events.find(e => e.type === "execution_started");
+  const completedEvent = events.find(e => e.type === "execution_completed");
+  const failedEvent = events.find(e => e.type === "execution_failed");
+
+  const statusFields: Record<string, unknown> = { tasks: protoTasks };
+
+  if (startedEvent) {
+    statusFields.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+    statusFields.startedAt = startedEvent.occurredAt;
+  }
+  if (completedEvent && completedEvent.type === "execution_completed") {
+    statusFields.phase = ExecutionPhase.EXECUTION_COMPLETED;
+    statusFields.completedAt = completedEvent.occurredAt;
+    statusFields.totalCostMicros = BigInt(completedEvent.totalCostMicros);
+    statusFields.totalInputTokens = BigInt(completedEvent.totalInputTokens ?? 0);
+    statusFields.totalOutputTokens = BigInt(completedEvent.totalOutputTokens ?? 0);
+  }
+  if (failedEvent && failedEvent.type === "execution_failed") {
+    statusFields.phase = ExecutionPhase.EXECUTION_FAILED;
+    statusFields.completedAt = failedEvent.occurredAt;
+    statusFields.error = failedEvent.error;
   }
+
+  const input = create(WorkflowExecutionUpdateStatusInputSchema, {
+    executionId,
+    status: create(WorkflowExecutionStatusSchema, statusFields as Parameters<typeof create>[1]),
+    events: protoEvents,
+  });
+  await client.workflowExecutionCommand.updateStatus(input);
 }
 
 const PROTO_STATUS_TO_STRING: Record<number, string> = {

package/src/bootstrap.ts

@@ -120,6 +120,11 @@ export async function resolveRunnerBootstrap(
     // (OSS / no signing key) and is handled by the runner, not treated as fatal.
     runnerAccessToken: discovered.runnerAccessToken,
     runnerAccessTokenExpiresInSeconds: discovered.runnerAccessTokenExpiresInSeconds,
+    // Server-managed payload-encryption keys ride the same best-effort lane:
+    // absent on OSS (env-configured keys) and on cloud servers predating key
+    // management. Note the explicit-address and localhost branches above return
+    // none by construction — key management only exists where discovery does.
+    payloadEncryption: discovered.payloadEncryption,
   };
 }
 

package/src/claimcheck/payload-codec.ts

@@ -22,6 +22,14 @@ interface ClaimcheckMarker {
   key: string;
   size: number;
   compressed: boolean;
+  /**
+   * The relocated payload's original metadata, base64-encoded per value.
+   * Without it the restored payload would carry the marker's own
+   * "binary/claimcheck" encoding and no payload converter could interpret
+   * it. Absent on markers written before this field existed; those decode
+   * with the legacy (metadata-less) behavior.
+   */
+  metadata?: Record<string, string>;
 }
 
 export class ClaimcheckPayloadCodec implements PayloadCodec {
@@ -63,6 +71,7 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
       key,
       size: data.length,
       compressed,
+      metadata: serializeMetadata(payload.metadata),
     };
 
     return {
@@ -94,7 +103,9 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
     const dataBuf = marker.compressed ? decompress(rawBuf) : rawBuf;
 
     return {
-      metadata: payload.metadata,
+      metadata: marker.metadata
+        ? deserializeMetadata(marker.metadata)
+        : payload.metadata,
       data: dataBuf,
     };
   }
@@ -105,3 +116,24 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
     return Buffer.from(encoding).toString("utf-8") === MARKER_ENCODING_VALUE;
   }
 }
+
+function serializeMetadata(
+  metadata: Payload["metadata"],
+): Record<string, string> | undefined {
+  if (!metadata) return undefined;
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value) out[key] = Buffer.from(value).toString("base64");
+  }
+  return out;
+}
+
+function deserializeMetadata(
+  metadata: Record<string, string>,
+): Record<string, Uint8Array> {
+  const out: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    out[key] = Buffer.from(value, "base64");
+  }
+  return out;
+}