@awak-app/simy-cli 0.2.3 → 0.4.0

package/src/durable-local-task-worker.js

@@ -0,0 +1,2607 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { isIP } from "node:net";
+import {
+  access,
+  appendFile,
+  chmod,
+  lstat,
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import {
+  createLocalTask,
+  localTaskArtifact,
+  localTaskSnapshot,
+  persistLocalTask,
+  prepareLocalTaskWorkspace,
+  startLocalTask,
+  stopLocalTask,
+} from "./local-task.js";
+import {
+  buildLocalTaskArtifactRefs,
+  LocalTaskArtifactContractError,
+} from "./local-task-artifact-contract.js";
+import {
+  LOCAL_TASK_FILE_CAPABILITY_VERSION,
+  validateLocalTaskFile,
+} from "./local-task-file-capabilities.js";
+import {
+  normalizeLocalTaskScenarioPack,
+  validateLocalTaskScenarioInputs,
+} from "./local-task-scenario-packs.js";
+import {
+  buildControlledLocalTaskPlan,
+  durableLocalTaskStepApiContract,
+  durableLocalTaskStepExecutionId,
+  durableLocalTaskStepInstruction,
+  durableLocalTaskStepWorkspaceId,
+  isDurableLocalTaskStepClaim,
+  isLocalTaskPlanOrchestration,
+  normalizeDurableLocalTaskStepClaim,
+  normalizeDurableLocalTaskStepTransition,
+} from "./durable-local-task-steps-contract.js";
+import {
+  normalizeDurableLocalTaskExecutionClaimV2,
+} from "./bounded-local-task-subtasks-contract.js";
+import {
+  createBoundedLocalTaskSubtaskPool,
+} from "./bounded-local-task-subtask-pool.js";
+import {
+  webApiErrorMessage,
+  webApiHeaders,
+  webApiUrl,
+} from "./web-api.js";
+import { normalizeGitHubRemote } from "./workspace-context.js";
+
+const DEFAULT_LEASE_SECONDS = 120;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const ARTIFACT_UPLOAD_TIMEOUT_MS = 300_000;
+const CLAIM_LEASE_EXPIRY_TOLERANCE_MS = 30_000;
+const SUPPORTED_SCHEMA_VERSION = "local_task_execution.v1";
+const SUPPORTED_BACKENDS = new Set(["codex", "claude"]);
+const SUPPORTED_OPERATIONS = new Set(["observe", "read", "execute"]);
+const SUPPORTED_PERMISSION_MODES = new Set(["read_only", "workspace_write"]);
+const SUPPORTED_WORKSPACE_MODES = new Set(["task_sandbox", "repository"]);
+const MACHINE_CODE_PATTERN = /^[a-z][a-z0-9_]{0,127}$/;
+const REPOSITORY_OUTPUT_EXCLUDE = "/.simy/local-tasks/";
+const DURABLE_STEP_ATTACHMENT_MANIFEST_SCHEMA =
+  "durable_local_task_attachments.v1";
+const DURABLE_STEP_ATTACHMENT_MANIFEST_NAME =
+  "durable-step-attachments.v1.json";
+const execFileAsync = promisify(execFile);
+
+export class DurableLocalTaskApiError extends Error {
+  constructor(message, { status = null, code = null, ambiguous = false } = {}) {
+    super(message);
+    this.name = "DurableLocalTaskApiError";
+    this.status = status;
+    this.code = safeMachineCode(code, "durable_local_task_api_error");
+    this.ambiguous = ambiguous;
+  }
+}
+
+export function createDurableLocalTaskApi({
+  getConnection,
+  fetchImpl = globalThis.fetch,
+  requestTimeoutMs = REQUEST_TIMEOUT_MS,
+  artifactUploadTimeoutMs = ARTIFACT_UPLOAD_TIMEOUT_MS,
+} = {}) {
+  if (typeof getConnection !== "function") {
+    throw new TypeError("getConnection is required");
+  }
+  if (typeof fetchImpl !== "function") {
+    throw new TypeError("fetchImpl is required");
+  }
+
+  const request = async (path, body, { ambiguousOnTransport = false } = {}) => {
+    const connection = getConnection();
+    if (
+      !connection?.apiOrigin ||
+      !connection?.token
+    ) {
+      throw new DurableLocalTaskApiError(
+        "The SIMY CLI session is not connected.",
+        { code: "local_cli_session_unavailable" },
+      );
+    }
+    let response;
+    try {
+      response = await fetchImpl(
+        webApiUrl(path, {
+          webOrigin: connection.apiOrigin,
+          apiBaseUrl: connection.apiBaseUrl,
+        }),
+        {
+          method: "POST",
+          headers: webApiHeaders(
+            { token: connection.token },
+            { "Content-Type": "application/json" },
+          ),
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(requestTimeoutMs),
+        },
+      );
+    } catch (error) {
+      throw new DurableLocalTaskApiError(
+        `SIMY Web could not be reached: ${errorMessage(error)}`,
+        {
+          code: "local_task_gateway_unavailable",
+          ambiguous: ambiguousOnTransport,
+        },
+      );
+    }
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new DurableLocalTaskApiError(
+        webApiErrorMessage(payload, response.status),
+        {
+          status: response.status,
+          code: safeMachineCode(
+            payload?.code,
+            "durable_local_task_api_error",
+          ),
+        },
+      );
+    }
+    return payload;
+  };
+  const stepContract = durableLocalTaskStepApiContract();
+
+  return {
+    async claimSubtaskParent({
+      workerId,
+      leaseSeconds = DEFAULT_LEASE_SECONDS,
+      turnId = null,
+    }) {
+      const body = {
+        worker_id: workerId,
+        lease_seconds: leaseSeconds,
+      };
+      if (turnId !== null) body.turn_id = turnId;
+      return request("local-tasks/subtasks/parent-claim", body);
+    },
+    async claim({
+      workerId,
+      leaseSeconds = DEFAULT_LEASE_SECONDS,
+      turnId = null,
+      controlledPlan = null,
+    }) {
+      const body = {
+        worker_id: workerId,
+        lease_seconds: leaseSeconds,
+        turn_id: turnId,
+      };
+      if (controlledPlan !== null) body.controlled_plan = controlledPlan;
+      const payload = await request(
+        "local-tasks/claim",
+        body,
+        { ambiguousOnTransport: controlledPlan !== null },
+      );
+      if (isLocalTaskPlanOrchestration(payload)) return payload;
+      return payload?.claim ?? null;
+    },
+    async heartbeat({
+      turnId,
+      workerId,
+      leaseEpoch,
+      leaseSeconds = DEFAULT_LEASE_SECONDS,
+    }) {
+      const payload = await request(
+        `local-tasks/${encodeURIComponent(turnId)}/heartbeat`,
+        {
+          worker_id: workerId,
+          lease_epoch: leaseEpoch,
+          lease_seconds: leaseSeconds,
+        },
+      );
+      return {
+        ok: payload?.ok === true,
+        cancelRequested: payload?.cancel_requested === true,
+      };
+    },
+    async markInvocationStarted({ turnId, workerId, leaseEpoch }) {
+      const payload = await request(
+        `local-tasks/${encodeURIComponent(turnId)}/invocation-start`,
+        {
+          worker_id: workerId,
+          lease_epoch: leaseEpoch,
+        },
+        { ambiguousOnTransport: true },
+      );
+      return payload?.ok === true;
+    },
+    async updateStatus({
+      turnId,
+      workerId,
+      leaseEpoch,
+      status,
+      resultSummary = null,
+      artifactRefs = [],
+      failureCode = null,
+    }) {
+      const payload = await request(
+        `local-tasks/${encodeURIComponent(turnId)}/status`,
+        {
+          worker_id: workerId,
+          lease_epoch: leaseEpoch,
+          status,
+          result_summary: resultSummary,
+          artifact_refs: artifactRefs,
+          failure_code: failureCode,
+        },
+        { ambiguousOnTransport: true },
+      );
+      return payload?.ok === true;
+    },
+    async prepareArtifact({
+      turnId,
+      localArtifactId,
+      name,
+      mimeType,
+      sizeBytes,
+      sha256,
+    }) {
+      return request(
+        "local-tasks/artifacts/prepare",
+        {
+          turn_id: turnId,
+          local_artifact_id: localArtifactId,
+          name,
+          mime_type: mimeType,
+          size_bytes: sizeBytes,
+          sha256,
+        },
+        { ambiguousOnTransport: true },
+      );
+    },
+    async uploadArtifact({ uploadUrl, method = "PUT", headers = {}, bytes }) {
+      const target = trustedArtifactUploadUrl(uploadUrl);
+      const uploadHeaders = trustedArtifactUploadHeaders(headers);
+      if (method !== "PUT" || !Buffer.isBuffer(bytes)) {
+        throw new DurableLocalTaskApiError(
+          "SIMY Web returned an invalid Pipeline artifact upload.",
+          { code: "artifact_materialization_invalid_response" },
+        );
+      }
+      let response;
+      try {
+        response = await fetchImpl(target, {
+          method: "PUT",
+          headers: uploadHeaders,
+          body: bytes,
+          signal: AbortSignal.timeout(artifactUploadTimeoutMs),
+        });
+      } catch (error) {
+        throw new DurableLocalTaskApiError(
+          `SIMY could not upload the Local Task output: ${errorMessage(error)}`,
+          {
+            code: "local_task_artifact_upload_unavailable",
+            ambiguous: true,
+          },
+        );
+      }
+      if (!response.ok) {
+        throw new DurableLocalTaskApiError(
+          `SIMY artifact storage returned HTTP ${response.status}.`,
+          {
+            status: response.status,
+            code: "local_task_artifact_upload_failed",
+          },
+        );
+      }
+      return true;
+    },
+    async commitArtifact({
+      uploadId,
+      turnId,
+      localArtifactId,
+      sha256,
+      sizeBytes,
+    }) {
+      return request(
+        "local-tasks/artifacts/commit",
+        {
+          upload_id: uploadId,
+          turn_id: turnId,
+          local_artifact_id: localArtifactId,
+          sha256,
+          size_bytes: sizeBytes,
+        },
+        { ambiguousOnTransport: true },
+      );
+    },
+    async heartbeatStep(input) {
+      const contract = stepContract.heartbeat(input);
+      const payload = await request(
+        contract.path,
+        contract.body,
+        { ambiguousOnTransport: contract.ambiguousOnTransport },
+      );
+      return {
+        ok: payload?.ok === true,
+        cancelRequested: payload?.cancel_requested === true,
+      };
+    },
+    async markStepInvocationStarted(input) {
+      const contract = stepContract.invocationStart(input);
+      const payload = await request(
+        contract.path,
+        contract.body,
+        { ambiguousOnTransport: contract.ambiguousOnTransport },
+      );
+      return payload?.ok === true;
+    },
+    async updateStepStatus(input) {
+      const contract = stepContract.status(input);
+      const payload = await request(
+        contract.path,
+        contract.body,
+        { ambiguousOnTransport: contract.ambiguousOnTransport },
+      );
+      if (payload?.ok !== true) return false;
+      const {
+        ok: _ok,
+        ...transitionPayload
+      } = payload;
+      return {
+        ok: true,
+        transition: normalizeDurableLocalTaskStepTransition(
+          transitionPayload,
+          { completedStepId: input.stepId },
+        ),
+      };
+    },
+    async initialize_local_task_subtask_batch_v2(input) {
+      return request(
+        boundedSubtaskPath(input, "initialize"),
+        {
+          worker_id: input.p_worker_id,
+          parent_lease_epoch: input.p_parent_lease_epoch,
+          plan: input.p_plan,
+        },
+        { ambiguousOnTransport: true },
+      );
+    },
+    async claim_local_task_subtask_attempt_v2(input) {
+      return request(
+        boundedSubtaskPath(input, "claim"),
+        {
+          worker_id: input.p_worker_id,
+          parent_lease_epoch: input.p_parent_lease_epoch,
+          cancel_generation: input.p_cancel_generation,
+          lease_seconds: input.p_lease_seconds,
+          step_id: input.p_step_id,
+        },
+        { ambiguousOnTransport: true },
+      );
+    },
+    async heartbeat_local_task_subtask_attempt_v2(input) {
+      const payload = await request(
+        boundedSubtaskStepPath(input, "heartbeat"),
+        {
+          ...boundedSubtaskFenceBody(input),
+          lease_seconds: input.p_lease_seconds,
+        },
+      );
+      const cancelGeneration = payload?.cancel_generation;
+      if (
+        cancelGeneration !== undefined &&
+        (typeof cancelGeneration !== "string" ||
+          !/^(?:0|[1-9][0-9]*)$/.test(cancelGeneration))
+      ) {
+        throw new DurableLocalTaskApiError(
+          "SIMY Web returned an invalid bounded subtask heartbeat.",
+          { code: "local_task_subtask_invalid_response" },
+        );
+      }
+      return {
+        schema_version: payload?.schema_version,
+        ok: payload?.ok === true,
+        terminal: payload?.terminal === true,
+        attempt_state: payload?.attempt_state,
+        batch_state: payload?.batch_state,
+        cancel_requested: payload?.cancel_requested === true,
+        cancel_generation: cancelGeneration,
+        attempt_lease_epoch: payload?.attempt_lease_epoch,
+      };
+    },
+    async mark_local_task_subtask_invocation_started_v2(input) {
+      const payload = await request(
+        boundedSubtaskStepPath(input, "invocation-start"),
+        boundedSubtaskFenceBody(input),
+        { ambiguousOnTransport: true },
+      );
+      return (
+        payload?.schema_version === "local_task_subtask_transition.v2" &&
+        payload?.state === "started"
+      );
+    },
+    async complete_local_task_subtask_attempt_v2(input) {
+      const payload = await request(
+        boundedSubtaskStepPath(input, "status"),
+        {
+          ...boundedSubtaskFenceBody(input),
+          status: input.p_status,
+          result_summary: input.p_result_summary,
+          artifact_refs: input.p_artifact_refs,
+          provider_tokens_used: input.p_provider_tokens_used,
+          elapsed_ms: input.p_elapsed_ms,
+          failure_code: input.p_failure_code,
+        },
+        { ambiguousOnTransport: true },
+      );
+      return payload;
+    },
+    async abandon_local_task_subtask_attempt_v2(input) {
+      const payload = await request(
+        boundedSubtaskStepPath(input, "abandon"),
+        {
+          ...boundedSubtaskFenceBody(input),
+          reason: input.p_reason_code,
+        },
+        { ambiguousOnTransport: true },
+      );
+      return payload;
+    },
+    async download_local_task_subtask_source_v2({
+      turnId,
+      batchId,
+      stepId,
+      attemptId,
+      source,
+      signal = null,
+    }) {
+      const input = {
+        p_turn_id: turnId,
+        p_step_id: stepId,
+      };
+      const body = {
+        batch_id: batchId,
+        attempt_id: attemptId,
+        source_id: source?.source_id,
+        upload_id: source?.upload_id,
+        sha256: source?.sha256,
+      };
+      const payload = await request(
+        boundedSubtaskStepPath(input, "sources/download"),
+        body,
+      );
+      const prepared = validateSubtaskSourceDownload(payload, source);
+      let response;
+      try {
+        response = await fetchImpl(prepared.url, {
+          method: "GET",
+          headers: prepared.headers,
+          signal: signal
+            ? AbortSignal.any([
+                signal,
+                AbortSignal.timeout(artifactUploadTimeoutMs),
+              ])
+            : AbortSignal.timeout(artifactUploadTimeoutMs),
+        });
+      } catch (error) {
+        throw new DurableLocalTaskApiError(
+          `SIMY could not download the verified subtask source: ${errorMessage(error)}`,
+          {
+            code: "local_task_subtask_source_download_unavailable",
+          },
+        );
+      }
+      if (!response.ok) {
+        throw new DurableLocalTaskApiError(
+          `SIMY source storage returned HTTP ${response.status}.`,
+          {
+            status: response.status,
+            code: "local_task_subtask_source_download_failed",
+          },
+        );
+      }
+      return Buffer.from(await response.arrayBuffer());
+    },
+  };
+}
+
+function boundedSubtaskPath(input, operation) {
+  const turnId = String(input?.p_turn_id || "");
+  if (!isUuid(turnId)) {
+    throw new DurableLocalTaskApiError(
+      "The bounded Local Task turn ID is invalid.",
+      { code: "invalid_local_task_subtask_request" },
+    );
+  }
+  return (
+    `local-tasks/${encodeURIComponent(turnId)}` +
+    `/subtasks/${operation}`
+  );
+}
+
+function boundedSubtaskStepPath(input, operation) {
+  const stepId = String(input?.p_step_id || "");
+  if (!isUuid(stepId)) {
+    throw new DurableLocalTaskApiError(
+      "The bounded Local Task step ID is invalid.",
+      { code: "invalid_local_task_subtask_request" },
+    );
+  }
+  return (
+    boundedSubtaskPath(input, encodeURIComponent(stepId)) +
+    `/${operation}`
+  );
+}
+
+function boundedSubtaskFenceBody(input) {
+  return {
+    worker_id: input.p_worker_id,
+    parent_lease_epoch: input.p_parent_lease_epoch,
+    batch_id: input.p_batch_id,
+    attempt_id: input.p_attempt_id,
+    attempt_lease_epoch: input.p_attempt_lease_epoch,
+    cancel_generation: input.p_cancel_generation,
+  };
+}
+
+function validateSubtaskSourceDownload(value, expected) {
+  const topKeys = new Set(["schema_version", "source", "download"]);
+  const sourceKeys = new Set([
+    "source_id",
+    "name",
+    "mime_type",
+    "size_bytes",
+    "sha256",
+  ]);
+  const downloadKeys = new Set([
+    "url",
+    "method",
+    "headers",
+    "expires_at",
+  ]);
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some((key) => !topKeys.has(key)) ||
+    Object.keys(value).length !== topKeys.size ||
+    value.schema_version !== "local_task_subtask_source_download.v2" ||
+    !value.source ||
+    typeof value.source !== "object" ||
+    Array.isArray(value.source) ||
+    Object.keys(value.source).some((key) => !sourceKeys.has(key)) ||
+    Object.keys(value.source).length !== sourceKeys.size ||
+    value.source.source_id !== expected?.source_id ||
+    value.source.name !== expected?.name ||
+    value.source.mime_type !== expected?.mime_type ||
+    value.source.size_bytes !== expected?.size_bytes ||
+    String(value.source.sha256 || "").toLowerCase() !== expected?.sha256 ||
+    !value.download ||
+    typeof value.download !== "object" ||
+    Array.isArray(value.download) ||
+    Object.keys(value.download).some((key) => !downloadKeys.has(key)) ||
+    Object.keys(value.download).length !== downloadKeys.size ||
+    value.download.method !== "GET" ||
+    !Number.isFinite(Date.parse(value.download.expires_at)) ||
+    Date.parse(value.download.expires_at) <= Date.now()
+  ) {
+    throw new DurableLocalTaskApiError(
+      "SIMY Web returned an invalid bounded subtask source download.",
+      { code: "local_task_subtask_source_invalid_response" },
+    );
+  }
+  return {
+    url: trustedSubtaskSourceDownloadUrl(value.download.url),
+    headers: trustedArtifactUploadHeaders(value.download.headers),
+  };
+}
+
+export function createDurableLocalTaskWorker({
+  api,
+  registry,
+  storageRoot,
+  workspaceRoot,
+  resolveRepository = async () => null,
+  runLocalTask = startLocalTask,
+  prepareWorkspace = prepareLocalTaskWorkspace,
+  persist = persistLocalTask,
+  stopTask = stopLocalTask,
+  materializeArtifacts = materializePipelineArtifacts,
+  attachmentStore = null,
+  getDeviceId = () => null,
+  beginWork = () => () => {},
+  workerId = `simy-cli-${randomUUID()}`,
+  leaseSeconds = DEFAULT_LEASE_SECONDS,
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+  onError = () => {},
+  createSubtaskPool = createBoundedLocalTaskSubtaskPool,
+  runBoundedSubtask = null,
+} = {}) {
+  if (!api || typeof api.claim !== "function") {
+    throw new TypeError("api is required");
+  }
+  if (!registry || typeof registry.create !== "function") {
+    throw new TypeError("registry is required");
+  }
+
+  let closed = false;
+  let pollPromise = null;
+  let active = null;
+  let activeExecutionPromise = null;
+  let lastStepDisposition = null;
+  let pendingStepTurnId = null;
+  const boundedTasks = new Map();
+
+  const executeBoundedRuntime = runBoundedSubtask ?? (async (runtime, { signal }) => {
+    const startedAt = Date.now();
+    const task = createLocalTask({
+      id: runtime.workspace_id,
+      instruction: runtime.instruction,
+      backend: runtime.backend,
+      model: runtime.model,
+      operation: runtime.operation,
+      permissionMode: "read_only",
+      workspaceMode: "task_sandbox",
+      repository: null,
+      workspacePath: runtime.workspace_path,
+      taskRoot: runtime.task_root,
+      inputsRoot: runtime.inputs_root,
+      outputsRoot: runtime.outputs_root,
+      outputsRootExpected: runtime.outputs_root_expected,
+      attachments: runtime.verified_uploaded_inputs,
+      expectedOutputs: [],
+      providerTokenBudget: Number(runtime.provider_token_budget),
+      timeoutMs: Number(runtime.timeout_ms),
+    });
+    task.durable_turn_id = runtime.parent_turn_id;
+    task.durable_step_id = runtime.step_id;
+    await persist(task);
+    registry.create(task);
+    boundedTasks.set(runtime.attempt_id, task);
+    if (active) active.task = task;
+    const stopOnAbort = () => {
+      void stopTask(task).catch(() => undefined);
+    };
+    signal.addEventListener("abort", stopOnAbort, { once: true });
+    try {
+      const completed = await runLocalTask(task);
+      const status = completed.status === "succeeded"
+        ? "succeeded"
+        : completed.status === "stopped"
+          ? "cancelled"
+          : "failed";
+      return {
+        status,
+        result_summary:
+          completed.result?.summary ||
+          completed.error ||
+          `Bounded Local Task subtask ${status}.`,
+        provider_tokens_used: String(completed.provider_tokens_used || 0),
+        elapsed_ms: String(Math.max(0, Date.now() - startedAt)),
+        failure_code:
+          status === "failed"
+            ? safeMachineCode(
+                completed.reason_code,
+                "local_task_subtask_failed",
+              )
+            : null,
+      };
+    } finally {
+      signal.removeEventListener("abort", stopOnAbort);
+      boundedTasks.delete(runtime.attempt_id);
+    }
+  });
+
+  const executeStepClaim = async (claim, releaseWork) => {
+    let task = null;
+    let heartbeatTimer = null;
+    let heartbeatInFlight = null;
+    let knownLeaseExpiry = Number.NaN;
+    let boundary = "not_started";
+    let leaseLost = false;
+    let cancelRequested = false;
+    let normalized = null;
+    const executionStartedAt = Date.now();
+
+    const stopForLeaseLoss = async (error) => {
+      if (leaseLost) return;
+      leaseLost = true;
+      onError(
+        recoveryError(
+          "SIMY lost the durable step lease and stopped the local Provider to prevent duplicate work.",
+          error,
+          "local_task_step_lease_lost",
+        ),
+      );
+      if (task) await stopTask(task).catch(() => undefined);
+    };
+
+    try {
+      normalized = normalizeDurableLocalTaskStepClaim(claim, {
+        leaseSeconds,
+      });
+      if (normalized.disposition !== "execute") {
+        throw workerError(
+          normalized.disposition === "approval_required"
+            ? "This durable Local Task step is waiting for human approval."
+            : "The previous Provider result is unknown and cannot be replayed.",
+          normalized.disposition === "approval_required"
+            ? "local_task_step_approval_required"
+            : "local_task_step_provider_result_unknown",
+        );
+      }
+      knownLeaseExpiry = normalized.leaseExpiresAtMs;
+      const workspace = await resolveStepWorkspace(normalized, {
+        storageRoot,
+        workspaceRoot,
+        prepareWorkspace,
+        resolveRepository,
+      });
+      const attachments = await loadDurableStepAttachments({
+        turnId: normalized.turnId,
+        taskRoot: workspace.turn_task_root,
+        inputsRoot: workspace.inputs_root,
+      });
+      task = createLocalTask({
+        id: workspace.localTaskId,
+        instruction: durableLocalTaskStepInstruction(normalized),
+        backend: normalized.step.backend,
+        operation: normalized.step.operation,
+        permissionMode: normalized.step.permission_mode,
+        workspaceMode: normalized.step.workspace_mode,
+        repository: normalized.step.repository,
+        workspacePath: workspace.workspace_path,
+        taskRoot: workspace.task_root,
+        inputsRoot: workspace.inputs_root,
+        outputsRoot: workspace.outputs_root,
+        outputsRootExpected: workspace.outputs_root_expected,
+        attachments,
+        expectedOutputs: normalized.step.expected_outputs,
+        providerTokenBudget: Math.min(
+          normalized.step.provider_token_budget,
+          normalized.remainingProviderTokens,
+        ),
+        timeoutMs: Math.min(
+          normalized.step.timeout_ms,
+          normalized.remainingTimeoutMs,
+        ),
+      });
+      task.durable_turn_id = normalized.turnId;
+      task.durable_plan_id = normalized.plan.plan_id;
+      task.durable_plan_hash = normalized.plan.plan_hash;
+      task.durable_step_id = normalized.step.step_id;
+      task.durable_step_index = normalized.step.index;
+      task.durable_lease_epoch = normalized.leaseEpoch;
+      await persist(task);
+      registry.create(task);
+      if (active) active.task = task;
+
+      const heartbeat = async () => {
+        if (
+          !active ||
+          active.claim.turn_id !== normalized.turnId ||
+          leaseLost
+        ) {
+          return;
+        }
+        try {
+          const response = await api.heartbeatStep({
+            turnId: normalized.turnId,
+            stepId: normalized.step.step_id,
+            workerId,
+            leaseEpoch: normalized.leaseEpoch,
+            leaseSeconds,
+          });
+          if (response.ok !== true) {
+            await stopForLeaseLoss(
+              workerError(
+                "SIMY Web did not renew the durable step lease.",
+                "local_task_step_lease_not_renewed",
+              ),
+            );
+            return;
+          }
+          knownLeaseExpiry = Date.now() + leaseSeconds * 1_000;
+          if (response.cancelRequested) {
+            cancelRequested = true;
+            await stopTask(task);
+          }
+        } catch (error) {
+          if (
+            error instanceof DurableLocalTaskApiError &&
+            error.status === 409
+          ) {
+            await stopForLeaseLoss(error);
+            return;
+          }
+          onError(
+            recoveryError(
+              "SIMY could not renew this durable step yet; it will keep trying while the lease is safe.",
+              error,
+              "local_task_step_heartbeat_failed",
+            ),
+          );
+          if (
+            Number.isFinite(knownLeaseExpiry) &&
+            Date.now() + heartbeatIntervalMs >= knownLeaseExpiry
+          ) {
+            await stopForLeaseLoss(error);
+          }
+        }
+      };
+      const runHeartbeat = () => {
+        if (!heartbeatInFlight) {
+          heartbeatInFlight = heartbeat().finally(() => {
+            heartbeatInFlight = null;
+          });
+        }
+        return heartbeatInFlight;
+      };
+
+      heartbeatTimer = setIntervalImpl(() => {
+        void runHeartbeat();
+      }, heartbeatIntervalMs);
+      heartbeatTimer?.unref?.();
+
+      const completed = await runLocalTask(task, {
+        beforeProviderInvocation: async () => {
+          if (leaseLost || cancelRequested || closed) {
+            throw workerError(
+              "The durable step was stopped before the Provider started.",
+              "local_task_step_cancelled_before_invocation",
+            );
+          }
+          try {
+            await markInvocationStartedWithReplay(
+              {
+                markInvocationStarted: (input) =>
+                  api.markStepInvocationStarted({
+                    ...input,
+                    stepId: normalized.step.step_id,
+                  }),
+              },
+              {
+                turnId: normalized.turnId,
+                workerId,
+                leaseEpoch: normalized.leaseEpoch,
+              },
+            );
+            boundary = "started";
+          } catch (error) {
+            boundary = error?.ambiguous ? "unknown" : "not_started";
+            throw workerError(
+              error?.ambiguous
+                ? "SIMY could not confirm the durable step Provider boundary. This step will not be started again."
+                : `SIMY could not authorize the durable step Provider invocation: ${errorMessage(error)}`,
+              error?.ambiguous
+                ? "local_task_step_provider_result_unknown"
+                : "local_task_step_invocation_not_authorized",
+              error,
+            );
+          }
+        },
+      });
+
+      if (heartbeatTimer) {
+        clearIntervalImpl(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      await runHeartbeat();
+      if (leaseLost) return;
+      const status = completed.status === "stopped"
+        ? "cancelled"
+        : boundary === "unknown"
+          ? "unknown"
+          : completed.status === "succeeded"
+            ? "succeeded"
+            : "failed";
+      let reportStatus = status;
+      let reportFailureCode =
+        status === "failed" || status === "unknown"
+          ? safeMachineCode(completed.reason_code, "local_task_step_failed")
+          : null;
+      let reportSummary = durableResultSummary(
+        completed,
+        status,
+        reportFailureCode,
+      );
+      let artifactRefs = [];
+      try {
+        artifactRefs = buildLocalTaskArtifactRefs(
+          completed.artifacts,
+          completed.id,
+        );
+      } catch (error) {
+        artifactRefs = [];
+        if (status !== "cancelled") {
+          reportStatus = status === "unknown" ? "unknown" : "failed";
+          reportFailureCode = "artifact_verification_failed";
+          reportSummary =
+            "SIMY could not safely verify this durable step's output files.";
+          completed.status =
+            reportStatus === "failed" ? "failed" : completed.status;
+          completed.reason_code = reportFailureCode;
+          completed.error = error.message;
+          completed.artifacts = [];
+          if (completed.result) completed.result.artifacts = [];
+          await persist(completed);
+        }
+        onError(
+          recoveryError(
+            "SIMY rejected unsafe durable step output metadata before sending it to SIMY Web.",
+            error,
+            reportFailureCode,
+          ),
+        );
+      }
+      const statusInput = {
+        turnId: normalized.turnId,
+        stepId: normalized.step.step_id,
+        workerId,
+        leaseEpoch: normalized.leaseEpoch,
+        status: reportStatus,
+        resultSummary: reportSummary,
+        artifactRefs,
+        providerTokensUsed: completed.provider_tokens_used,
+        elapsedMs: Math.max(0, Date.now() - executionStartedAt),
+        failureCode: reportFailureCode,
+      };
+      let statusResolution;
+      try {
+        statusResolution = await updateStatusWithResolution(
+          {
+            updateStatus: (input) => api.updateStepStatus({
+              ...input,
+              stepId: normalized.step.step_id,
+              providerTokensUsed: statusInput.providerTokensUsed,
+              elapsedMs: statusInput.elapsedMs,
+            }),
+          },
+          statusInput,
+        );
+      } catch (error) {
+        onError(
+          recoveryError(
+            "SIMY completed the durable Provider step but could not save its final server state. It will not rerun the Provider.",
+            error,
+            "local_task_step_status_unavailable",
+          ),
+        );
+        return;
+      }
+      const statusConfirmed =
+        statusResolution === true || statusResolution?.ok === true;
+      if (!statusConfirmed) {
+        onError(
+          recoveryError(
+            "SIMY could not confirm the durable step's final server state. It will not rerun the Provider.",
+            new Error("The durable step lease was already fenced."),
+            "local_task_step_status_unconfirmed",
+          ),
+        );
+        return;
+      }
+      if (statusResolution?.transition?.status === "advanced") {
+        const transition = statusResolution.transition;
+        const nextStep = normalized.plan.steps[normalized.step.index + 1];
+        if (
+          reportStatus !== "succeeded" ||
+          transition.plan_id !== normalized.plan.plan_id ||
+          transition.current_step_id !== nextStep?.step_id ||
+          transition.current_step_index !== nextStep?.index + 1
+        ) {
+          onError(
+            recoveryError(
+              "SIMY Web returned an inconsistent durable plan handoff. The CLI stopped before starting another Provider.",
+              new Error("The authoritative step transition did not match the claimed plan."),
+              "local_task_plan_handoff_invalid",
+            ),
+          );
+          return;
+        }
+        pendingStepTurnId = normalized.turnId;
+      }
+    } catch (error) {
+      if (!leaseLost) {
+        onError(
+          recoveryError(
+            "SIMY could not execute this durable Local Task step safely.",
+            error,
+            safeMachineCode(error?.code, "durable_local_task_step_failed"),
+          ),
+        );
+        if (normalized?.disposition === "execute") {
+          const claimStatus = boundary === "not_started" ? "failed" : "unknown";
+          await api.updateStepStatus({
+            turnId: normalized.turnId,
+            stepId: normalized.step.step_id,
+            workerId,
+            leaseEpoch: normalized.leaseEpoch,
+            status: claimStatus,
+            resultSummary:
+              claimStatus === "unknown"
+                ? "SIMY could not confirm the Provider result and will not replay this durable step."
+                : safeResultSummary(
+                    `SIMY could not start this durable step. ${plainRecovery(error)}`,
+                  ),
+            artifactRefs: [],
+            providerTokensUsed: task?.provider_tokens_used || 0,
+            elapsedMs: Math.max(0, Date.now() - executionStartedAt),
+            failureCode: safeMachineCode(
+              error?.code,
+              "durable_local_task_step_failed",
+            ),
+          }).catch((statusError) => onError(statusError));
+        }
+      }
+    } finally {
+      if (heartbeatTimer) clearIntervalImpl(heartbeatTimer);
+      active = null;
+      releaseWork?.();
+    }
+  };
+
+  const executeClaim = async (claim, releaseWork) => {
+    if (isDurableLocalTaskStepClaim(claim)) {
+      return executeStepClaim(claim, releaseWork);
+    }
+    let task = null;
+    let heartbeatTimer = null;
+    let heartbeatInFlight = null;
+    let knownLeaseExpiry = Number.NaN;
+    let boundary = "not_started";
+    let leaseLost = false;
+    let cancelRequested = false;
+    let materializedAttachmentRefs = null;
+
+    const stopForLeaseLoss = async (error) => {
+      if (leaseLost) return;
+      leaseLost = true;
+      onError(
+        recoveryError(
+          "SIMY lost the execution lease and stopped the local Provider to prevent duplicate work.",
+          error,
+          "local_task_lease_lost",
+        ),
+      );
+      if (task) await stopTask(task).catch(() => undefined);
+    };
+
+    try {
+      const normalized = normalizeClaim(claim, { leaseSeconds });
+      knownLeaseExpiry = normalized.leaseExpiresAtMs;
+      const workspace = await resolveWorkspace(normalized, {
+        storageRoot,
+        workspaceRoot,
+        prepareWorkspace,
+        resolveRepository,
+      });
+      let attachments = [];
+      if (normalized.attachmentRefs.length > 0) {
+        if (!attachmentStore || typeof attachmentStore.materialize !== "function") {
+          throw workerError(
+            "Update SIMY CLI before running Local Tasks with attached files.",
+            "durable_local_task_attachments_unavailable",
+          );
+        }
+        const deviceId = getDeviceId();
+        attachments = await attachmentStore.materialize({
+          refs: normalized.attachmentRefs,
+          deviceId,
+          inputsRoot: workspace.inputs_root,
+        });
+        materializedAttachmentRefs = normalized.attachmentRefs;
+      }
+      validateLocalTaskScenarioInputs(normalized.scenarioPack, {
+        instruction: normalized.instruction,
+        attachments,
+      });
+      task = createLocalTask({
+        id: workspace.localTaskId,
+        instruction: normalized.instruction,
+        backend: normalized.spec.backend,
+        operation: normalized.spec.operation,
+        permissionMode: normalized.spec.permission_mode,
+        workspaceMode: normalized.spec.workspace_mode,
+        repository: normalized.spec.repository,
+        workspacePath: workspace.workspace_path,
+        taskRoot: workspace.task_root,
+        inputsRoot: workspace.inputs_root,
+        outputsRoot: workspace.outputs_root,
+        outputsRootExpected: workspace.outputs_root_expected,
+        attachments,
+        expectedOutputs: normalized.spec.expected_outputs,
+        scenarioPack: normalized.scenarioPack,
+        providerTokenBudget: normalized.spec.provider_token_budget,
+        timeoutMs: normalized.spec.timeout_ms,
+      });
+      task.durable_turn_id = normalized.turnId;
+      task.durable_lease_epoch = normalized.leaseEpoch;
+      await persist(task);
+      registry.create(task);
+      if (active) active.task = task;
+
+      const heartbeat = async () => {
+        if (!active || active.claim.turn_id !== normalized.turnId) return;
+        try {
+          const response = await api.heartbeat({
+            turnId: normalized.turnId,
+            workerId,
+            leaseEpoch: normalized.leaseEpoch,
+            leaseSeconds,
+          });
+          if (response.ok !== true) {
+            await stopForLeaseLoss(
+              workerError(
+                "SIMY Web did not renew the execution lease.",
+                "local_task_lease_not_renewed",
+              ),
+            );
+            return;
+          }
+          knownLeaseExpiry = Date.now() + leaseSeconds * 1_000;
+          if (response.cancelRequested) {
+            cancelRequested = true;
+            await stopTask(task);
+          }
+        } catch (error) {
+          if (
+            error instanceof DurableLocalTaskApiError &&
+            error.status === 409
+          ) {
+            await stopForLeaseLoss(error);
+            return;
+          }
+          onError(
+            recoveryError(
+              "SIMY could not renew this Local Task yet; it will keep trying while the lease is safe.",
+              error,
+              "local_task_heartbeat_failed",
+            ),
+          );
+          if (
+            Number.isFinite(knownLeaseExpiry) &&
+            Date.now() + heartbeatIntervalMs >= knownLeaseExpiry
+          ) {
+            await stopForLeaseLoss(error);
+          }
+        }
+      };
+      const runHeartbeat = () => {
+        if (!heartbeatInFlight) {
+          heartbeatInFlight = heartbeat().finally(() => {
+            heartbeatInFlight = null;
+          });
+        }
+        return heartbeatInFlight;
+      };
+
+      heartbeatTimer = setIntervalImpl(() => {
+        void runHeartbeat();
+      }, heartbeatIntervalMs);
+      heartbeatTimer?.unref?.();
+
+      const completed = await runLocalTask(task, {
+        beforeProviderInvocation: async () => {
+          if (leaseLost || cancelRequested || closed) {
+            throw workerError(
+              "The Local Task was stopped before the Provider started.",
+              "local_task_cancelled_before_invocation",
+            );
+          }
+          try {
+            await markInvocationStartedWithReplay(api, {
+              turnId: normalized.turnId,
+              workerId,
+              leaseEpoch: normalized.leaseEpoch,
+            });
+            boundary = "started";
+          } catch (error) {
+            boundary = error?.ambiguous ? "unknown" : "not_started";
+            throw workerError(
+              error?.ambiguous
+                ? "SIMY could not confirm whether the Provider boundary was recorded. The task was not started again."
+                : `SIMY could not authorize the Provider invocation: ${errorMessage(error)}`,
+              error?.ambiguous
+                ? "local_provider_boundary_unknown"
+                : "local_provider_invocation_not_authorized",
+              error,
+            );
+          }
+        },
+      });
+
+      if (heartbeatTimer) {
+        clearIntervalImpl(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      await runHeartbeat();
+      if (leaseLost) return;
+      // Report the Provider operation's observed outcome. A cancellation that
+      // arrives after Provider completion still cancels the parent Turn on the
+      // server, but must not rewrite a known successful operation as cancelled.
+      const status = completed.status === "stopped"
+        ? "cancelled"
+        : boundary === "unknown"
+          ? "unknown"
+          : completed.status === "succeeded"
+            ? "succeeded"
+            : "failed";
+      const failureCode =
+        status === "failed" || status === "unknown"
+          ? safeMachineCode(completed.reason_code, "local_task_failed")
+          : null;
+      let reportStatus = status;
+      let reportFailureCode = failureCode;
+      let reportSummary = durableResultSummary(completed, status, failureCode);
+      let artifactRefs = [];
+      try {
+        artifactRefs = buildLocalTaskArtifactRefs(completed.artifacts, completed.id);
+        if (
+          reportStatus === "succeeded" &&
+          normalized.pipelineContext &&
+          artifactRefs.length > 0
+        ) {
+          artifactRefs = await materializeArtifacts({
+            api,
+            turnId: normalized.turnId,
+            task: completed,
+            artifactRefs,
+          });
+        }
+      } catch (error) {
+        const contractFailure = error instanceof LocalTaskArtifactContractError;
+        // Pipeline status accepts only refs that already have a durable
+        // crew_artifact link. Keep locally verified files on disk for recovery,
+        // but never report an unmaterialized manifest to Backend.
+        artifactRefs = [];
+        if (status !== "cancelled") {
+          reportStatus = status === "unknown" ? "unknown" : "failed";
+          reportFailureCode = contractFailure
+            ? "artifact_verification_failed"
+            : "artifact_materialization_failed";
+          reportSummary =
+            contractFailure
+              ? "SIMY could not safely verify the Local Task output files."
+              : "SIMY created the output files locally but could not safely attach them to this Pipeline run. Keep SIMY CLI running, check the connection, and start a new Pipeline run.";
+          completed.status = reportStatus === "failed" ? "failed" : completed.status;
+          completed.reason_code = reportFailureCode;
+          completed.error = error.message;
+          if (contractFailure) {
+            completed.artifacts = [];
+            if (completed.result) completed.result.artifacts = [];
+          }
+          await persist(completed);
+        }
+        onError(contractFailure
+          ? recoveryError(
+              "SIMY rejected unsafe Local Task output metadata before sending it to SIMY Web.",
+              error,
+              reportFailureCode,
+            )
+          : workerError(
+              `SIMY could not persist the Local Task output files for this Pipeline run. ${errorMessage(error)} Keep SIMY CLI running, check the connection, and start a new Pipeline run.`,
+              reportFailureCode,
+              error,
+            ));
+      }
+      let statusConfirmed;
+      try {
+        statusConfirmed = await updateStatusWithResolution(api, {
+          turnId: normalized.turnId,
+          workerId,
+          leaseEpoch: normalized.leaseEpoch,
+          status: reportStatus,
+          resultSummary: reportSummary,
+          artifactRefs,
+          failureCode: reportFailureCode,
+        });
+      } catch (error) {
+        onError(
+          recoveryError(
+            "SIMY completed the local Provider call but could not save its final server state. It will not rerun the Provider.",
+            error,
+            "local_task_status_unavailable",
+          ),
+        );
+        return;
+      }
+      if (!statusConfirmed) {
+        onError(
+          recoveryError(
+            "SIMY stopped this Local Task but could not confirm its final server state. It will not rerun the Provider.",
+            new Error("The execution lease was already fenced."),
+            "local_task_status_unconfirmed",
+          ),
+        );
+      }
+    } catch (error) {
+      if (!leaseLost) {
+        onError(
+          recoveryError(
+            "SIMY could not execute this Local Task safely.",
+            error,
+            safeMachineCode(error?.code, "durable_local_task_failed"),
+          ),
+        );
+        const claimStatus =
+          boundary === "not_started" ? "failed" : "unknown";
+        const statusConfirmed = await updateStatusWithResolution(api, {
+          turnId: claim.turn_id,
+          workerId,
+          leaseEpoch: claim.lease_epoch,
+          status: claimStatus,
+          resultSummary:
+            claimStatus === "unknown"
+              ? "SIMY did not start this task again because the Provider boundary could not be confirmed. Check the task before retrying."
+              : safeResultSummary(
+                  `SIMY could not start this Local Task. ${plainRecovery(error)}`,
+                ),
+          artifactRefs: [],
+          failureCode: safeMachineCode(error?.code, "durable_local_task_failed"),
+        }).catch((statusError) => {
+          onError(statusError);
+          return false;
+        });
+        if (!statusConfirmed) {
+          onError(
+            recoveryError(
+              "SIMY will not rerun this Provider because the final task state could not be confirmed.",
+              new Error("The execution lease was already fenced."),
+              "local_task_status_unconfirmed",
+            ),
+          );
+        }
+      }
+    } finally {
+      if (heartbeatTimer) clearIntervalImpl(heartbeatTimer);
+      if (
+        materializedAttachmentRefs &&
+        boundary === "started" &&
+        attachmentStore &&
+        typeof attachmentStore.cleanup === "function"
+      ) {
+        await attachmentStore.cleanup({
+          refs: materializedAttachmentRefs,
+          deviceId: getDeviceId(),
+        }).catch((error) => onError(recoveryError(
+          "SIMY could not remove the staged attachment copy.",
+          error,
+          "local_task_attachment_cleanup_failed",
+        )));
+      }
+      active = null;
+      releaseWork?.();
+    }
+  };
+
+  return {
+    get workerId() {
+      return workerId;
+    },
+    snapshot() {
+      return {
+        closed,
+        polling: Boolean(pollPromise),
+        active_turn_id: active?.claim?.turn_id || null,
+        durable_step_disposition: lastStepDisposition,
+        pending_step_turn_id: pendingStepTurnId,
+        local_task: active?.task ? localTaskSnapshot(active.task) : null,
+      };
+    },
+    async poll() {
+      if (closed || active || pollPromise) return false;
+      const releaseWork = beginWork?.();
+      if (!releaseWork) return false;
+      pollPromise = (async () => {
+        try {
+          const requestedTurnId = pendingStepTurnId;
+          if (
+            !requestedTurnId &&
+            typeof api.claimSubtaskParent === "function"
+          ) {
+            const parentEnvelope = await api.claimSubtaskParent({
+              workerId,
+              leaseSeconds,
+            });
+            const parentClaim = normalizeDurableLocalTaskExecutionClaimV2(
+              parentEnvelope,
+              { workerId, leaseSeconds },
+            );
+            if (parentClaim.disposition === "claimed") {
+              const pool = createSubtaskPool({
+                api,
+                parentAuthority: parentClaim.parentAuthority,
+                batchPlan: parentClaim.batchPlan,
+                storageRoot,
+                workspaceRoot,
+                runSubtask: executeBoundedRuntime,
+                stopSubtask: async ({ attemptId }) => {
+                  const task = boundedTasks.get(attemptId);
+                  if (task) await stopTask(task);
+                },
+                prepareWorkspace,
+                leaseSeconds,
+                heartbeatIntervalMs,
+                setIntervalImpl,
+                clearIntervalImpl,
+                onError,
+              });
+              active = {
+                claim: { turn_id: parentClaim.turnId },
+                task: null,
+                subtaskPool: pool,
+              };
+              const executionPromise = pool.run()
+                .catch((error) => {
+                  onError(
+                    recoveryError(
+                      "SIMY could not finish the bounded Local Task pool safely.",
+                      error,
+                      "bounded_local_task_subtask_pool_failed",
+                    ),
+                  );
+                })
+                .finally(() => {
+                  active = null;
+                  releaseWork();
+                  if (activeExecutionPromise === executionPromise) {
+                    activeExecutionPromise = null;
+                  }
+                });
+              activeExecutionPromise = executionPromise;
+              void executionPromise;
+              return true;
+            }
+          }
+          let claim = await api.claim({
+            workerId,
+            leaseSeconds,
+            turnId: requestedTurnId,
+          });
+          if (!claim) {
+            if (requestedTurnId) {
+              throw workerError(
+                "SIMY Web advanced the durable plan but did not return its next step.",
+                "local_task_plan_handoff_unavailable",
+              );
+            }
+            releaseWork();
+            return false;
+          }
+          if (isLocalTaskPlanOrchestration(claim)) {
+            const orchestration = claim;
+            const controlledPlan = buildControlledLocalTaskPlan(orchestration);
+            await prepareDurableStepAttachments({
+              orchestration,
+              storageRoot,
+              workspaceRoot,
+              prepareWorkspace,
+              attachmentStore,
+              deviceId: getDeviceId(),
+              onError,
+            });
+            claim = await claimControlledPlanWithReplay(api, {
+              workerId,
+              leaseSeconds,
+              turnId: orchestration.turn_id,
+              controlledPlan,
+            });
+            if (!claim || isLocalTaskPlanOrchestration(claim)) {
+              throw workerError(
+                "SIMY Web did not initialize the controlled Local Task plan.",
+                "local_task_plan_not_initialized",
+              );
+            }
+            if (claim.turn_id !== orchestration.turn_id) {
+              throw workerError(
+                "SIMY Web returned a different Local Task after plan initialization.",
+                "local_task_plan_claim_mismatch",
+              );
+            }
+          }
+          if (requestedTurnId && claim.turn_id !== requestedTurnId) {
+            throw workerError(
+              "SIMY Web returned a different Local Task during the durable plan handoff.",
+              "local_task_plan_claim_mismatch",
+            );
+          }
+          if (isDurableLocalTaskStepClaim(claim)) {
+            const normalized = normalizeDurableLocalTaskStepClaim(claim, {
+              leaseSeconds,
+            });
+            lastStepDisposition = normalized.disposition;
+            if (requestedTurnId) pendingStepTurnId = null;
+            if (normalized.disposition !== "execute") {
+              // Approval checkpoints and unknown Provider results are durable
+              // Backend states, not executable leases. Keep no process,
+              // heartbeat, or update-manager work reservation while waiting.
+              releaseWork();
+              return false;
+            }
+          } else {
+            if (requestedTurnId) {
+              throw workerError(
+                "SIMY Web did not return a durable step for the advanced plan.",
+                "local_task_plan_handoff_invalid",
+              );
+            }
+            lastStepDisposition = null;
+          }
+          active = { claim, task: null };
+          const executionPromise = executeClaim(claim, releaseWork)
+            .catch((error) => {
+              onError(
+                recoveryError(
+                  "SIMY could not finish the active Local Task worker safely.",
+                  error,
+                  "durable_local_task_worker_failed",
+                ),
+              );
+            })
+            .finally(() => {
+              if (activeExecutionPromise === executionPromise) {
+                activeExecutionPromise = null;
+              }
+            });
+          activeExecutionPromise = executionPromise;
+          void executionPromise;
+          return true;
+        } catch (error) {
+          releaseWork();
+          onError(
+            recoveryError(
+              "SIMY could not check for My AI Local Tasks. Keep SIMY running; it will try again automatically.",
+              error,
+              "local_task_claim_failed",
+            ),
+          );
+          return false;
+        } finally {
+          pollPromise = null;
+        }
+      })();
+      return pollPromise;
+    },
+    async waitForIdle() {
+      await pollPromise;
+      await activeExecutionPromise;
+    },
+    async close() {
+      closed = true;
+      await pollPromise;
+      await active?.subtaskPool?.close?.().catch(() => undefined);
+      if (active?.task) await stopTask(active.task).catch(() => undefined);
+      await activeExecutionPromise;
+    },
+  };
+}
+
+async function claimControlledPlanWithReplay(api, input) {
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await api.claim(input);
+    } catch (error) {
+      lastError = error;
+      const retryable =
+        error?.ambiguous === true ||
+        (Number.isInteger(error?.status) && error.status >= 500);
+      if (!retryable || attempt > 0) throw error;
+    }
+  }
+  throw lastError;
+}
+
+async function markInvocationStartedWithReplay(api, input) {
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      if (await api.markInvocationStarted(input)) return true;
+      lastError = new DurableLocalTaskApiError(
+        "SIMY Web did not confirm the Provider boundary.",
+        { code: "local_provider_boundary_not_confirmed" },
+      );
+    } catch (error) {
+      lastError = error;
+      if (!error?.ambiguous || attempt > 0) throw error;
+    }
+  }
+  throw lastError;
+}
+
+async function updateStatusWithResolution(api, input) {
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await api.updateStatus(input);
+    } catch (error) {
+      lastError = error;
+      // A response can be lost after the durable transaction commits. A 409
+      // is not proof of commit: report it as unconfirmed, never rerun Provider.
+      if (error instanceof DurableLocalTaskApiError && error.status === 409) {
+        return false;
+      }
+      const retryable =
+        error?.ambiguous === true ||
+        (Number.isInteger(error?.status) && error.status >= 500);
+      if (!retryable || attempt > 0) throw error;
+    }
+  }
+  throw lastError;
+}
+
+function normalizeClaim(claim, { leaseSeconds, nowMs = Date.now() } = {}) {
+  const turnId = String(claim?.turn_id || "");
+  const leaseEpoch = Number(claim?.lease_epoch);
+  if (!/^[a-f0-9-]{36}$/i.test(turnId) || !Number.isInteger(leaseEpoch) || leaseEpoch < 1) {
+    throw workerError("SIMY Web returned an invalid Local Task lease.", "invalid_local_task_claim");
+  }
+  const leaseExpiresAtMs = Date.parse(claim?.lease_expires_at);
+  const maximumLeaseExpiry =
+    nowMs + Number(leaseSeconds) * 1_000 + CLAIM_LEASE_EXPIRY_TOLERANCE_MS;
+  if (
+    !Number.isFinite(leaseExpiresAtMs) ||
+    leaseExpiresAtMs <= nowMs ||
+    !Number.isFinite(maximumLeaseExpiry) ||
+    leaseExpiresAtMs > maximumLeaseExpiry
+  ) {
+    throw workerError(
+      "SIMY Web returned an invalid Local Task lease expiry.",
+      "invalid_local_task_claim",
+    );
+  }
+  const payload = claim.request_payload;
+  const spec = claim.execution_spec;
+  if (!payload || typeof payload !== "object" || payload.mode !== "local_task") {
+    throw workerError("SIMY Web returned an invalid Local Task request.", "invalid_local_task_request");
+  }
+  const instruction = String(payload.input || "").trim();
+  if (!instruction) {
+    throw workerError("The Local Task has no instruction.", "local_task_instruction_required");
+  }
+  const attachmentRefs = payload.attachment_refs ?? [];
+  if (!Array.isArray(attachmentRefs)) {
+    throw workerError(
+      "SIMY Web returned invalid attached-file references.",
+      "invalid_local_task_claim",
+    );
+  }
+  validateExecutionSpec(spec);
+  if (
+    attachmentRefs.length > 0 &&
+    spec.attachment_capability_version !== LOCAL_TASK_FILE_CAPABILITY_VERSION
+  ) {
+    throw workerError(
+      "Update SIMY CLI before running this Local Task with attached files.",
+      "unsupported_local_task_attachment_capability",
+    );
+  }
+  const pipelineContext = normalizePipelineContext(spec);
+  const scenarioPack = normalizeLocalTaskScenarioPack(spec.scenario_pack);
+  return {
+    turnId,
+    leaseEpoch,
+    leaseExpiresAtMs,
+    instruction,
+    attachmentRefs,
+    spec,
+    pipelineContext,
+    scenarioPack,
+  };
+}
+
+function normalizePipelineContext(spec) {
+  const value = spec?.origin;
+  if (value === null || value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw workerError(
+      "SIMY Web returned an invalid Pipeline Local Task binding.",
+      "invalid_local_task_claim",
+    );
+  }
+  const allowed = new Set([
+    "schema_version",
+    "kind",
+    "pipeline_run_id",
+    "block_run_id",
+    "node_key",
+    "artifact_delivery",
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    throw workerError(
+      "SIMY Web returned an invalid Pipeline Local Task binding.",
+      "invalid_local_task_claim",
+    );
+  }
+  const pipelineRunId = String(value.pipeline_run_id || "");
+  const blockRunId = String(value.block_run_id || "");
+  const nodeKey = String(value.node_key || "");
+  if (
+    value.schema_version !== "pipeline_local_task_origin.v1" ||
+    value.kind !== "pipeline_block" ||
+    value.artifact_delivery !== "crew_artifact_link_required" ||
+    !isUuid(pipelineRunId) ||
+    !isUuid(blockRunId) ||
+    !/^[A-Za-z0-9._:-]{1,128}$/.test(nodeKey)
+  ) {
+    throw workerError(
+      "SIMY Web returned an invalid Pipeline Local Task binding.",
+      "invalid_local_task_claim",
+    );
+  }
+  return {
+    pipeline_run_id: pipelineRunId,
+    block_run_id: blockRunId,
+    node_key: nodeKey,
+  };
+}
+
+function validateExecutionSpec(spec) {
+  if (!spec || typeof spec !== "object" || spec.schema_version !== SUPPORTED_SCHEMA_VERSION) {
+    throw workerError(
+      "Update SIMY CLI before running this Local Task.",
+      "unsupported_local_task_execution_spec",
+    );
+  }
+  if (!SUPPORTED_BACKENDS.has(spec.backend)) {
+    throw workerError("Unsupported Local Task Provider.", "unsupported_local_task_backend");
+  }
+  if (!SUPPORTED_OPERATIONS.has(spec.operation)) {
+    throw workerError("Unsupported Local Task operation.", "unsupported_local_task_operation");
+  }
+  if (!SUPPORTED_PERMISSION_MODES.has(spec.permission_mode)) {
+    throw workerError("Unsupported Local Task permission.", "unsupported_local_task_permission");
+  }
+  if (!SUPPORTED_WORKSPACE_MODES.has(spec.workspace_mode)) {
+    throw workerError("Unsupported Local Task workspace.", "unsupported_local_task_workspace");
+  }
+  if (Number(spec.max_provider_invocations) !== 1) {
+    throw workerError(
+      "Local Tasks must allow exactly one Provider invocation.",
+      "invalid_local_task_invocation_limit",
+    );
+  }
+  if (spec.operation !== "execute" && spec.permission_mode !== "read_only") {
+    throw workerError(
+      "Read-only Local Tasks cannot request workspace write access.",
+      "invalid_local_task_permission",
+    );
+  }
+  if (spec.workspace_mode === "repository" && !String(spec.repository || "").trim()) {
+    throw workerError(
+      "This Local Task requires a repository.",
+      "local_task_repository_required",
+    );
+  }
+}
+
+async function resolveWorkspace(
+  normalized,
+  { storageRoot, workspaceRoot, prepareWorkspace, resolveRepository },
+) {
+  const localTaskId =
+    `local_task_${normalized.turnId.replaceAll("-", "")}_${normalized.leaseEpoch}`;
+  const prepared = await prepareWorkspace({
+    taskId: localTaskId,
+    root: storageRoot,
+    workspaceRoot,
+  });
+  if (normalized.spec.workspace_mode !== "repository") {
+    return { ...prepared, localTaskId };
+  }
+  const repository = await resolveRepository(normalized.spec.repository);
+  if (!repository?.local_path) {
+    throw workerError(
+      `${normalized.spec.repository} is not available on this desktop. Open SIMY CLI and allow its repository folder, then try a new task.`,
+      "repository_not_authorized",
+    );
+  }
+  const repositoryWorkspace = await prepareRepositoryWorkspace({
+    repositoryPath: repository.local_path,
+    expectedRepository: normalized.spec.repository,
+    localTaskId,
+  });
+  return {
+    ...prepared,
+    localTaskId,
+    ...repositoryWorkspace,
+  };
+}
+
+async function resolveStepWorkspace(
+  normalized,
+  { storageRoot, workspaceRoot, prepareWorkspace, resolveRepository },
+) {
+  const workspaceId = durableLocalTaskStepWorkspaceId(normalized.turnId);
+  const localTaskId = durableLocalTaskStepExecutionId(
+    normalized.turnId,
+    normalized.step.step_id,
+    normalized.leaseEpoch,
+  );
+  const prepared = await prepareWorkspace({
+    taskId: workspaceId,
+    root: storageRoot,
+    workspaceRoot,
+  });
+  let resolved = prepared;
+  if (normalized.step.workspace_mode === "repository") {
+    const repository = await resolveRepository(normalized.step.repository);
+    if (!repository?.local_path) {
+      throw workerError(
+        `${normalized.step.repository} is not available on this desktop. Open SIMY CLI and allow its repository folder, then try again.`,
+        "repository_not_authorized",
+      );
+    }
+    resolved = {
+      ...prepared,
+      ...(await prepareRepositoryWorkspace({
+        repositoryPath: repository.local_path,
+        expectedRepository: normalized.step.repository,
+        localTaskId: workspaceId,
+      })),
+    };
+  }
+
+  const outputsRoot = path.join(
+    resolved.outputs_root,
+    normalized.step.step_id,
+  );
+  await mkdir(outputsRoot, { recursive: true, mode: 0o700 });
+  const outputDetails = await lstat(outputsRoot);
+  if (!outputDetails.isDirectory() || outputDetails.isSymbolicLink()) {
+    throw workerError(
+      "The durable step output directory is not safe to use.",
+      "local_task_output_path_unsafe",
+    );
+  }
+  const canonicalOutputsRoot = await realpath(outputsRoot);
+  const canonicalParent = await realpath(resolved.outputs_root);
+  if (
+    path.dirname(canonicalOutputsRoot) !== canonicalParent ||
+    path.basename(canonicalOutputsRoot) !== normalized.step.step_id
+  ) {
+    throw workerError(
+      "The durable step output directory escaped its turn workspace.",
+      "local_task_output_path_unsafe",
+    );
+  }
+
+  return {
+    ...resolved,
+    localTaskId,
+    turn_task_root: prepared.task_root,
+    // Persist each lease attempt independently while keeping inputs and the
+    // Provider workspace stable for the whole turn.
+    task_root: path.join(path.dirname(prepared.task_root), localTaskId),
+    outputs_root: canonicalOutputsRoot,
+    outputs_root_expected: canonicalOutputsRoot,
+  };
+}
+
+async function prepareDurableStepAttachments({
+  orchestration,
+  storageRoot,
+  workspaceRoot,
+  prepareWorkspace,
+  attachmentStore,
+  deviceId,
+  onError,
+}) {
+  const refs = orchestration?.request_payload?.attachment_refs ?? [];
+  if (!Array.isArray(refs)) {
+    throw workerError(
+      "SIMY Web returned invalid attached-file references.",
+      "invalid_local_task_claim",
+    );
+  }
+  if (refs.length === 0) return [];
+  if (
+    orchestration?.execution_spec?.attachment_capability_version !==
+    LOCAL_TASK_FILE_CAPABILITY_VERSION
+  ) {
+    throw workerError(
+      "Update SIMY CLI before running this Local Task with attached files.",
+      "unsupported_local_task_attachment_capability",
+    );
+  }
+  if (!attachmentStore || typeof attachmentStore.materialize !== "function") {
+    throw workerError(
+      "This SIMY CLI cannot safely receive attached files.",
+      "unsupported_local_task_attachment_capability",
+    );
+  }
+
+  const turnId = String(orchestration.turn_id || "");
+  const workspaceId = durableLocalTaskStepWorkspaceId(turnId);
+  const prepared = await prepareWorkspace({
+    taskId: workspaceId,
+    root: storageRoot,
+    workspaceRoot,
+  });
+  const sourceRefsSha256 = createHash("sha256")
+    .update(JSON.stringify(refs))
+    .digest("hex");
+  const existing = await loadDurableStepAttachments({
+    turnId,
+    taskRoot: prepared.task_root,
+    inputsRoot: prepared.inputs_root,
+    expectedSourceRefsSha256: sourceRefsSha256,
+    allowMissing: true,
+  });
+  if (existing) return existing;
+
+  const attachments = await attachmentStore.materialize({
+    refs,
+    deviceId,
+    inputsRoot: prepared.inputs_root,
+  });
+  await persistDurableStepAttachmentManifest({
+    turnId,
+    taskRoot: prepared.task_root,
+    sourceRefsSha256,
+    attachments,
+  });
+  if (typeof attachmentStore.cleanup === "function") {
+    await attachmentStore.cleanup({ refs, deviceId }).catch((error) =>
+      onError(
+        recoveryError(
+          "SIMY cached the attached files for this plan but could not remove their staging copy.",
+          error,
+          "local_task_attachment_cleanup_failed",
+        ),
+      ));
+  }
+  return attachments;
+}
+
+async function loadDurableStepAttachments({
+  turnId,
+  taskRoot,
+  inputsRoot,
+  expectedSourceRefsSha256 = null,
+  allowMissing = false,
+}) {
+  const manifestPath = path.join(
+    taskRoot,
+    DURABLE_STEP_ATTACHMENT_MANIFEST_NAME,
+  );
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    if (allowMissing && error?.code === "ENOENT") return null;
+    if (!allowMissing && error?.code === "ENOENT") return [];
+    throw workerError(
+      "SIMY could not verify the durable task attachment manifest.",
+      "local_task_attachment_manifest_invalid",
+      error,
+    );
+  }
+  if (
+    !manifest ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    manifest.schema_version !== DURABLE_STEP_ATTACHMENT_MANIFEST_SCHEMA ||
+    manifest.turn_id !== turnId ||
+    !/^[a-f0-9]{64}$/.test(manifest.source_refs_sha256) ||
+    (expectedSourceRefsSha256 !== null &&
+      manifest.source_refs_sha256 !== expectedSourceRefsSha256) ||
+    !Array.isArray(manifest.attachments)
+  ) {
+    throw workerError(
+      "SIMY rejected a mismatched durable task attachment manifest.",
+      "local_task_attachment_manifest_invalid",
+    );
+  }
+
+  const requestedInputsRoot = path.resolve(inputsRoot);
+  const canonicalInputsRoot = await realpath(requestedInputsRoot);
+  const verified = [];
+  for (const attachment of manifest.attachments) {
+    if (
+      !attachment ||
+      typeof attachment !== "object" ||
+      Array.isArray(attachment) ||
+      attachment.integrity_status !== "verified" ||
+      !Number.isInteger(attachment.size_bytes) ||
+      attachment.size_bytes < 0 ||
+      !/^[a-f0-9]{64}$/.test(attachment.sha256) ||
+      typeof attachment.local_path !== "string"
+    ) {
+      throw workerError(
+        "SIMY rejected invalid durable task attachment metadata.",
+        "local_task_attachment_manifest_invalid",
+      );
+    }
+    const candidate = path.resolve(attachment.local_path);
+    const relative = path.relative(requestedInputsRoot, candidate);
+    if (
+      relative === "" ||
+      relative.startsWith(`..${path.sep}`) ||
+      relative === ".." ||
+      path.isAbsolute(relative)
+    ) {
+      throw workerError(
+        "SIMY rejected a durable task attachment outside its input workspace.",
+        "local_task_attachment_path_unsafe",
+      );
+    }
+    const details = await lstat(candidate).catch(() => null);
+    if (!details?.isFile() || details.isSymbolicLink()) {
+      throw workerError(
+        "A durable task attachment is no longer a safe regular file.",
+        "local_task_attachment_path_unsafe",
+      );
+    }
+    const canonicalPath = await realpath(candidate);
+    if (path.dirname(canonicalPath) !== canonicalInputsRoot) {
+      throw workerError(
+        "SIMY rejected an unsafe durable task attachment path.",
+        "local_task_attachment_path_unsafe",
+      );
+    }
+    const bytes = await readFile(canonicalPath);
+    const validated = validateLocalTaskFile(
+      { ...attachment, bytes },
+      { direction: "input", requireBytes: true },
+    );
+    const attachmentId = String(attachment.id || "");
+    if (!/^attachment_[A-Za-z0-9-]{36}$/.test(attachmentId)) {
+      throw workerError(
+        "SIMY rejected an invalid durable task attachment identifier.",
+        "local_task_attachment_manifest_invalid",
+      );
+    }
+    verified.push({
+      id: attachmentId,
+      name: validated.name,
+      mime_type: validated.mime_type,
+      size_bytes: validated.size_bytes,
+      sha256: validated.sha256,
+      local_path: canonicalPath,
+      integrity_status: "verified",
+      executor_handoff_status: "pending",
+      storage: "managed_copy",
+      capability_version: validated.capability_version,
+    });
+  }
+  return verified;
+}
+
+async function persistDurableStepAttachmentManifest({
+  turnId,
+  taskRoot,
+  sourceRefsSha256,
+  attachments,
+}) {
+  await mkdir(taskRoot, { recursive: true, mode: 0o700 });
+  const manifestPath = path.join(
+    taskRoot,
+    DURABLE_STEP_ATTACHMENT_MANIFEST_NAME,
+  );
+  const temporaryPath = `${manifestPath}.${randomUUID()}.tmp`;
+  const payload = JSON.stringify({
+    schema_version: DURABLE_STEP_ATTACHMENT_MANIFEST_SCHEMA,
+    turn_id: turnId,
+    source_refs_sha256: sourceRefsSha256,
+    attachments,
+  });
+  try {
+    await writeFile(temporaryPath, payload, { flag: "wx", mode: 0o600 });
+    await rename(temporaryPath, manifestPath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+async function prepareRepositoryWorkspace({
+  repositoryPath,
+  expectedRepository,
+  localTaskId,
+}) {
+  const candidate = path.resolve(String(repositoryPath || ""));
+  const candidateDetails = await lstat(candidate).catch(() => null);
+  if (!candidateDetails?.isDirectory() || candidateDetails.isSymbolicLink()) {
+    throw workerError(
+      "The selected repository folder is not safe to use.",
+      "repository_not_authorized",
+    );
+  }
+  const repositoryRoot = await realpath(candidate);
+  const gitRoot = await gitOutput(repositoryRoot, [
+    "rev-parse",
+    "--show-toplevel",
+  ]).catch(() => "");
+  const canonicalGitRoot = gitRoot
+    ? await realpath(path.resolve(gitRoot)).catch(() => "")
+    : "";
+  if (!canonicalGitRoot || canonicalGitRoot !== repositoryRoot) {
+    throw workerError(
+      "The selected folder is not the root of an available Git repository.",
+      "repository_not_authorized",
+    );
+  }
+  const currentRemote = await gitOutput(repositoryRoot, [
+    "remote",
+    "get-url",
+    "origin",
+  ]).catch(() => "");
+  if (
+    normalizeGitHubRemote(currentRemote)?.toLowerCase() !==
+    normalizeGitHubRemote(expectedRepository)?.toLowerCase()
+  ) {
+    throw workerError(
+      "The selected repository no longer matches the repository authorized in SIMY CLI. Scan repositories again, then start a new task.",
+      "repository_not_authorized",
+    );
+  }
+
+  const trackedOutputs = await gitOutput(repositoryRoot, [
+    "ls-files",
+    "--",
+    ".simy/local-tasks",
+  ]);
+  if (trackedOutputs.trim()) {
+    throw workerError(
+      "This repository already tracks .simy/local-tasks. Remove it from version control before running a Local Task.",
+      "repository_output_path_tracked",
+    );
+  }
+
+  await assertExistingRepositoryPathSafe(
+    repositoryRoot,
+    [".simy", "local-tasks", localTaskId, "outputs"],
+  );
+  await ensureRepositoryOutputExcluded(repositoryRoot);
+  const taskRoot = await ensureSafeRepositoryDirectory(
+    repositoryRoot,
+    [".simy", "local-tasks", localTaskId],
+  );
+  const outputsRoot = await ensureSafeRepositoryDirectory(
+    repositoryRoot,
+    [".simy", "local-tasks", localTaskId, "outputs"],
+  );
+  await chmod(taskRoot, 0o700);
+  await chmod(outputsRoot, 0o700);
+  await access(outputsRoot, fsConstants.W_OK);
+  return {
+    workspace_path: repositoryRoot,
+    outputs_root: outputsRoot,
+    outputs_root_expected: outputsRoot,
+  };
+}
+
+async function assertExistingRepositoryPathSafe(repositoryRoot, segments) {
+  let current = repositoryRoot;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    const details = await lstat(current).catch((error) => {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    });
+    if (!details) return;
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+      throw workerError(
+        "The repository Local Task output path is not a safe directory.",
+        "repository_output_path_unsafe",
+      );
+    }
+  }
+}
+
+async function ensureSafeRepositoryDirectory(repositoryRoot, segments) {
+  let current = repositoryRoot;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    let details = await lstat(current).catch((error) => {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    });
+    if (!details) {
+      await mkdir(current, { mode: 0o700 });
+      details = await lstat(current);
+    }
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+      throw workerError(
+        "The repository Local Task output path is not a safe directory.",
+        "repository_output_path_unsafe",
+      );
+    }
+  }
+  const canonical = await realpath(current);
+  if (!isWithin(repositoryRoot, canonical)) {
+    throw workerError(
+      "The repository Local Task output path escapes the repository.",
+      "repository_output_path_unsafe",
+    );
+  }
+  return canonical;
+}
+
+async function ensureRepositoryOutputExcluded(repositoryRoot) {
+  const commonDirectoryValue = await gitOutput(repositoryRoot, [
+    "rev-parse",
+    "--git-common-dir",
+  ]);
+  const commonDirectory = await realpath(
+    path.resolve(repositoryRoot, commonDirectoryValue),
+  );
+  const excludePath = path.join(commonDirectory, "info", "exclude");
+  const excludeParent = path.dirname(excludePath);
+  await mkdir(excludeParent, { recursive: true, mode: 0o700 });
+  const canonicalParent = await realpath(excludeParent);
+  if (!isWithin(commonDirectory, canonicalParent)) {
+    throw workerError(
+      "The repository Git exclude path is not safe.",
+      "repository_output_path_unsafe",
+    );
+  }
+  const existingDetails = await lstat(excludePath).catch((error) => {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  });
+  if (existingDetails?.isSymbolicLink() || existingDetails?.isDirectory()) {
+    throw workerError(
+      "The repository Git exclude file is not safe.",
+      "repository_output_path_unsafe",
+    );
+  }
+  const existing = await readFile(excludePath, "utf8").catch((error) => {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  });
+  if (
+    existing
+      .split(/\r?\n/)
+      .some((line) => line.trim() === REPOSITORY_OUTPUT_EXCLUDE)
+  ) {
+    return;
+  }
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  await appendFile(
+    excludePath,
+    `${prefix}${REPOSITORY_OUTPUT_EXCLUDE}\n`,
+    { encoding: "utf8", mode: 0o600 },
+  );
+}
+
+async function gitOutput(repositoryRoot, args) {
+  const { stdout } = await execFileAsync("git", ["-C", repositoryRoot, ...args], {
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024,
+  });
+  return stdout.trim();
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export async function materializePipelineArtifacts({
+  api,
+  turnId,
+  task,
+  artifactRefs,
+}) {
+  if (
+    !api ||
+    typeof api.prepareArtifact !== "function" ||
+    typeof api.uploadArtifact !== "function" ||
+    typeof api.commitArtifact !== "function"
+  ) {
+    throw workerError(
+      "This SIMY CLI cannot persist Pipeline output files. Update SIMY CLI and retry the Pipeline run.",
+      "artifact_materialization_unsupported",
+    );
+  }
+
+  const materialized = [];
+  for (const ref of artifactRefs) {
+    const artifact = await localTaskArtifact(task, ref.id);
+    if (!artifact) {
+      throw workerError(
+        `The Local Task output ${ref.name} changed before it could be attached to the Pipeline run.`,
+        "artifact_materialization_source_changed",
+      );
+    }
+    const bytes = await readFile(artifact.local_path);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (bytes.byteLength !== ref.size_bytes || digest !== ref.sha256.toLowerCase()) {
+      throw workerError(
+        `The Local Task output ${ref.name} changed before it could be attached to the Pipeline run.`,
+        "artifact_materialization_source_changed",
+      );
+    }
+
+    const prepared = await retryAmbiguousArtifactStep(() =>
+      api.prepareArtifact({
+        turnId,
+        localArtifactId: ref.id,
+        name: ref.name,
+        mimeType: ref.mime_type,
+        sizeBytes: ref.size_bytes,
+        sha256: ref.sha256.toLowerCase(),
+      }));
+    validatePreparedArtifact(prepared);
+    await retryAmbiguousArtifactStep(() =>
+      api.uploadArtifact({
+        uploadUrl: prepared.upload_url,
+        method: prepared.method,
+        headers: prepared.headers,
+        bytes,
+      }));
+    const committed = await retryAmbiguousArtifactStep(() =>
+      api.commitArtifact({
+        uploadId: prepared.upload_id,
+        turnId,
+        localArtifactId: ref.id,
+        sha256: ref.sha256.toLowerCase(),
+        sizeBytes: ref.size_bytes,
+      }));
+    materialized.push(validateCommittedArtifact(committed, ref));
+  }
+  return materialized;
+}
+
+async function retryAmbiguousArtifactStep(operation) {
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      const retryable =
+        error?.ambiguous === true ||
+        (Number.isInteger(error?.status) && error.status >= 500);
+      if (!retryable || attempt > 0) throw error;
+    }
+  }
+  throw lastError;
+}
+
+function validatePreparedArtifact(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !/^[A-Za-z0-9._:-]{1,256}$/.test(String(value.upload_id || "")) ||
+    value.method !== "PUT" ||
+    !value.headers ||
+    typeof value.headers !== "object" ||
+    Array.isArray(value.headers)
+  ) {
+    throw workerError(
+      "SIMY Web returned an invalid Pipeline artifact upload.",
+      "artifact_materialization_invalid_response",
+    );
+  }
+  trustedArtifactUploadUrl(value.upload_url);
+  trustedArtifactUploadHeaders(value.headers);
+}
+
+function validateCommittedArtifact(value, expected) {
+  const artifact = value?.crew_artifact;
+  if (
+    !artifact ||
+    typeof artifact !== "object" ||
+    !isUuid(String(artifact.artifact_id || "")) ||
+    !/^s3:\/\/[^/]+\/.+/.test(String(artifact.s3_uri || "")) ||
+    artifact.name !== expected.name ||
+    artifact.mime_type !== expected.mime_type ||
+    artifact.size_bytes !== expected.size_bytes ||
+    String(artifact.sha256 || "").toLowerCase() !== expected.sha256.toLowerCase()
+  ) {
+    throw workerError(
+      "SIMY could not confirm the persisted Pipeline output file.",
+      "artifact_materialization_invalid_response",
+    );
+  }
+  return {
+    artifact_id: artifact.artifact_id,
+    s3_uri: artifact.s3_uri,
+    name: artifact.name,
+    mime_type: artifact.mime_type,
+    size_bytes: artifact.size_bytes,
+    sha256: artifact.sha256.toLowerCase(),
+    verified: true,
+  };
+}
+
+function trustedArtifactUploadUrl(value) {
+  let target;
+  try {
+    target = new URL(String(value || ""));
+  } catch {
+    throw workerError(
+      "SIMY Web returned an invalid Pipeline artifact upload address.",
+      "artifact_materialization_invalid_response",
+    );
+  }
+  const localHttp =
+    target.protocol === "http:" &&
+    ["127.0.0.1", "localhost", "[::1]"].includes(target.hostname);
+  const awsS3 =
+    target.protocol === "https:" &&
+    /^(?:[a-z0-9][a-z0-9.-]*\.)?s3(?:[.-][a-z0-9-]+)*\.amazonaws\.com$/i.test(
+      target.hostname,
+    );
+  if (target.username || target.password || (!awsS3 && !localHttp)) {
+    throw workerError(
+      "SIMY Web returned an unsafe Pipeline artifact upload address.",
+      "artifact_materialization_invalid_response",
+    );
+  }
+  return target;
+}
+
+function trustedSubtaskSourceDownloadUrl(value) {
+  let target;
+  try {
+    target = new URL(String(value || ""));
+  } catch {
+    throw workerError(
+      "SIMY Web returned an invalid bounded subtask download address.",
+      "local_task_subtask_source_invalid_response",
+    );
+  }
+  const hostname = target.hostname.toLowerCase();
+  const localHttp =
+    target.protocol === "http:" &&
+    ["127.0.0.1", "localhost", "[::1]"].includes(hostname);
+  const publicHttps =
+    target.protocol === "https:" &&
+    !isLocalOrPrivateHostname(hostname);
+  if (
+    target.username ||
+    target.password ||
+    target.port === "0" ||
+    (!publicHttps && !localHttp)
+  ) {
+    throw workerError(
+      "SIMY Web returned an unsafe bounded subtask download address.",
+      "local_task_subtask_source_invalid_response",
+    );
+  }
+  return target;
+}
+
+function isLocalOrPrivateHostname(hostname) {
+  if (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost")
+  ) {
+    return true;
+  }
+  const literal = hostname.startsWith("[") && hostname.endsWith("]")
+    ? hostname.slice(1, -1)
+    : hostname;
+  const ipVersion = isIP(literal);
+  if (ipVersion === 4) return isNonPublicIpv4(literal);
+  if (ipVersion !== 6) return false;
+  const normalized = literal.toLowerCase();
+  if (
+    normalized === "::" ||
+    normalized === "::1" ||
+    normalized.startsWith("fc") ||
+    normalized.startsWith("fd") ||
+    /^fe[89ab]/.test(normalized)
+  ) {
+    return true;
+  }
+  const mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  return mapped ? isNonPublicIpv4(mapped[1]) : false;
+}
+
+function isNonPublicIpv4(value) {
+  const octets = value.split(".").map(Number);
+  if (
+    octets.length !== 4 ||
+    octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)
+  ) {
+    return true;
+  }
+  const [first, second] = octets;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168) ||
+    (first === 198 && (second === 18 || second === 19)) ||
+    first >= 224
+  );
+}
+
+function trustedArtifactUploadHeaders(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw workerError(
+      "SIMY Web returned invalid Pipeline artifact upload headers.",
+      "artifact_materialization_invalid_response",
+    );
+  }
+  const headers = {};
+  for (const [key, rawValue] of Object.entries(value)) {
+    const normalizedKey = String(key).trim().toLowerCase();
+    if (
+      !normalizedKey ||
+      ["authorization", "cookie", "proxy-authorization", "host"].includes(normalizedKey) ||
+      typeof rawValue !== "string" ||
+      /[\r\n]/.test(rawValue)
+    ) {
+      throw workerError(
+        "SIMY Web returned unsafe Pipeline artifact upload headers.",
+        "artifact_materialization_invalid_response",
+      );
+    }
+    headers[normalizedKey] = rawValue;
+  }
+  return headers;
+}
+
+function isUuid(value) {
+  return /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(
+    value,
+  );
+}
+
+function recoverySummary(status, failureCode) {
+  if (status === "cancelled") return "The Local Task was stopped.";
+  if (status === "unknown") {
+    return "SIMY could not confirm the Provider result. Review the task before retrying.";
+  }
+  return `The Local Task failed (${failureCode || "unknown error"}).`;
+}
+
+function durableResultSummary(completed, status, failureCode) {
+  // Process exit details such as signal-derived code 130 are useful only in
+  // the local technical record. A user-requested stop has one stable public
+  // outcome regardless of how the Provider process terminated.
+  if (status === "cancelled") return recoverySummary(status, failureCode);
+  return safeResultSummary(
+    completed.result?.summary ||
+      completed.error ||
+      recoverySummary(status, failureCode),
+  );
+}
+
+function safeResultSummary(value) {
+  return String(value || "").slice(0, 20_000);
+}
+
+function workerError(message, code, cause = null) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = safeMachineCode(code, "durable_local_task_failed");
+  return error;
+}
+
+function safeMachineCode(value, fallback) {
+  const candidate = typeof value === "string" ? value.trim() : "";
+  return MACHINE_CODE_PATTERN.test(candidate) ? candidate : fallback;
+}
+
+function recoveryError(message, error, code) {
+  return workerError(`${message} ${plainRecovery(error)}`, code, error);
+}
+
+function plainRecovery(error) {
+  const detail = errorMessage(error);
+  return detail
+    ? `${detail} Keep SIMY CLI running and use “Try again” in My AI after checking the connection.`
+    : "Keep SIMY CLI running and use “Try again” in My AI after checking the connection.";
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error || "");
+}