@wardby/cli 0.5.3 → 0.7.0

package/dist/core/runner.js

@@ -16,17 +16,26 @@
  * down) lives inside the engine now — there is exactly one place that
  * reasons about cost, not one here plus one in the engine.
  */
+import { createHash, randomBytes } from "node:crypto";
 import { z } from "zod";
-import { runStepInline } from "../providers/engine/types.js";
+import { Prisma } from "#prisma";
+import { RunOwnershipLostError, STEPS_CHANGED_REASON, StepReplayMismatchError, runStepInline, } from "../providers/engine/types.js";
 import { isLlmEffort } from "../providers/llm/types.js";
-import { validateParams } from "../sandbox/zod-params.js";
-import { runInSandbox } from "../sandbox/run-in-sandbox.js";
+import { createPrivilegedHost } from "../sandbox/host-functions.js";
+import { consoleRedactionValues } from "../sandbox/secret-broker.js";
+import { runUserToolCall } from "../sandbox/user-tool.js";
+import { logUnexpectedError, runSandboxedEngine, SandboxRunCancelledError, } from "../native-worker/gateway.js";
+import { NATIVE_WORKER_PROTOCOL_VERSION } from "../native-worker/protocol.js";
 import { asStringArray, asPrefixMap } from "../sandbox/tool-capabilities.js";
 import { scopeDatastore } from "../providers/datastore/scoped.js";
 import { buildSecretsAccessor, scopeSecretsAccessor } from "./secrets.js";
+import { loadAgentSecretValues, maskNamedSecrets, POSTING_TOOL_NAMES, SECRET_CHECK_UNAVAILABLE_MESSAGE, WITHHELD_TEXT_NOTICE, } from "./secret-guard.js";
 import { buildSharedDatastoreAccessor, scopeSharedDatastoreAccessor } from "./datastores.js";
 import { effectiveBudgetForRun } from "./budget-groups.js";
+import { stopChildrenOfLostRun } from "./lost-run-children.js";
 import { createDelegationSiblings } from "./delegation-siblings.js";
+import { findDelegationChild } from "./delegation-child.js";
+import { DRIVABLE } from "./run-status.js";
 import { createSerialGate } from "./serial-gate.js";
 import { withRunHeartbeat } from "./run-heartbeat.js";
 import { ContinuationRefusedError, dispatchRun } from "./dispatch.js";
@@ -36,6 +45,7 @@ import { DELEGATE_TOOL_PREFIX, duplicateToolNames } from "./tool-names.js";
 import { SUBAGENT_MEMORY_GET_TOOL, PARENT_MEMORY_GET_TOOL, handleSubAgentMemoryGet, handleParentMemoryGet, } from "./subagent-memory-tools.js";
 import { prisma as defaultDb } from "./db.js";
 import { logger } from "./logger.js";
+import { CHILD_RUN_FAILURE_CODES, declaredCodeOf } from "./error-code.js";
 import { loadCodingConcurrencyConfig } from "../config/providers.js";
 import { REVIEW_HOST_TOOL_DEFS, REVIEW_HOST_TOOL_NAMES, handleReviewHostTool, } from "./review-host-tools.js";
 import { closeOpenHostCheck } from "./review-host-checks.js";
@@ -47,15 +57,21 @@ import { ISSUE_TRACKER_TOOL_DEFS, ISSUE_TRACKER_TOOL_NAMES, handleIssueTrackerTo
 import { completeIssueStatus } from "./issue-status.js";
 import { fileIssue } from "./issue-dedupe.js";
 import { fileSelfDefect } from "./self-defects.js";
+import { emitRunFinishedEvents } from "./workflow-run-events.js";
 import { startReviewFixAfterReview } from "./review-fix.js";
 import { updateRelatedPullRequests } from "./related-pull-requests.js";
+import { syncMergeOrderChecksAfterRun } from "./merge-order-check.js";
+import { markReadyAfterRun } from "./mark-ready.js";
+import { startDeferredForRequest } from "./host-events.js";
 import { recordNativeModelUsage } from "./model-usage.js";
 import { pinNativeRunPricing } from "./run-pricing.js";
 import { RoutingLlmProvider } from "../providers/llm/routing.js";
 import { ModelUnavailableError } from "../providers/llm/catalog-types.js";
 import { trackRun } from "./in-flight-runs.js";
+import { ReviewReadLedger } from "./review-reads.js";
 import { createRepoAccessGate, requiredLevel } from "./repo-access.js";
-const runnerLog = logger.child({ module: "runner" });
+import { loadBudgetEvent, ownerBudgetSentence } from "./budget-events.js";
+export const runnerLog = logger.child({ module: "runner" });
 /**
  * Sub-agent dispatch uses one synthetic tool per declared child, named by the
  * boundName it's attached
@@ -115,20 +131,177 @@ function delegateToolDef(boundName, parallel) {
                     type: "string",
                     description: "Coding sub-agents only. The run id of a prior coding run whose branch/PR this dispatch should push a new commit onto, instead of opening a fresh one — use when the task is a revision to an existing PR (a plan/spec update, or a code-review follow-up), even across a different sub-agent than the one that opened it.",
                 },
+                mergeOrder: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 99,
+                    description: "Coding sub-agents only. This repository's step in the merge order of the whole request (1 = merge first). " +
+                        "Give dependencies lower numbers than the changes that use them (e.g. a service 1, the API that calls it 2, the client 3); " +
+                        "equal numbers have no order between them. Set it whenever one change spans several repositories.",
+                },
             },
             required: ["task"],
             additionalProperties: false,
         },
     };
 }
+/** Every mergeOrder validation failure (wrong type, non-integer, or out of range) names the same bound. */
+const MERGE_ORDER_RANGE_MESSAGE = "mergeOrder must be an integer from 1 to 99.";
 const DelegateArgs = z
     .object({
     task: z.string(),
     datastoreRef: z.object({ name: z.string(), key: z.string() }).strict().optional(),
     grantParentMemoryKeys: z.array(z.string()).optional(),
     continuePriorRun: z.string().optional(),
+    mergeOrder: z
+        .number({ error: MERGE_ORDER_RANGE_MESSAGE })
+        .int(MERGE_ORDER_RANGE_MESSAGE)
+        .min(1, MERGE_ORDER_RANGE_MESSAGE)
+        .max(99, MERGE_ORDER_RANGE_MESSAGE)
+        .optional(),
 })
     .strict();
+/** The tool result note for a native child's delegation when the caller passed mergeOrder: it does not apply. */
+const MERGE_ORDER_IGNORED_NOTE = "mergeOrder applies only to coding sub-agents; ignored";
+/** A delegate_to_* call's arguments, or the tool result refusing them. */
+export function parseDelegateArgs(argsJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argsJson || "{}");
+    }
+    catch (err) {
+        return {
+            refusal: JSON.stringify({
+                error: "invalid_arguments_json",
+                message: err instanceof Error ? err.message : String(err),
+            }),
+        };
+    }
+    try {
+        return { args: DelegateArgs.parse(parsed) };
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            return {
+                refusal: JSON.stringify({
+                    error: "validation_failed",
+                    message: err.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; "),
+                }),
+            };
+        }
+        throw err;
+    }
+}
+/**
+ * At most `limit` dispatches per run (default one: a classifier deciding plan-vs-implement
+ * commits to exactly one child), and never the same child twice, so a retry can't leave two
+ * children racing on the same task. A delegation waiting for budget holds its place.
+ */
+export function delegationLimitRefusal(input) {
+    const { priorChildAgentIds, waitingChildAgentIds, childAgentId, boundName, limit } = input;
+    if (priorChildAgentIds.includes(childAgentId) || waitingChildAgentIds.includes(childAgentId)) {
+        return JSON.stringify({
+            error: "already_dispatched",
+            message: `This run already delegated to "${boundName}"; a run delegates to each sub-agent at most once.`,
+        });
+    }
+    if (priorChildAgentIds.length < limit && priorChildAgentIds.length + waitingChildAgentIds.length >= limit) {
+        // Only a waiting delegation (parallelDelegations) holds the remaining place.
+        return JSON.stringify({
+            error: "already_dispatched",
+            message: `This run reached its limit of ${limit} delegations: ${priorChildAgentIds.length} made and ${waitingChildAgentIds.length} waiting for budget.`,
+        });
+    }
+    if (priorChildAgentIds.length >= limit) {
+        return JSON.stringify({
+            error: "already_dispatched",
+            message: limit === 1
+                ? "This run already delegated to a sub-agent; only one delegation is allowed per run."
+                : `This run already made ${limit} delegations, the most this agent allows per run.`,
+        });
+    }
+    return null;
+}
+const DELEGATION_CHILD_SELECT = {
+    id: true,
+    kind: true,
+    budgetGroupId: true,
+    budgetUsd: true,
+    ownerId: true,
+    nativeExecutionMode: true,
+    codingProfile: { select: { allowWebhookTaskOverride: true, timeoutSec: true } },
+};
+/**
+ * The live authorization of one delegation, and the child agent as it is now. Owners are re-read
+ * on every delegation (resource-sharing grants spec §3.4.4, N1): the child must have the parent's
+ * current owner, or that owner must still hold execute on the child. A revoked grant or a
+ * make_owner transfer stops the very next call.
+ */
+export async function authorizeDelegation(db, parentAgentId, edge, boundName, args) {
+    const [parentNow, childAgent] = await Promise.all([
+        db.agent.findUnique({ where: { id: parentAgentId }, select: { ownerId: true } }),
+        db.agent.findUniqueOrThrow({ where: { id: edge.childAgentId }, select: DELEGATION_CHILD_SELECT }),
+    ]);
+    const parentOwnerId = parentNow?.ownerId ?? null;
+    const childOwnerId = childAgent.ownerId ?? null;
+    if (!parentNow ||
+        !(await canDelegate(db, { ownerId: parentOwnerId }, { id: childAgent.id, ownerId: childOwnerId }))) {
+        return {
+            refusal: JSON.stringify({
+                error: "subagent_not_authorized",
+                message: `The "${boundName}" sub-agent belongs to another owner who has not given this agent's owner execute access to it.`,
+            }),
+        };
+    }
+    if (parentOwnerId !== childOwnerId) {
+        // Across owners the edge carries execute and nothing more: no
+        // model-chosen memory grant, no continuation of another run's PR,
+        // and no task text the caller couldn't give the child directly --
+        // the trigger_agent rule (review I3): a coding child only with its
+        // owner's allowWebhookTaskOverride opt-in, a native child never
+        // (it runs its owner's fixed prompt; pass an empty task).
+        const refusal = (args.grantParentMemoryKeys?.length ?? 0) > 0
+            ? "grantParentMemoryKeys is only allowed when the sub-agent has the same owner."
+            : args.continuePriorRun !== undefined
+                ? "continuePriorRun is only allowed when the sub-agent has the same owner."
+                : childAgent.kind === "coding" && !childAgent.codingProfile?.allowWebhookTaskOverride
+                    ? "This coding sub-agent belongs to another owner and does not accept task text from others (allowWebhookTaskOverride)."
+                    : childAgent.kind !== "coding" && (args.task.trim() !== "" || args.datastoreRef !== undefined)
+                        ? 'This sub-agent belongs to another owner and runs only its own instructions: delegate with task "" and no datastoreRef.'
+                        : null;
+        if (refusal)
+            return { refusal: JSON.stringify({ error: "cross_owner_not_allowed", message: refusal }) };
+    }
+    if (args.continuePriorRun !== undefined && childAgent.kind !== "coding") {
+        return {
+            refusal: JSON.stringify({
+                error: "continuation_requires_coding_agent",
+                message: "continuePriorRun is only supported when the sub-agent is coding-kind.",
+            }),
+        };
+    }
+    return { childAgent };
+}
+/** A native child's task text: the delegated task, with any datastore reference as a note. */
+export function delegationTaskOverride(args) {
+    return args.datastoreRef
+        ? `${args.task}\n\n[Referenced datastore: name="${args.datastoreRef.name}", key="${args.datastoreRef.key}" — use your datastore tools to read it.]`
+        : args.task.trim() !== ""
+            ? args.task
+            : undefined;
+}
+/** The tool result a native child's terminal run reports to its parent. `note` surfaces e.g. an ignored mergeOrder. */
+export function nativeChildResult(run, note) {
+    return JSON.stringify({
+        status: run.status,
+        finalText: run.finalText,
+        costUsd: Number(run.costUsd),
+        tokensIn: run.tokensIn,
+        tokensOut: run.tokensOut,
+        ...(run.error ? { error: run.error } : {}),
+        ...(note ? { note } : {}),
+    });
+}
 /**
  * The composed review hosts, or undefined when there are none (no GitHub App
  * configured yields an empty registry). Undefined means the run never touches
@@ -161,17 +334,7 @@ function toIssueProjectLink(row) {
         maxNewIssuesPerRun: row.maxNewIssuesPerRun ?? null,
     };
 }
-/**
- * The two states a Run can still be driven out of. Every write `executeRun`
- * makes is filtered on these: a durable executor can have two attempts of the
- * same run in flight at once (a still-live original parked in a slow LLM step
- * and an adopted attempt the reconciler resumed elsewhere), and whichever
- * reaches a terminal state first must win. A conditional `updateMany` makes
- * that a database-level CAS rather than a race — the loser's WHERE matches
- * zero rows. It also stops a *later* attempt resurrecting a run the
- * reconciler already reaped: a `lost` row stays `lost`.
- */
-const DRIVABLE = ["pending", "running"];
+// DRIVABLE (the two states a Run can still be driven out of) lives in run-status.ts.
 /**
  * Raised when a run's step boundary observed a cancellation (DbosExecutor's
  * `stop`). `executeRun`'s backstop persists these as `cancelled` with the
@@ -183,6 +346,15 @@ export class RunCancelledError extends Error {
         this.name = "RunCancelledError";
     }
 }
+/** Re-exported beside RunCancelledError: thrown by a step runner when another attempt owns the run. */
+export { RunOwnershipLostError };
+/**
+ * The one log line for an attempt that lost ownership of its run. Warn, not info: each one also
+ * means a discarded step's spend and an owner that stalled long enough to be adopted.
+ */
+function logRunOwnershipLost(runId, err) {
+    runnerLog.warn({ runId, step: err.step, event: "run_ownership_lost", discardedUsage: err.discardedUsage }, "run_ownership_lost: another execution owns this run; stopping without a terminal write (this attempt's last step is discarded)");
+}
 /**
  * Terminal write + read-back. The write is conditional (see DRIVABLE), so
  * the returned row is the run's real state — this attempt's result if it won
@@ -196,6 +368,46 @@ async function finishRunClaimed(db, runId, data) {
     const updated = await db.run.updateMany({ where: { id: runId, status: { in: [...DRIVABLE] } }, data });
     return { run: await db.run.findUniqueOrThrow({ where: { id: runId } }), claimed: updated.count > 0 };
 }
+/**
+ * A step runner made to notice a stop. Before each step this reads the run's own row: once anything
+ * else has made it terminal (stop_run, an MCP task's cancel, a parent run's stop, the reconciler),
+ * the run stops at this boundary with a RunCancelledError. The terminal row is never rewritten
+ * (finishRunClaimed matches zero rows), so the stop keeps its reason. Inline runs need it because
+ * nothing else interrupts their steps. DbosExecutor wraps its own step runner in it too: DBOS stops
+ * only a workflow it was told to cancel, and stop() can name only the workflow the run records.
+ */
+export function stopAwareStep(db, runId, inner = runStepInline, options = {}) {
+    const check = async (name, own) => {
+        const read = db.run.findUnique({ where: { id: runId }, select: { status: true, executionWorkflowId: true } });
+        const row = options.failOpen ? await read.catch(() => null) : await read;
+        if (row?.executionWorkflowId && own && options.ownership?.forkedFrom(row.executionWorkflowId, own)) {
+            throw new RunOwnershipLostError(name);
+        }
+        if (row && !DRIVABLE.includes(row.status)) {
+            throw new RunCancelledError(`Run ${row.status}: stopped before step "${name}".`);
+        }
+    };
+    // Each check waits for the one before it, so steps reach `inner` in the order they were called,
+    // as they did without a read in front: a durable runner numbers a step when it is called (DBOS
+    // assigns its function id then), and a replay of concurrent delegations matches steps by number.
+    let previous = Promise.resolve();
+    return async (name, fn) => {
+        const own = options.ownership?.workflowId();
+        const checked = previous.then(() => check(name, own));
+        previous = checked.catch(() => undefined);
+        await checked;
+        return inner(name, fn);
+    };
+}
+/**
+ * Why a sandbox-mode native run is not executed here. The runner only ever
+ * executes native runs in the control plane; a run whose snapshot says
+ * `sandbox` reaches it only when no native sandbox executor is composed in
+ * (RoutingExecutor sends it to the native executor), and must fail closed
+ * rather than run unisolated.
+ */
+export const NATIVE_SANDBOX_NOT_CONFIGURED = "native_sandbox_unavailable: This agent runs with nativeExecutionMode=sandbox, but this deployment has no native " +
+    "sandbox executor configured, so the run was not started. Switch the agent back to control-plane mode to run it here.";
 /**
  * Why a coding run cannot start in this process: runs reach the runner only
  * when no container executor is composed in (JOB_LAUNCHER=local, e.g. every
@@ -210,12 +422,22 @@ const CODING_EXECUTOR_NOT_CONFIGURED = "Coding agents need a container executor,
  * write the terminal row, and the queue timeout only fires on a drain tick.
  */
 export const CODING_CHILD_WAIT_GRACE_SEC = 60;
+/**
+ * How long a parent waits for a sandbox-mode native child before stopping it. Native runs have
+ * no run timeout of their own; until the sandbox executor brings a per-run deadline, this bounds
+ * a parent left waiting on a child that never finishes.
+ */
+export const SANDBOX_CHILD_WAIT_SEC = 60 * 60;
+/** The leading snake_case code of an error message (`code: sentence`); messages can carry internals. */
 /**
  * What a coding sub-agent's run tells the parent run's model. A run refused
  * over its services carries the host sentence (never the raw Run.error), so
- * the parent can pass it on — for a mention, that is the requester.
+ * the parent can pass it on — for a mention, that is the requester. A failed
+ * run carries only its error code, so the parent can say why without seeing internals.
  */
-export function codingChildResult(run, codingResult) {
+export function codingChildResult(run, codingResult, 
+/** The child's recorded budget refusal (loadBudgetEvent), if any. */
+budgetEvent) {
     // Checked before the "refused" branch: a continuation whose PR closed
     // before the run ever spent anything is stored as "refused" (a preflight
     // refusal, container.ts), not "failed" -- but it is the same
@@ -226,6 +448,10 @@ export function codingChildResult(run, codingResult) {
         : run.status === "refused"
             ? serviceRefusalSentence(run.error)
             : null;
+    const errorCode = run.status === "failed" ? declaredCodeOf(run.error, CHILD_RUN_FAILURE_CODES) : undefined;
+    const budget = budgetEvent && (run.status === "budget_exhausted" || run.status === "refused")
+        ? ownerBudgetSentence(budgetEvent.event, budgetEvent.agentName)
+        : undefined;
     return JSON.stringify({
         status: run.status,
         finalText: run.finalText,
@@ -233,6 +459,8 @@ export function codingChildResult(run, codingResult) {
         tokensIn: run.tokensIn,
         tokensOut: run.tokensOut,
         ...(refusal ? { refusal } : {}),
+        ...(errorCode ? { errorCode } : {}),
+        ...(budget ? { budget } : {}),
         ...pullRequestOf(codingResult),
     });
 }
@@ -306,40 +534,27 @@ export async function createRun(db, agentName, trigger = "manual") {
     if (agent.kind === "coding") {
         throw new Error(CODING_EXECUTOR_NOT_CONFIGURED);
     }
-    return db.run.create({ data: { agentId: agent.id, trigger } });
-}
-/** Drives an existing Run (created by `createRun` or the scheduler) to a terminal state. */
-export async function executeRun(runId, providers, db = defaultDb, onText, step = runStepInline) {
-    // Counted so a shutdown waits for this run instead of abandoning it (core/in-flight-runs.ts).
-    return trackRun(runId, () => executeTrackedRun(runId, providers, db, onText, step));
-}
-async function executeTrackedRun(runId, providers, db, onText, step) {
-    const existingRun = await db.run.findUnique({ where: { id: runId } });
-    if (!existingRun) {
-        throw new Error(`Unknown run "${runId}".`);
+    // Refused here, before any row: a foreground run executes inline, never in a sandbox.
+    if (agent.nativeExecutionMode === "sandbox") {
+        throw new Error(NATIVE_SANDBOX_NOT_CONFIGURED);
     }
-    // Pre-flight guard. A run that already reached a terminal state must never
-    // be re-driven: a durable workflow re-dispatched after the reconciler
-    // reaped its row (rollback to EXECUTOR=in-process, then roll forward) would
-    // otherwise re-spend the whole run against a `lost` row, and a duplicate
-    // attempt of a finished run would spend a second time for a result no write
-    // can land. Cheaper and clearer than letting it run and discarding the
-    // result at the conditional write.
-    if (!DRIVABLE.includes(existingRun.status)) {
-        runnerLog.info({ runId, status: existingRun.status }, "skipping execution of an already-terminal run");
-        return existingRun;
-    }
-    const reviewHosts = configuredReviewHosts(providers.reviewHosts);
-    const repoAccess = reviewHosts
-        ? (providers.repoAccess ?? createRepoAccessGate({ db, hosts: reviewHosts }))
-        : undefined;
-    const issueTrackers = configuredIssueTrackers(providers.issueTrackers);
-    // Pinned in one checkpointed step: on replay after a crash, the agent row
-    // or its budget group may have changed since first execution. The
-    // engine's control flow depends on budgetUsd and maxTurns, so they must
-    // be pinned to the values seen on first execution or the replay's step
-    // order diverges from the record.
-    const loadedOrUnavailable = await step("load", async () => {
+    return db.run.create({ data: { agentId: agent.id, trigger, nativeExecutionMode: agent.nativeExecutionMode } });
+}
+/**
+ * The trusted load of a native run: the agent, its attached tools and their
+ * consented capabilities, the pinned catalog entry, the effective budget,
+ * sub-agent edges, and repository/issue links. Shared by in-process execution
+ * and the native sandbox gateway, which hands the worker this result.
+ *
+ * Pinned in one checkpointed step: on replay after a crash, the agent row
+ * or its budget group may have changed since first execution. The
+ * engine's control flow depends on budgetUsd and maxTurns, so they must
+ * be pinned to the values seen on first execution or the replay's step
+ * order diverges from the record.
+ */
+export async function loadNativeRun(options) {
+    const { runId, existingRun, providers, db, step, reviewHosts, issueTrackers } = options;
+    return step("load", async () => {
         const agent = await db.agent.findUnique({ where: { id: existingRun.agentId } });
         if (!agent) {
             throw new Error(`Run "${runId}" references missing agent "${existingRun.agentId}".`);
@@ -486,53 +701,181 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
             (err instanceof Error && err.message.startsWith("model_unavailable:"))) {
             return { unavailable: err.message };
         }
+        // Thrown out of executeRun ahead of its backstop, so logged here instead.
+        if (err instanceof RunOwnershipLostError)
+            logRunOwnershipLost(runId, err);
         throw err;
     });
-    // Fails a run that ends before its engine starts, closing what its trigger opened (the review
-    // check, the host and issue status comments) exactly as the normal and catch paths below do.
-    // Deliberately no self-defect: both callers are configuration states, not this run's defect (an
-    // admin disabled or removed the model, or this deployment has no coding executor), and filing
-    // would open one defect per affected agent rather than describe a failure of that agent.
-    const finishEarly = async (error) => {
-        const finished = await finishRun(db, runId, { status: "failed", error, finishedAt: new Date() });
-        await closeOpenHostCheck(db, finished, reviewHosts);
-        await completeHostStatus(db, finished, reviewHosts);
-        await completeIssueStatus(db, finished, issueTrackers);
-        return finished;
+}
+/**
+ * Every value of the secrets `names` (readable or brokered; a SigV4 secret's key and token alone
+ * too, the same set the in-process host redacts), as a redaction list. Rejects when ANY read
+ * fails: a list missing one secret would let that secret through, so a caller treats a rejection
+ * as "no list" and fails closed. A secret with no value contributes nothing.
+ */
+export async function readRedactionValues(accessor, names) {
+    const values = await Promise.all(names.map((secret) => accessor.resolve
+        ? accessor.resolve(secret).then((e) => (e ? consoleRedactionValues(e) : []))
+        : accessor.get(secret).then((v) => (v === undefined ? [] : [v]))));
+    return values.flat().filter((value) => typeof value === "string");
+}
+/**
+ * One attempt's tool surface for a native run. `builtinHandler(name)` is the
+ * single source of truth for which names are trusted built-ins (memory,
+ * repo_*, jira_*, sub-agent/parent memory, delegate_to_*) and returns undefined
+ * for everything else, which `runUserTool` runs in the WASM sandbox. Per-attempt
+ * state (the delegation gate, siblings, issue creation counters) lives here.
+ */
+export function createNativeRunTools(options) {
+    const { runId, existingRun, loaded, providers, db, reviewHosts, repoAccess, issueTrackers } = options;
+    const toolsByName = new Map(Object.entries(loaded.toolsByName));
+    const secretsAccessor = buildSecretsAccessor(loaded.agentId, providers.secrets, db);
+    const sharedDatastoreAccessor = buildSharedDatastoreAccessor(loaded.agentId, providers.datastore, db);
+    // jira_create_issue's per-run cap counter: shared by every tool call of this attempt (a resumed attempt
+    // starts a fresh one, floored by the run's recorded fingerprint creates).
+    const issueCreationCounters = new Map();
+    // What this attempt's review tools have read, for repo_publish_review's unread_files gate.
+    const reviewReads = options.reviewReads ?? new ReviewReadLedger();
+    // One per attempt: admits this run's delegations one at a time (see the delegate branch).
+    const delegationGate = createSerialGate();
+    // The children this attempt's delegations have running, and the sub-agents whose delegation is
+    // waiting for one of them to free budget (parallelDelegations): a waiting delegation keeps its
+    // place in the same-child and limit checks while the gate is open to the others.
+    const delegationSiblings = createDelegationSiblings();
+    const waitingDelegations = new Set();
+    /**
+     * Waits on a dispatched coding or sandbox-mode native child until it is terminal, its wait
+     * bound passes (it is then stopped), or this run is cancelled, and returns what the model sees.
+     * The bound is measured from the child's creation, so a re-executed delegate step (a resume, or
+     * a takeover under a new version) never extends how long this run waits for it.
+     */
+    const awaitDelegatedChild = async (wait) => {
+        const { executor, childRunId, kind, boundName } = wait;
+        const startedAt = Date.now();
+        let boundMs;
+        if (kind === "coding") {
+            const codingRun = await db.codingRun.findUnique({
+                where: { runId: childRunId },
+                select: { timeoutSec: true },
+            });
+            const { queueTimeoutSec } = loadCodingConcurrencyConfig();
+            boundMs = (queueTimeoutSec + (codingRun?.timeoutSec ?? 0) + CODING_CHILD_WAIT_GRACE_SEC) * 1000;
+        }
+        else {
+            boundMs = SANDBOX_CHILD_WAIT_SEC * 1000;
+        }
+        const elapsedMs = Math.max(0, Date.now() - wait.createdAtMs);
+        // Executor.start may resolve before the child is terminal, so wait on the row.
+        const waited = await waitForCodingChild({
+            db,
+            executor,
+            childRunId,
+            parentRunId: runId,
+            boundMs: Math.max(0, boundMs - elapsedMs),
+        });
+        wait.onSettled();
+        runnerLog.info({
+            runId,
+            childRunId,
+            boundName,
+            outcome: waited.kind === "terminal" ? waited.run.status : waited.kind,
+            durationMs: Date.now() - startedAt,
+        }, "delegation finished");
+        if (waited.kind === "timed_out") {
+            return JSON.stringify({
+                error: "subagent_wait_timed_out",
+                runId: childRunId,
+                message: kind === "coding"
+                    ? "The coding sub-agent did not finish within its queue timeout plus run timeout; it was stopped and produced no result."
+                    : "The sandbox sub-agent did not finish in time; it was stopped and produced no result.",
+            });
+        }
+        if (waited.kind === "parent_cancelled") {
+            return JSON.stringify({
+                error: "parent_cancelled",
+                runId: childRunId,
+                message: kind === "coding"
+                    ? "This run was cancelled while waiting for the coding sub-agent; the sub-agent was stopped."
+                    : "This run was cancelled while waiting for the sandbox sub-agent; the sub-agent was stopped.",
+            });
+        }
+        if (kind === "coding") {
+            const stored = await db.codingRun
+                .findUnique({ where: { runId: childRunId }, select: { result: true } })
+                .catch((err) => {
+                runnerLog.warn({ err, childRunId }, "could not read the coding sub-run's result");
+                return null;
+            });
+            return codingChildResult(waited.run, stored?.result, await loadBudgetEvent(db, childRunId));
+        }
+        return nativeChildResult(waited.run, wait.mergeOrderNote);
     };
-    if ("unavailable" in loadedOrUnavailable)
-        return finishEarly(loadedOrUnavailable.unavailable);
-    const loaded = loadedOrUnavailable;
-    if (loaded.kind === "coding")
-        return finishEarly(CODING_EXECUTOR_NOT_CONFIGURED);
-    // Conditional on DRIVABLE rather than on `pending`: an adopted attempt
-    // legitimately finds the row already `running`, but a terminal row must
-    // never be flipped back to `running`.
-    await db.run.updateMany({ where: { id: runId, status: { in: [...DRIVABLE] } }, data: { status: "running" } });
-    try {
-        const toolsByName = new Map(Object.entries(loaded.toolsByName));
-        const secretsAccessor = buildSecretsAccessor(loaded.agentId, providers.secrets, db);
-        const sharedDatastoreAccessor = buildSharedDatastoreAccessor(loaded.agentId, providers.datastore, db);
-        // jira_create_issue's per-run cap counter: shared by every tool call of this attempt (a resumed attempt
-        // starts a fresh one, floored by the run's recorded fingerprint creates).
-        const issueCreationCounters = new Map();
-        // One per attempt: admits this run's delegations one at a time (see the delegate branch).
-        const delegationGate = createSerialGate();
-        // The children this attempt's delegations have running, and the sub-agents whose delegation is
-        // waiting for one of them to free budget (parallelDelegations): a waiting delegation keeps its
-        // place in the same-child and limit checks while the gate is open to the others.
-        const delegationSiblings = createDelegationSiblings();
-        const waitingDelegations = new Set();
-        const runSandboxTool = async (name, argsJson) => {
-            if (loaded.memoryEnabled && MEMORY_TOOL_NAMES.has(name)) {
+    /**
+     * A re-executed delegate call whose child already exists (findDelegationChild): wait on it
+     * again rather than refuse it as a duplicate. A control-plane native child ran inline in the
+     * attempt that died, so nothing drives it any more: it is stopped (or its result returned, if
+     * it had finished) and no new child is started.
+     */
+    const reattachDelegatedChild = async (child, boundName, argsJson) => {
+        const row = await db.run.findUniqueOrThrow({ where: { id: child.id } });
+        const childAgentRow = await db.agent.findUnique({ where: { id: row.agentId }, select: { kind: true } });
+        const parsedArgs = parseDelegateArgs(argsJson);
+        const mergeOrderNote = "args" in parsedArgs && parsedArgs.args.mergeOrder !== undefined ? MERGE_ORDER_IGNORED_NOTE : undefined;
+        const coding = childAgentRow?.kind === "coding";
+        if (!coding && row.nativeExecutionMode !== "sandbox") {
+            if (!DRIVABLE.includes(row.status))
+                return nativeChildResult(row, mergeOrderNote);
+            await providers.executor?.stop(child.id, "parent resumed without it").catch((err) => {
+                runnerLog.warn({ err, childRunId: child.id, runId }, "failed to stop an interrupted sub-agent run");
+            });
+            return JSON.stringify({
+                error: "subagent_interrupted",
+                message: "The sub-agent was interrupted by a restart and cannot be resumed; no new sub-agent run was started.",
+            });
+        }
+        if (!providers.executor) {
+            return coding
+                ? JSON.stringify({
+                    error: "coding_dispatch_unavailable",
+                    message: "This execution context has no Executor wired in, so a coding-kind sub-agent cannot be dispatched.",
+                })
+                : JSON.stringify({
+                    error: "sandbox_dispatch_unavailable",
+                    message: "This execution context has no Executor wired in, so a sandbox-mode sub-agent cannot be dispatched.",
+                });
+        }
+        // Counted as a running sibling while it is waited on, as a fresh dispatch is.
+        const finishSibling = delegationSiblings.start();
+        try {
+            return await awaitDelegatedChild({
+                executor: providers.executor,
+                childRunId: child.id,
+                createdAtMs: child.createdAt.getTime(),
+                kind: coding ? "coding" : "native-sandbox",
+                boundName,
+                mergeOrderNote: coding ? undefined : mergeOrderNote,
+                onSettled: finishSibling,
+            });
+        }
+        finally {
+            finishSibling();
+        }
+    };
+    const unguardedBuiltinHandler = (name) => {
+        if (loaded.memoryEnabled && MEMORY_TOOL_NAMES.has(name)) {
+            return async (argsJson) => {
                 return handleMemoryTool(name, argsJson, loaded.agentId, providers.memory);
-            }
-            if (REVIEW_HOST_TOOL_NAMES.has(name) && loaded.repositoryLinks.length > 0 && reviewHosts && repoAccess) {
+            };
+        }
+        if (REVIEW_HOST_TOOL_NAMES.has(name) && loaded.repositoryLinks.length > 0 && reviewHosts && repoAccess) {
+            return async (argsJson) => {
                 const check = await db.runHostCheck.findUnique({ where: { runId } });
                 return handleReviewHostTool(name, argsJson, {
                     agentId: loaded.agentId,
                     links: loaded.repositoryLinks,
                     hosts: reviewHosts,
+                    reads: reviewReads,
+                    db,
                     runCheck: check && !check.completedAt
                         ? {
                             provider: check.provider,
@@ -581,11 +924,13 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                         });
                     },
                 });
-            }
-            // `?? []`: a load step replayed from before these links were pinned has none.
-            // Each link is re-normalised too: one pinned before the allowlists existed lacks them.
-            const issueProjectLinks = (loaded.issueProjectLinks ?? []).map(toIssueProjectLink);
-            if (ISSUE_TRACKER_TOOL_NAMES.has(name) && issueProjectLinks.length > 0 && issueTrackers) {
+            };
+        }
+        // `?? []`: a load step replayed from before these links were pinned has none.
+        // Each link is re-normalised too: one pinned before the allowlists existed lacks them.
+        const issueProjectLinks = (loaded.issueProjectLinks ?? []).map(toIssueProjectLink);
+        if (ISSUE_TRACKER_TOOL_NAMES.has(name) && issueProjectLinks.length > 0 && issueTrackers) {
+            return async (argsJson) => {
                 return handleIssueTrackerTool(name, argsJson, {
                     agentId: loaded.agentId,
                     links: issueProjectLinks,
@@ -605,14 +950,22 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                         recordedCreates: (projectKey) => db.issueFingerprint.count({ where: { createdByRunId: runId, issueProvider: "jira", projectKey } }),
                     },
                 });
-            }
-            if (name === "subagent_memory_get") {
+            };
+        }
+        if (name === "subagent_memory_get") {
+            return async (argsJson) => {
                 return handleSubAgentMemoryGet(argsJson, loaded.agentId, db, providers.memory);
-            }
-            if (name === "parent_memory_get") {
+            };
+        }
+        if (name === "parent_memory_get") {
+            return async (argsJson) => {
                 return handleParentMemoryGet(argsJson, runId, db, providers.memory);
-            }
-            if (name.startsWith(DELEGATE_TOOL_PREFIX)) {
+            };
+        }
+        if (name.startsWith(DELEGATE_TOOL_PREFIX)) {
+            return async (argsJson, toolCallId) => {
+                // An empty id (an adapter that had none) is no key: every such call would share it.
+                const callId = toolCallId || undefined;
                 const boundName = name.slice(DELEGATE_TOOL_PREFIX.length);
                 const edge = loaded.subAgentEdges.find((e) => e.boundName === boundName);
                 if (!edge) {
@@ -621,8 +974,36 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                         message: `No sub-agent is bound to name "${boundName}".`,
                     });
                 }
+                // A re-executed delegate step (a resume, or a takeover under a new version) finds the
+                // child this very call created and waits on it again, instead of refusing it as a duplicate.
+                const existingChild = await findDelegationChild(db, runId, edge.childAgentId, callId);
+                if (existingChild) {
+                    runnerLog.info({ runId, childRunId: existingChild.id, boundName }, "delegation re-attached");
+                    return reattachDelegatedChild(existingChild, boundName, argsJson);
+                }
                 let release = await delegationGate.acquire();
                 let finishSibling = () => { };
+                /**
+                 * A child create that lost the (parentRunId, parentCallId) unique key to another execution of
+                 * this same delegate step (a stalled owner overlapping an adopted attempt): wait on the child
+                 * that execution created, as a re-executed step does. A key held by no child of this agent
+                 * (an id colliding with another sub-agent's call) is the model's to see, never a run failure.
+                 */
+                const afterDelegationKeyConflict = async (err) => {
+                    if (!(err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002"))
+                        throw err;
+                    release();
+                    const raced = await findDelegationChild(db, runId, edge.childAgentId, callId);
+                    if (raced) {
+                        runnerLog.info({ runId, childRunId: raced.id, boundName }, "delegation re-attached after a concurrent create");
+                        return reattachDelegatedChild(raced, boundName, argsJson);
+                    }
+                    runnerLog.warn({ err, runId, boundName }, "delegation child create hit a unique key held by no child of this agent");
+                    return JSON.stringify({
+                        error: "delegation_conflict",
+                        message: "The sub-agent run could not be created: its call id is already used by another sub-agent run.",
+                    });
+                };
                 try {
                     // At most maxDelegationsPerRun dispatches per run (default one: a
                     // classifier deciding plan-vs-implement commits to exactly one child),
@@ -630,105 +1011,24 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                     // racing on the same task. Checked and the child row written under the
                     // run's delegation gate: delegations started together in one turn
                     // (parallelDelegations) are admitted one at a time.
-                    const limit = loaded.maxDelegationsPerRun ?? 1;
                     const priorDispatches = await db.run.findMany({ where: { parentRunId: { in: [runId] } } });
-                    if (priorDispatches.some((prior) => prior.agentId === edge.childAgentId) ||
-                        waitingDelegations.has(edge.childAgentId)) {
-                        return JSON.stringify({
-                            error: "already_dispatched",
-                            message: `This run already delegated to "${boundName}"; a run delegates to each sub-agent at most once.`,
-                        });
-                    }
-                    if (priorDispatches.length < limit && priorDispatches.length + waitingDelegations.size >= limit) {
-                        // Only a waiting delegation (parallelDelegations) holds the remaining place.
-                        return JSON.stringify({
-                            error: "already_dispatched",
-                            message: `This run reached its limit of ${limit} delegations: ${priorDispatches.length} made and ${waitingDelegations.size} waiting for budget.`,
-                        });
-                    }
-                    if (priorDispatches.length >= limit) {
-                        return JSON.stringify({
-                            error: "already_dispatched",
-                            message: limit === 1
-                                ? "This run already delegated to a sub-agent; only one delegation is allowed per run."
-                                : `This run already made ${limit} delegations, the most this agent allows per run.`,
-                        });
-                    }
-                    let parsed;
-                    try {
-                        parsed = JSON.parse(argsJson || "{}");
-                    }
-                    catch (err) {
-                        return JSON.stringify({
-                            error: "invalid_arguments_json",
-                            message: err instanceof Error ? err.message : String(err),
-                        });
-                    }
-                    let args;
-                    try {
-                        args = DelegateArgs.parse(parsed);
-                    }
-                    catch (err) {
-                        if (err instanceof z.ZodError) {
-                            return JSON.stringify({
-                                error: "validation_failed",
-                                message: err.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; "),
-                            });
-                        }
-                        throw err;
-                    }
-                    // Owners are re-read live on every delegation (resource-sharing
-                    // grants spec §3.4.4, N1): the child must have the parent's current
-                    // owner, or that owner must still hold execute on the child. A
-                    // revoked grant or a make_owner transfer stops the very next call.
-                    const [parentNow, childAgent] = await Promise.all([
-                        db.agent.findUnique({ where: { id: loaded.agentId }, select: { ownerId: true } }),
-                        db.agent.findUniqueOrThrow({
-                            where: { id: edge.childAgentId },
-                            select: {
-                                id: true,
-                                kind: true,
-                                budgetGroupId: true,
-                                budgetUsd: true,
-                                ownerId: true,
-                                codingProfile: { select: { allowWebhookTaskOverride: true, timeoutSec: true } },
-                            },
-                        }),
-                    ]);
-                    const parentOwnerId = parentNow?.ownerId ?? null;
-                    const childOwnerId = childAgent.ownerId ?? null;
-                    if (!parentNow ||
-                        !(await canDelegate(db, { ownerId: parentOwnerId }, { id: childAgent.id, ownerId: childOwnerId }))) {
-                        return JSON.stringify({
-                            error: "subagent_not_authorized",
-                            message: `The "${boundName}" sub-agent belongs to another owner who has not given this agent's owner execute access to it.`,
-                        });
-                    }
-                    if (parentOwnerId !== childOwnerId) {
-                        // Across owners the edge carries execute and nothing more: no
-                        // model-chosen memory grant, no continuation of another run's PR,
-                        // and no task text the caller couldn't give the child directly --
-                        // the trigger_agent rule (review I3): a coding child only with its
-                        // owner's allowWebhookTaskOverride opt-in, a native child never
-                        // (it runs its owner's fixed prompt; pass an empty task).
-                        const refusal = (args.grantParentMemoryKeys?.length ?? 0) > 0
-                            ? "grantParentMemoryKeys is only allowed when the sub-agent has the same owner."
-                            : args.continuePriorRun !== undefined
-                                ? "continuePriorRun is only allowed when the sub-agent has the same owner."
-                                : childAgent.kind === "coding" && !childAgent.codingProfile?.allowWebhookTaskOverride
-                                    ? "This coding sub-agent belongs to another owner and does not accept task text from others (allowWebhookTaskOverride)."
-                                    : childAgent.kind !== "coding" && (args.task.trim() !== "" || args.datastoreRef !== undefined)
-                                        ? 'This sub-agent belongs to another owner and runs only its own instructions: delegate with task "" and no datastoreRef.'
-                                        : null;
-                        if (refusal)
-                            return JSON.stringify({ error: "cross_owner_not_allowed", message: refusal });
-                    }
-                    if (args.continuePriorRun !== undefined && childAgent.kind !== "coding") {
-                        return JSON.stringify({
-                            error: "continuation_requires_coding_agent",
-                            message: "continuePriorRun is only supported when the sub-agent is coding-kind.",
-                        });
-                    }
+                    const limitRefusal = delegationLimitRefusal({
+                        priorChildAgentIds: priorDispatches.map((prior) => prior.agentId),
+                        waitingChildAgentIds: [...waitingDelegations],
+                        childAgentId: edge.childAgentId,
+                        boundName,
+                        limit: loaded.maxDelegationsPerRun ?? 1,
+                    });
+                    if (limitRefusal)
+                        return limitRefusal;
+                    const parsedArgs = parseDelegateArgs(argsJson);
+                    if ("refusal" in parsedArgs)
+                        return parsedArgs.refusal;
+                    const { args } = parsedArgs;
+                    const authorized = await authorizeDelegation(db, loaded.agentId, edge, boundName, args);
+                    if ("refusal" in authorized)
+                        return authorized.refusal;
+                    const { childAgent } = authorized;
                     // parallelDelegations: a child the budget would refuse (run_tree_exhausted or
                     // budget_group_exhausted:*) while a sibling still runs waits for a sibling to finish and
                     // free its hold, then tries again while siblings remain, up to the child's own wait bound
@@ -741,6 +1041,7 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                         while (delegationSiblings.inFlight > 0) {
                             // Taken before the budget read, so a sibling that finishes during it still wakes this wait.
                             const finishes = delegationSiblings.finishes;
+                            // What dispatch will reserve: a coding child's base too, its overrun is never reserved.
                             const { exhaustedBy } = await effectiveBudgetForRun(db, childAgent, new Date(), runId);
                             const remainingMs = deadline - Date.now();
                             if (!exhaustedBy || remainingMs <= 0)
@@ -798,7 +1099,9 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                                 trigger: "subagent",
                                 codingTask: args.task,
                                 continuesCodingRunId: args.continuePriorRun,
+                                mergeOrder: args.mergeOrder,
                                 parentRunId: runId,
+                                parentCallId: callId,
                                 // The child's result flows back into this run, which the
                                 // triggerer sees, so the child is visible to them too.
                                 triggeredById: existingRun.triggeredById,
@@ -818,7 +1121,7 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                             // a pull request another deployment opened, say) is the model's to
                             // report, not a reason to fail the whole run.
                             if (!(err instanceof ContinuationRefusedError))
-                                throw err;
+                                return await afterDelegationKeyConflict(err);
                             return JSON.stringify({
                                 error: "continuation_refused",
                                 message: `${err.message} No sub-agent run was started. Do not open a new pull request in its place: ` +
@@ -829,65 +1132,91 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                             return JSON.stringify({ error: "dispatch_failed", message: "The sub-agent run could not be created." });
                         }
                         const childRunId = dispatched.run.id;
-                        const startedAt = Date.now();
                         runnerLog.info({ runId, childRunId, boundName, kind: "coding" }, "delegation started");
-                        const codingRun = await db.codingRun.findUnique({
-                            where: { runId: childRunId },
-                            select: { timeoutSec: true },
-                        });
-                        const { queueTimeoutSec } = loadCodingConcurrencyConfig();
-                        const waited = await waitForCodingChild({
-                            db,
+                        return await awaitDelegatedChild({
                             executor: providers.executor,
                             childRunId,
-                            parentRunId: runId,
-                            boundMs: (queueTimeoutSec + (codingRun?.timeoutSec ?? 0) + CODING_CHILD_WAIT_GRACE_SEC) * 1000,
-                        });
-                        finishSibling();
-                        runnerLog.info({
-                            runId,
-                            childRunId,
+                            createdAtMs: dispatched.run.startedAt.getTime(),
+                            kind: "coding",
                             boundName,
-                            outcome: waited.kind === "terminal" ? waited.run.status : waited.kind,
-                            durationMs: Date.now() - startedAt,
-                        }, "delegation finished");
-                        if (waited.kind === "timed_out") {
+                            mergeOrderNote: undefined,
+                            onSettled: finishSibling,
+                        });
+                    }
+                    const taskOverride = delegationTaskOverride(args);
+                    // mergeOrder is a coding-only concept (it orders CodingRuns within a merge); a native
+                    // child has no CodingRun to store it on, so it's never passed to dispatchRun/executeRun
+                    // below -- only surfaced back to the model as a note, so a lead that set it on the wrong
+                    // kind of sub-agent notices rather than silently losing it.
+                    const mergeOrderNote = args.mergeOrder !== undefined ? MERGE_ORDER_IGNORED_NOTE : undefined;
+                    if (childAgent.nativeExecutionMode === "sandbox") {
+                        // A sandbox-mode child must run where its snapshot says, so it goes through
+                        // dispatchRun and the Executor (RoutingExecutor sends it to the sandbox executor),
+                        // exactly like a coding child — never inline in this process.
+                        if (!providers.executor) {
                             return JSON.stringify({
-                                error: "subagent_wait_timed_out",
-                                runId: childRunId,
-                                message: "The coding sub-agent did not finish within its queue timeout plus run timeout; it was stopped and produced no result.",
+                                error: "sandbox_dispatch_unavailable",
+                                message: "This execution context has no Executor wired in, so a sandbox-mode sub-agent cannot be dispatched.",
                             });
                         }
-                        if (waited.kind === "parent_cancelled") {
-                            return JSON.stringify({
-                                error: "parent_cancelled",
-                                runId: childRunId,
-                                message: "This run was cancelled while waiting for the coding sub-agent; the sub-agent was stopped.",
+                        let dispatched;
+                        try {
+                            dispatched = await dispatchRun({
+                                db,
+                                executor: providers.executor,
+                                selfDefects: { db, issueTrackers },
+                                agentId: edge.childAgentId,
+                                trigger: "subagent",
+                                taskOverride,
+                                grantedParentMemoryKeys: args.grantParentMemoryKeys ?? [],
+                                parentRunId: runId,
+                                parentCallId: callId,
+                                triggeredById: existingRun.triggeredById,
+                                awaitExecution: true,
+                                onPersisted: (persistedRun) => {
+                                    if (persistedRun.status !== "refused" && persistedRun.status !== "failed") {
+                                        finishSibling = delegationSiblings.start();
+                                    }
+                                    release();
+                                },
                             });
                         }
-                        const stored = await db.codingRun
-                            .findUnique({ where: { runId: childRunId }, select: { result: true } })
-                            .catch((err) => {
-                            runnerLog.warn({ err, childRunId }, "could not read the coding sub-run's result");
-                            return null;
+                        catch (err) {
+                            return await afterDelegationKeyConflict(err);
+                        }
+                        if (!dispatched) {
+                            return JSON.stringify({ error: "dispatch_failed", message: "The sub-agent run could not be created." });
+                        }
+                        const childRunId = dispatched.run.id;
+                        runnerLog.info({ runId, childRunId, boundName, kind: "native-sandbox" }, "delegation started");
+                        return await awaitDelegatedChild({
+                            executor: providers.executor,
+                            childRunId,
+                            createdAtMs: dispatched.run.startedAt.getTime(),
+                            kind: "native-sandbox",
+                            boundName,
+                            mergeOrderNote,
+                            onSettled: finishSibling,
                         });
-                        return codingChildResult(waited.run, stored?.result);
                     }
-                    const taskOverride = args.datastoreRef
-                        ? `${args.task}\n\n[Referenced datastore: name="${args.datastoreRef.name}", key="${args.datastoreRef.key}" — use your datastore tools to read it.]`
-                        : args.task.trim() !== ""
-                            ? args.task
-                            : undefined;
-                    const childRun = await db.run.create({
-                        data: {
-                            agentId: edge.childAgentId,
-                            trigger: "subagent",
-                            parentRunId: runId,
-                            grantedParentMemoryKeys: args.grantParentMemoryKeys ?? [],
-                            taskOverride,
-                            triggeredById: existingRun.triggeredById,
-                        },
-                    });
+                    let childRun;
+                    try {
+                        childRun = await db.run.create({
+                            data: {
+                                agentId: edge.childAgentId,
+                                trigger: "subagent",
+                                parentRunId: runId,
+                                parentCallId: callId,
+                                grantedParentMemoryKeys: args.grantParentMemoryKeys ?? [],
+                                taskOverride,
+                                triggeredById: existingRun.triggeredById,
+                                nativeExecutionMode: childAgent.nativeExecutionMode,
+                            },
+                        });
+                    }
+                    catch (err) {
+                        return await afterDelegationKeyConflict(err);
+                    }
                     finishSibling = delegationSiblings.start();
                     // The child row exists: admit the next delegation while this child runs.
                     release();
@@ -904,87 +1233,674 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
                         outcome: childResult.status,
                         durationMs: Date.now() - startedAt,
                     }, "delegation finished");
-                    return JSON.stringify({
-                        status: childResult.status,
-                        finalText: childResult.finalText,
-                        costUsd: Number(childResult.costUsd),
-                        tokensIn: childResult.tokensIn,
-                        tokensOut: childResult.tokensOut,
-                    });
+                    return nativeChildResult(childResult, mergeOrderNote);
                 }
                 finally {
                     finishSibling();
                     release();
                 }
+            };
+        }
+        return undefined;
+    };
+    /**
+     * The only route to a built-in tool, in both execution modes (the in-process loop and the native
+     * gateway's builtin.call). A tool that posts model-written text to a host, and a delegate_to_*
+     * call (its task text becomes the child run's stored task), has every attached secret's value
+     * masked in its arguments first; when the secrets cannot be read the call is refused and
+     * neither the host nor a child run is reached. (The native gateway serves delegate_to_* through
+     * durableDelegate, which masks the same way.)
+     */
+    const builtinHandler = (name) => {
+        const handler = unguardedBuiltinHandler(name);
+        if (!handler || !(POSTING_TOOL_NAMES.has(name) || name.startsWith(DELEGATE_TOOL_PREFIX)))
+            return handler;
+        return async (argsJson, toolCallId) => {
+            const masked = await maskModelWrittenArgs({ db, secrets: providers.secrets, agentId: loaded.agentId, runId }, name, argsJson);
+            if (masked === undefined) {
+                return JSON.stringify({ error: "secret_check_unavailable", message: SECRET_CHECK_UNAVAILABLE_MESSAGE });
             }
-            const tool = toolsByName.get(name);
-            if (!tool) {
-                return JSON.stringify({
-                    error: "unknown_tool",
-                    message: `No tool named "${name}" is attached to this agent.`,
-                });
-            }
-            let parsedArgs;
-            try {
-                // Some providers stream no JSON delta at all for a zero-parameter
-                // tool call, yielding an empty argsJson rather than "{}".
-                parsedArgs = JSON.parse(argsJson || "{}");
-            }
-            catch (err) {
-                return JSON.stringify({
-                    error: "invalid_arguments_json",
-                    message: err instanceof Error ? err.message : String(err),
-                });
-            }
-            const validation = await validateParams(tool.paramsZod, parsedArgs);
-            if (!validation.ok) {
-                return JSON.stringify({ error: "validation_failed", message: validation.errorMessage });
-            }
-            const result = await runInSandbox({
-                code: tool.code,
-                params: validation.value,
-                agentId: loaded.agentId,
-                datastore: scopeDatastore(providers.datastore, tool.allowedDatastorePrefixes),
-                sharedDatastore: scopeSharedDatastoreAccessor(sharedDatastoreAccessor, tool.allowedSharedDatastorePrefixes),
-                secrets: scopeSecretsAccessor(secretsAccessor, tool.allowedSecrets),
-                allowedFetchHosts: tool.allowedHosts,
-                toolName: name,
+            return handler(masked, toolCallId);
+        };
+    };
+    /**
+     * The privileged host for one call of the user tool `name`, scoped to that attachment's
+     * consented capabilities. Undefined for a name that is not an attached user tool. In-process it
+     * serves the sandbox directly; the native sandbox gateway serves a worker's bridge calls with it.
+     */
+    const scopedHost = (name, tool, signal, redactSecretValues) => createPrivilegedHost({
+        redactSecretValues,
+        agentId: loaded.agentId,
+        datastore: scopeDatastore(providers.datastore, tool.allowedDatastorePrefixes),
+        sharedDatastore: scopeSharedDatastoreAccessor(sharedDatastoreAccessor, tool.allowedSharedDatastorePrefixes),
+        secrets: scopeSecretsAccessor(secretsAccessor, tool.allowedSecrets),
+        allowedFetchHosts: tool.allowedHosts,
+        fetchImpl: providers.sandboxFetch,
+        logTag: name,
+        signal,
+    });
+    const privilegedHostFor = (name, signal, redactSecretValues) => {
+        const tool = toolsByName.get(name);
+        return tool ? scopedHost(name, tool, signal, redactSecretValues) : undefined;
+    };
+    /**
+     * Every secret value the user tool `name` may use (readable or brokered), for console redaction
+     * by a stateless gateway. Rejects when any read fails (readRedactionValues).
+     */
+    const readableSecretValues = async (name) => {
+        const tool = toolsByName.get(name);
+        if (!tool)
+            return [];
+        return readRedactionValues(scopeSecretsAccessor(secretsAccessor, tool.allowedSecrets), tool.allowedSecrets);
+    };
+    const runUserTool = async (name, argsJson) => {
+        const tool = toolsByName.get(name);
+        if (!tool) {
+            return JSON.stringify({
+                error: "unknown_tool",
+                message: `No tool named "${name}" is attached to this agent.`,
+            });
+        }
+        return runUserToolCall(tool, argsJson, (signal) => scopedHost(name, tool, signal));
+    };
+    const runSandboxTool = async (name, argsJson, callId) => {
+        const builtin = builtinHandler(name);
+        return builtin ? builtin(argsJson, callId) : runUserTool(name, argsJson);
+    };
+    return { toolsByName, builtinHandler, privilegedHostFor, readableSecretValues, runUserTool, runSandboxTool };
+}
+/**
+ * Live progress for observers (MCP get_run, the viewer). Absolute totals, so a DBOS replay
+ * re-writing them is harmless. Written into the run's own cost columns on purpose: the run
+ * tree's shared budget (computeRunTreeSpend) then counts a running parent's spend so far, as it
+ * already does for coding runs, whose proxy ledger writes their totals live. Best-effort: a
+ * failed write only delays what observers see, and finishRun writes the final totals anyway.
+ * A cancelled run takes them too: a stop lands mid-step, and that step's spend is real, while the
+ * cancelled run's terminal write (failNativeRun) records no totals of its own.
+ */
+export async function recordNativeRunProgress(db, runId, progress) {
+    try {
+        await db.run.updateMany({
+            where: { id: runId, status: { in: ["running", "cancelled"] } },
+            data: {
+                turns: progress.turns,
+                tokensIn: progress.usage.tokensIn,
+                tokensOut: progress.usage.tokensOut,
+                costUsd: progress.usage.costUsd,
+                heartbeatAt: new Date(),
+            },
+        });
+    }
+    catch (err) {
+        runnerLog.warn({ err, runId }, "failed to record run progress");
+    }
+}
+/**
+ * `texts` with every value of every secret attached to the run's agent masked, for a terminal
+ * write: the stored row is what get_run, the viewer, host and issue status comments and run
+ * notifications all read. Fails closed: when the secrets cannot be read, every non-null text is
+ * replaced by WITHHELD_TEXT_NOTICE (the log line carries no text and no error message). A pure
+ * function of the stored secrets, so a durable replay writes the same row.
+ */
+async function maskRunTexts(ctx, texts) {
+    const entries = Object.entries(texts);
+    if (!entries.some(([, text]) => typeof text === "string" && text.length > 0))
+        return texts;
+    let mask;
+    try {
+        const row = await ctx.db.run.findUnique({ where: { id: ctx.runId }, select: { agentId: true } });
+        if (!row)
+            throw new Error("run not found");
+        const named = await loadAgentSecretValues(ctx.db, ctx.providers.secrets, row.agentId);
+        mask = (text) => maskNamedSecrets(text, named);
+    }
+    catch (err) {
+        runnerLog.warn({
+            runId: ctx.runId,
+            event: "run_text_secret_check_failed",
+            errorName: err instanceof Error ? err.name : typeof err,
+        }, "could not read the agent's secrets to check the run's final text and error; storing the withheld notice");
+        mask = () => WITHHELD_TEXT_NOTICE;
+    }
+    return Object.fromEntries(entries.map(([key, text]) => [key, typeof text === "string" && text.length > 0 ? mask(text) : text]));
+}
+/** Everything after the terminal write, shared by the normal and backstop paths. */
+async function settleFinishedNativeRun(ctx, finished, claimed) {
+    const { runId, db, providers, reviewHosts, repoAccess, issueTrackers } = ctx;
+    await closeOpenHostCheck(db, finished, reviewHosts);
+    await completeHostStatus(db, finished, reviewHosts);
+    await completeIssueStatus(db, finished, issueTrackers);
+    // After the issue status, so IssuePullRequest rows for this run exist. Bounded and never throws.
+    if (claimed)
+        await updateRelatedPullRequests(db, finished, reviewHosts, issueTrackers);
+    // A tree root is the lead of a request: once it is terminal every coding run it delegated is
+    // too, so the reviews of their pull requests that waited for it start now, after the related
+    // sections above are current (#259). Not gated on `claimed`: release is claimed per row, and a
+    // lead another finalizer ended (a cancellation) should not leave them to the sweep. A run that
+    // delegated nothing has no rows: one indexed lookup. Never throws.
+    if (finished.parentRunId === null && providers.executor && reviewHosts && repoAccess) {
+        await startDeferredForRequest({ db, executor: providers.executor, hosts: reviewHosts, repoAccess, issueTrackers }, runId).catch((err) => runnerLog.warn({ err, runId }, "could not start the reviews waiting for this run"));
+    }
+    if (claimed && providers.executor && reviewHosts && repoAccess) {
+        await startReviewFixAfterReview(runId, {
+            db,
+            executor: providers.executor,
+            hosts: reviewHosts,
+            repoAccess,
+            issueTrackers,
+        });
+    }
+    // Only the call that made the row terminal files, so a run another finalizer (the reconciler) ended is not
+    // filed twice. Bounded and never throws.
+    if (claimed)
+        await fileSelfDefect(db, issueTrackers, finished);
+    // Only the finalizer that made the row terminal notifies. Never throws.
+    if (claimed)
+        await emitRunFinishedEvents(db, finished);
+    // A lead's end posts the `wardby merge order` check on each open pull request of its set,
+    // once every delegated coding run has opened its PR (#261); last, after the release above (so
+    // no review waits on it) and after the follow-ups and notifications (so none is delayed by its
+    // host reads). Only for a tree root that delegated. Not gated on `claimed`: the sync is
+    // idempotent (an unchanged check writes nothing). Never throws.
+    await syncMergeOrderChecksAfterRun({ db, hosts: reviewHosts }, finished);
+    // A reviewer run's end may be the last thing a pull request waited for: mark it ready for review
+    // when its builder link opted in (#287). Last, so nothing above waits on its host reads; idempotent
+    // (claimed once per pull request); no host reads unless a link opted in. Never throws.
+    await markReadyAfterRun({ db, hosts: reviewHosts, log: runnerLog }, runId);
+    return finished;
+}
+/** The terminal write for an engine result, then its usage, host/issue status, and follow-ups. */
+export async function finishNativeRun(ctx, model, result) {
+    const texts = await maskRunTexts(ctx, { error: result.error ?? null, finalText: result.finalText || null });
+    const { run: finished, claimed } = await finishRunClaimed(ctx.db, ctx.runId, {
+        status: result.status,
+        tokensIn: result.usage.tokensIn,
+        tokensOut: result.usage.tokensOut,
+        costUsd: result.usage.costUsd,
+        error: texts.error,
+        finalText: texts.finalText,
+        turns: result.turns,
+        finishedAt: new Date(),
+    });
+    // Per-model usage is written on the same path as Run.costUsd: any future mid-run cost write must write usage too.
+    await recordNativeModelUsage(ctx.db, ctx.runId, model, result.usage);
+    return settleFinishedNativeRun(ctx, finished, claimed);
+}
+/** The backstop terminal write for a run that threw. A cancellation is not a failure: it carries the operator's own reason. */
+export async function failNativeRun(ctx, err) {
+    const { error } = await maskRunTexts(ctx, { error: err instanceof Error ? err.message : String(err) });
+    const { run: finished, claimed } = await finishRunClaimed(ctx.db, ctx.runId, {
+        status: err instanceof RunCancelledError || err instanceof SandboxRunCancelledError ? "cancelled" : "failed",
+        error,
+        finishedAt: new Date(),
+    });
+    return settleFinishedNativeRun(ctx, finished, claimed);
+}
+/** The terminal write for a run that cannot continue (it ends `lost` with `reason`), then the same settle path. */
+export async function loseNativeRun(ctx, reason) {
+    const { error } = await maskRunTexts(ctx, { error: reason });
+    const { run: finished, claimed } = await finishRunClaimed(ctx.db, ctx.runId, {
+        status: "lost",
+        error,
+        finishedAt: new Date(),
+    });
+    if (claimed)
+        await stopChildrenOfLostRun(ctx.db, ctx.providers.executor, ctx.runId);
+    return settleFinishedNativeRun(ctx, finished, claimed);
+}
+/** Where a run stands for the native gateway: still drivable, cancelled (its task), or otherwise ended. */
+export async function runDrivability(db, runId) {
+    const run = await db.run.findUnique({ where: { id: runId }, select: { status: true } });
+    if (!run || !DRIVABLE.includes(run.status)) {
+        return run?.status === "cancelled" ? "cancelled" : "ended";
+    }
+    const cancelledTask = await db.task.findFirst({ where: { runId, status: "cancelled" }, select: { id: true } });
+    return cancelledTask ? "cancelled" : "drivable";
+}
+/**
+ * What a sandbox worker is given: the pinned agent and tool definitions, which names are built-ins
+ * (served by the gateway), and each user tool's code and schema only — never its capabilities,
+ * secret names, or values, which stay with the gateway's privileged host.
+ */
+export function sandboxWorkerInput(runId, loaded, tools) {
+    if (!loaded.pricing) {
+        throw new Error("native_sandbox_requires_catalog: a sandbox run needs its model's catalog entry, and none was recorded.");
+    }
+    return {
+        v: NATIVE_WORKER_PROTOCOL_VERSION,
+        runId,
+        agent: loaded.agent,
+        tools: loaded.tools,
+        builtinTools: loaded.tools.map((tool) => tool.name).filter((name) => tools.builtinHandler(name) !== undefined),
+        userTools: Object.fromEntries([...tools.toolsByName].map(([name, tool]) => [name, { code: tool.code, paramsZod: tool.paramsZod }])),
+        runsConcurrently: loaded.parallelDelegations
+            ? loaded.tools.map((tool) => tool.name).filter((name) => name.startsWith(DELEGATE_TOOL_PREFIX))
+            : [],
+        pricing: { ...loaded.pricing.entry, efforts: [...loaded.pricing.entry.efforts] },
+    };
+}
+/**
+ * A tool call's model-written arguments with every secret value attached to the agent masked, or
+ * undefined (logged by error name only) when the secrets cannot be read and the call must be refused.
+ */
+async function maskModelWrittenArgs(ctx, tool, argsJson) {
+    try {
+        const named = await loadAgentSecretValues(ctx.db, ctx.secrets, ctx.agentId);
+        return maskNamedSecrets(argsJson, named);
+    }
+    catch (err) {
+        runnerLog.warn({
+            runId: ctx.runId,
+            tool,
+            event: "post_secret_check_failed",
+            errorName: err instanceof Error ? err.name : typeof err,
+        }, "could not read the agent's secrets to check a posted text; refusing the call");
+        return undefined;
+    }
+}
+/** Long-poll window: well under common proxy and load-balancer idle timeouts. */
+export const DELEGATION_POLL_WINDOW_MS = 20_000;
+/**
+ * A delegate_to_* call from a sandboxed run, served by the native gateway. The in-process branch
+ * holds its admission, budget wait, and child wait in one process's memory for the child's whole
+ * life; this one keeps them on the call's ledger row, so the worker can call again with the same
+ * callId — on any control-plane replica, before or after a restart — and continue where it was:
+ *
+ * - every child, native or coding, is a managed run dispatched through dispatchRun and the
+ *   Executor (never inline: an inline child dies with the replica, and the reconciler does not
+ *   reap unmanaged runs);
+ * - admission re-checks the per-run delegation limit under a run-scoped advisory lock inside the
+ *   child's own transaction, so parallel delegations on different replicas cannot exceed it;
+ * - a delegation the budget would refuse while sibling children still run is recorded as waiting
+ *   and re-evaluated on each call (parallelDelegations), up to the same bound as in process;
+ * - each call waits on the child row up to `pollWindowMs`, then answers `pending`.
+ *
+ * Every refusal and result uses the same helpers, and so the same messages, as in process.
+ */
+export async function durableDelegate(ctx, callId, name, argsJson) {
+    const { runId, existingRun, loaded, providers, db, ledger, sessionId } = ctx;
+    const now = ctx.now ?? Date.now;
+    const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const finish = async (result) => {
+        await ledger.recordResult(sessionId, callId, result);
+        return { result };
+    };
+    const claimed = await ledger.claim(sessionId, callId, "builtin.call");
+    if (claimed.outcome === "done")
+        return { result: String(claimed.result) };
+    const state = await ledger.delegation(sessionId, callId);
+    const startedAt = state?.createdAt.getTime() ?? now();
+    const boundName = name.slice(DELEGATE_TOOL_PREFIX.length);
+    const edge = loaded.subAgentEdges.find((e) => e.boundName === boundName);
+    if (!edge) {
+        return finish(JSON.stringify({ error: "no_such_subagent", message: `No sub-agent is bound to name "${boundName}".` }));
+    }
+    const executor = providers.executor;
+    if (!executor) {
+        return finish(JSON.stringify({
+            error: "delegation_unavailable",
+            message: "This execution context has no Executor wired in, so the sub-agent cannot be dispatched.",
+        }));
+    }
+    const parsedArgs = parseDelegateArgs(argsJson);
+    if ("refusal" in parsedArgs)
+        return finish(parsedArgs.refusal);
+    const { args } = parsedArgs;
+    const authorized = await authorizeDelegation(db, loaded.agentId, edge, boundName, args);
+    if ("refusal" in authorized)
+        return finish(authorized.refusal);
+    const { childAgent } = authorized;
+    const coding = childAgent.kind === "coding";
+    const { queueTimeoutSec } = loadCodingConcurrencyConfig();
+    let childRunId = state?.childRunId ?? null;
+    if (!childRunId && state?.childAgentId === edge.childAgentId) {
+        // A replica that died between dispatching the child and recording it left the child row:
+        // adopt it rather than refusing this very delegation as a duplicate.
+        childRunId = (await findDelegationChild(db, runId, edge.childAgentId, callId))?.id ?? null;
+        // Recorded, so later calls wait on it by id.
+        if (childRunId) {
+            await ledger.setDelegation(sessionId, callId, { status: "pending", childAgentId: edge.childAgentId, childRunId });
+        }
+    }
+    if (!childRunId) {
+        // About to create a child: its task is model-written and stored, so mask the parent's secret
+        // values first. Only here, never on a poll of an existing child (a transient secret-read
+        // failure must not orphan a running child). Recorded as the call's result, which also completes a waiting row; the model's retry comes with a new callId.
+        const maskedArgsJson = await maskModelWrittenArgs({ db, secrets: providers.secrets, agentId: loaded.agentId, runId }, name, argsJson);
+        if (maskedArgsJson === undefined) {
+            return finish(JSON.stringify({ error: "secret_check_unavailable", message: SECRET_CHECK_UNAVAILABLE_MESSAGE }));
+        }
+        const maskedArgs = parseDelegateArgs(maskedArgsJson);
+        if ("refusal" in maskedArgs)
+            return finish(maskedArgs.refusal);
+        const dispatchArgs = maskedArgs.args;
+        const limit = loaded.maxDelegationsPerRun ?? 1;
+        const refusalNow = async (reader) => {
+            const prior = await reader.run.findMany({ where: { parentRunId: runId }, select: { agentId: true } });
+            return delegationLimitRefusal({
+                priorChildAgentIds: prior.map((p) => p.agentId),
+                waitingChildAgentIds: await ledger.waitingChildAgentIds(sessionId, callId),
+                childAgentId: edge.childAgentId,
+                boundName,
+                limit,
             });
-            if (!result.ok) {
-                return JSON.stringify({ error: result.errorKind, message: result.errorMessage });
-            }
-            return JSON.stringify(result.value);
         };
-        // Live progress for observers (MCP get_run, the viewer). Absolute totals, so a DBOS replay
-        // re-writing them is harmless. Written into the run's own cost columns on purpose: the run
-        // tree's shared budget (computeRunTreeSpend) then counts a running parent's spend so far, as it
-        // already does for coding runs, whose proxy ledger writes their totals live. Best-effort: a
-        // failed write only delays what observers see, and finishRun writes the final totals anyway.
-        const onProgress = async (progress) => {
-            try {
-                await db.run.updateMany({
-                    where: { id: runId, status: "running" },
-                    data: {
-                        turns: progress.turns,
-                        tokensIn: progress.usage.tokensIn,
-                        tokensOut: progress.usage.tokensOut,
-                        costUsd: progress.usage.costUsd,
-                        heartbeatAt: new Date(),
-                    },
-                });
+        const limitRefusal = await refusalNow(db);
+        if (limitRefusal)
+            return finish(limitRefusal);
+        // parallelDelegations: a child the budget would refuse while a sibling still runs waits for a
+        // sibling to finish and free its hold, up to the child's own wait bound. With no sibling
+        // running it goes ahead and is refused at dispatch or at its first turn, as in process.
+        if (loaded.parallelDelegations) {
+            const siblings = await db.run.count({ where: { parentRunId: runId, status: { in: [...DRIVABLE] } } });
+            if (siblings > 0) {
+                const runTimeoutSec = coding ? (childAgent.codingProfile?.timeoutSec ?? 0) : 0;
+                const boundMs = (queueTimeoutSec + runTimeoutSec + CODING_CHILD_WAIT_GRACE_SEC) * 1000;
+                const { exhaustedBy } = await effectiveBudgetForRun(db, childAgent, new Date(), runId);
+                if (exhaustedBy && now() - startedAt < boundMs) {
+                    await ledger.setDelegation(sessionId, callId, { status: "waiting_budget", childAgentId: edge.childAgentId });
+                    return { pending: true };
+                }
             }
-            catch (err) {
-                runnerLog.warn({ err, runId }, "failed to record run progress");
+        }
+        // Recorded before dispatch, so a replica dying in between leaves a row the next call adopts.
+        await ledger.setDelegation(sessionId, callId, { status: "pending", childAgentId: edge.childAgentId });
+        let dispatched;
+        let refusedUnderLock = null;
+        try {
+            dispatched = await dispatchRun({
+                db,
+                executor,
+                selfDefects: { db, issueTrackers: ctx.issueTrackers },
+                agentId: edge.childAgentId,
+                trigger: "subagent",
+                ...(coding
+                    ? {
+                        codingTask: dispatchArgs.task,
+                        continuesCodingRunId: dispatchArgs.continuePriorRun,
+                        mergeOrder: dispatchArgs.mergeOrder,
+                    }
+                    : {
+                        taskOverride: delegationTaskOverride(dispatchArgs),
+                        grantedParentMemoryKeys: dispatchArgs.grantParentMemoryKeys ?? [],
+                    }),
+                parentRunId: runId,
+                parentCallId: callId,
+                // The child's result flows back into this run, which the triggerer sees, so the child is visible to them too.
+                triggeredById: existingRun.triggeredById,
+                beforePersist: async (tx) => {
+                    // One admission per parent at a time, across every replica.
+                    await tx.$queryRaw `SELECT 1 AS locked FROM (SELECT pg_advisory_xact_lock(hashtext(${runId}))) AS l`;
+                    refusedUnderLock = await refusalNow(tx);
+                    return refusedUnderLock === null;
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof ContinuationRefusedError) {
+                return finish(JSON.stringify({
+                    error: "continuation_refused",
+                    message: `${err.message} No sub-agent run was started. Do not open a new pull request in its place: ` +
+                        "tell the requester that this wardby deployment cannot continue that pull request's branch.",
+                }));
             }
-        };
+            // Recorded as the call's result, so the model can report it and a retried callId never
+            // dispatches twice. Only the leading code is exposed: messages can carry internals.
+            const code = declaredCodeOf(err);
+            const values = await ctx.secretValues?.().catch(() => undefined);
+            logUnexpectedError(runnerLog, err, values, "delegation dispatch failed", { runId, boundName });
+            return finish(JSON.stringify({
+                error: "dispatch_failed",
+                message: `The sub-agent run could not be created${code ? ` (${code})` : ""}.`,
+            }));
+        }
+        if (!dispatched) {
+            return finish(refusedUnderLock ??
+                JSON.stringify({ error: "dispatch_failed", message: "The sub-agent run could not be created." }));
+        }
+        childRunId = dispatched.run.id;
+        await ledger.setDelegation(sessionId, callId, { status: "pending", childAgentId: edge.childAgentId, childRunId });
+        runnerLog.info({ runId, childRunId, boundName, kind: childAgent.kind, durable: true }, "delegation started");
+    }
+    const codingRun = coding
+        ? await db.codingRun.findUnique({ where: { runId: childRunId }, select: { timeoutSec: true } })
+        : null;
+    const boundMs = coding
+        ? (queueTimeoutSec + (codingRun?.timeoutSec ?? 0) + CODING_CHILD_WAIT_GRACE_SEC) * 1000
+        : SANDBOX_CHILD_WAIT_SEC * 1000;
+    const windowEnd = now() + (ctx.pollWindowMs ?? DELEGATION_POLL_WINDOW_MS);
+    for (;;) {
+        const child = await db.run.findUniqueOrThrow({ where: { id: childRunId } });
+        if (!DRIVABLE.includes(child.status)) {
+            runnerLog.info({ runId, childRunId, boundName, outcome: child.status, durable: true }, "delegation finished");
+            if (!coding) {
+                return finish(nativeChildResult(child, args.mergeOrder !== undefined ? MERGE_ORDER_IGNORED_NOTE : undefined));
+            }
+            const stored = await db.codingRun
+                .findUnique({ where: { runId: childRunId }, select: { result: true } })
+                .catch(() => null);
+            return finish(codingChildResult(child, stored?.result, await loadBudgetEvent(db, childRunId)));
+        }
+        if (now() - startedAt >= boundMs) {
+            await executor.stop(childRunId, "sub-agent wait timed out").catch((err) => {
+                runnerLog.warn({ err, childRunId, runId }, "failed to stop a timed-out sub-agent run");
+            });
+            return finish(JSON.stringify({
+                error: "subagent_wait_timed_out",
+                runId: childRunId,
+                message: coding
+                    ? "The coding sub-agent did not finish within its queue timeout plus run timeout; it was stopped and produced no result."
+                    : "The sub-agent did not finish in time; it was stopped and produced no result.",
+            }));
+        }
+        const remaining = windowEnd - now();
+        if (remaining <= 0)
+            return { pending: true };
+        await sleep(Math.min(ctx.pollIntervalMs ?? 1_000, remaining));
+    }
+}
+/** The integrations a native run uses, as executeRun derives them from its providers. */
+export function nativeRunIntegrations(providers, db) {
+    const reviewHosts = configuredReviewHosts(providers.reviewHosts);
+    const repoAccess = reviewHosts
+        ? (providers.repoAccess ?? createRepoAccessGate({ db, hosts: reviewHosts }))
+        : undefined;
+    return { reviewHosts, repoAccess, issueTrackers: configuredIssueTrackers(providers.issueTrackers) };
+}
+/** How long a sandbox run's gateway session (and so its capability) stays valid. */
+export const SANDBOX_RUN_MAX_SEC = SANDBOX_CHILD_WAIT_SEC;
+/**
+ * Starts a sandbox-mode run's trusted half: loads and pins the run, marks it running, records its
+ * gateway session (capability hash, deadline, budget, snapshot), and records `native-sandbox` as
+ * its execution backend — all before any worker exists. The caller launches the worker with the
+ * returned input, which carries the gateway URL and the one-time capability.
+ */
+export async function createSandboxSession(options) {
+    const { runId, providers, db, ledger } = options;
+    const now = options.now ?? new Date();
+    const existingRun = await db.run.findUnique({ where: { id: runId } });
+    if (!existingRun)
+        throw new Error(`Unknown run "${runId}".`);
+    if (!DRIVABLE.includes(existingRun.status))
+        return { kind: "ended", run: existingRun };
+    if (existingRun.nativeExecutionMode !== "sandbox")
+        throw new Error(`Run "${runId}" is not a sandbox-mode run.`);
+    const { reviewHosts, repoAccess, issueTrackers } = nativeRunIntegrations(providers, db);
+    const finishContext = { runId, db, providers, reviewHosts, repoAccess, issueTrackers };
+    const loadedOrUnavailable = await loadNativeRun({
+        runId,
+        existingRun,
+        providers,
+        db,
+        step: runStepInline,
+        reviewHosts,
+        issueTrackers,
+    });
+    if ("unavailable" in loadedOrUnavailable) {
+        return { kind: "ended", run: await failNativeRun(finishContext, new Error(loadedOrUnavailable.unavailable)) };
+    }
+    const loaded = loadedOrUnavailable;
+    if (loaded.kind === "coding") {
+        return { kind: "ended", run: await failNativeRun(finishContext, new Error(CODING_EXECUTOR_NOT_CONFIGURED)) };
+    }
+    const tools = createNativeRunTools({
+        runId,
+        existingRun,
+        loaded,
+        providers,
+        db,
+        reviewHosts,
+        repoAccess,
+        issueTrackers,
+    });
+    let input;
+    try {
+        input = sandboxWorkerInput(runId, loaded, tools);
+    }
+    catch (err) {
+        return { kind: "ended", run: await failNativeRun(finishContext, err) };
+    }
+    await db.run.updateMany({ where: { id: runId, status: { in: [...DRIVABLE] } }, data: { status: "running" } });
+    const capability = randomBytes(32).toString("base64url");
+    const snapshot = { input, loaded };
+    const session = await ledger.createSession({
+        runId,
+        capabilityHash: sandboxCapabilityHash(capability),
+        deadlineAt: new Date(now.getTime() + SANDBOX_RUN_MAX_SEC * 1000),
+        budgetUsd: loaded.agent.budgetUsd,
+        snapshot: snapshot,
+        networkReadyAt: options.networkReady === false ? null : now,
+    });
+    // The handle exists before any worker does, so the reconciler routes a stale run to the sandbox executor.
+    await db.run.updateMany({
+        where: { id: runId, executionBackend: null },
+        data: { executionBackend: NATIVE_SANDBOX_BACKEND },
+    });
+    return {
+        kind: "started",
+        sessionId: session.id,
+        capability,
+        input: { ...input, gateway: { url: options.gatewayUrl, capability } },
+        secretValues: () => userToolSecretValues(tools, Object.keys(input.userTools)),
+    };
+}
+/**
+ * Every secret value the sandbox run's user tools `names` may read (readable or brokered): what its
+ * worker can be handed, so what the gateway checks its cause codes against and a launcher masks
+ * from the worker's output tail. Rejects when any read fails (readRedactionValues).
+ */
+export async function userToolSecretValues(tools, names) {
+    return (await Promise.all(names.map((name) => tools.readableSecretValues(name)))).flat();
+}
+/** Run.executionBackend for a sandbox-mode run whose worker is (or was) launched. */
+export const NATIVE_SANDBOX_BACKEND = "native-sandbox";
+/** The stored form of a sandbox capability: never the token itself. */
+export function sandboxCapabilityHash(capability) {
+    return createHash("sha256").update(capability).digest("hex");
+}
+/** Drives an existing Run (created by `createRun` or the scheduler) to a terminal state. */
+export async function executeRun(runId, providers, db = defaultDb, onText, step = runStepInline) {
+    // Counted so a shutdown waits for this run instead of abandoning it (core/in-flight-runs.ts).
+    return trackRun(runId, () => executeTrackedRun(runId, providers, db, onText, step));
+}
+async function executeTrackedRun(runId, providers, db, onText, step) {
+    const existingRun = await db.run.findUnique({ where: { id: runId } });
+    if (!existingRun) {
+        throw new Error(`Unknown run "${runId}".`);
+    }
+    // Pre-flight guard. A run that already reached a terminal state must never
+    // be re-driven: a durable workflow re-dispatched after the reconciler
+    // reaped its row (rollback to EXECUTOR=in-process, then roll forward) would
+    // otherwise re-spend the whole run against a `lost` row, and a duplicate
+    // attempt of a finished run would spend a second time for a result no write
+    // can land. Cheaper and clearer than letting it run and discarding the
+    // result at the conditional write.
+    if (!DRIVABLE.includes(existingRun.status)) {
+        runnerLog.info({ runId, status: existingRun.status }, "skipping execution of an already-terminal run");
+        return existingRun;
+    }
+    const reviewHosts = configuredReviewHosts(providers.reviewHosts);
+    const repoAccess = reviewHosts
+        ? (providers.repoAccess ?? createRepoAccessGate({ db, hosts: reviewHosts }))
+        : undefined;
+    const issueTrackers = configuredIssueTrackers(providers.issueTrackers);
+    // Inline execution checks for a stop before every step (stopAwareStep); a durable executor passes
+    // its own step runner, which does its own check (DbosExecutor wraps it in stopAwareStep too).
+    if (step === runStepInline)
+        step = stopAwareStep(db, runId);
+    // Fails a run that ends before its engine starts, closing what its trigger opened (the review
+    // check, the host and issue status comments) exactly as the normal and catch paths below do.
+    // Deliberately no self-defect: every caller is a configuration state, not this run's defect (an
+    // admin disabled or removed the model, or this deployment has no coding or native sandbox
+    // executor), and filing would open one defect per affected agent rather than describe a failure
+    // of that agent.
+    const finishEarly = async (reason) => {
+        const { error } = await maskRunTexts({ runId, db, providers }, { error: reason });
+        const finished = await finishRun(db, runId, { status: "failed", error, finishedAt: new Date() });
+        await closeOpenHostCheck(db, finished, reviewHosts);
+        await completeHostStatus(db, finished, reviewHosts);
+        await completeIssueStatus(db, finished, issueTrackers);
+        await emitRunFinishedEvents(db, finished);
+        return finished;
+    };
+    // Decided by the run's own snapshot, before any work or spend (no pricing pin, no engine): a
+    // sandbox-mode run never executes in the control plane.
+    const sandboxed = existingRun.nativeExecutionMode === "sandbox";
+    if (sandboxed && !providers.nativeSandbox)
+        return finishEarly(NATIVE_SANDBOX_NOT_CONFIGURED);
+    const loadedOrUnavailable = await loadNativeRun({
+        runId,
+        existingRun,
+        providers,
+        db,
+        step,
+        reviewHosts,
+        issueTrackers,
+    });
+    if ("unavailable" in loadedOrUnavailable)
+        return finishEarly(loadedOrUnavailable.unavailable);
+    const loaded = loadedOrUnavailable;
+    if (loaded.kind === "coding")
+        return finishEarly(CODING_EXECUTOR_NOT_CONFIGURED);
+    // Conditional on DRIVABLE rather than on `pending`: an adopted attempt
+    // legitimately finds the row already `running`, but a terminal row must
+    // never be flipped back to `running`.
+    await db.run.updateMany({ where: { id: runId, status: { in: [...DRIVABLE] } }, data: { status: "running" } });
+    const finishContext = { runId, db, providers, reviewHosts, repoAccess, issueTrackers };
+    try {
+        const tools = createNativeRunTools({
+            runId,
+            existingRun,
+            loaded,
+            providers,
+            db,
+            reviewHosts,
+            repoAccess,
+            issueTrackers,
+        });
+        const { runSandboxTool } = tools;
+        const onProgress = (progress) => recordNativeRunProgress(db, runId, progress);
+        const llm = loaded.pricing && providers.llm instanceof RoutingLlmProvider
+            ? providers.llm.forRun(loaded.pricing.entry)
+            : providers.llm;
+        if (sandboxed && providers.nativeSandbox) {
+            // The turn loop runs in a worker; this process serves its calls from the same tools and LLM.
+            const engineResult = await runSandboxedEngine({
+                runId,
+                input: sandboxWorkerInput(runId, loaded, tools),
+                ctx: { providers: { llm }, onText, onProgress },
+                builtinHandler: tools.builtinHandler,
+                privilegedHostFor: tools.privilegedHostFor,
+                readableSecretValues: tools.readableSecretValues,
+                drivability: () => runDrivability(db, runId),
+                launcher: providers.nativeSandbox,
+            });
+            return await finishNativeRun(finishContext, loaded.agent.model, engineResult);
+        }
         const engineResult = await providers.engine.run({
             agent: loaded.agent,
             tools: loaded.tools,
-            providers: {
-                llm: loaded.pricing && providers.llm instanceof RoutingLlmProvider
-                    ? providers.llm.forRun(loaded.pricing.entry)
-                    : providers.llm,
-            },
+            providers: { llm },
             runSandboxTool,
             // A replay recorded before this flag existed has none: its delegations stay sequential.
             ...(loaded.parallelDelegations
@@ -994,70 +1910,26 @@ async function executeTrackedRun(runId, providers, db, onText, step) {
             onProgress,
             step,
         });
-        const { run: finished, claimed } = await finishRunClaimed(db, runId, {
-            status: engineResult.status,
-            tokensIn: engineResult.usage.tokensIn,
-            tokensOut: engineResult.usage.tokensOut,
-            costUsd: engineResult.usage.costUsd,
-            error: engineResult.error ?? null,
-            finalText: engineResult.finalText || null,
-            turns: engineResult.turns,
-            finishedAt: new Date(),
-        });
-        // Per-model usage is written on the same path as Run.costUsd: any future mid-run cost write must write usage too.
-        await recordNativeModelUsage(db, runId, loaded.agent.model, engineResult.usage);
-        await closeOpenHostCheck(db, finished, reviewHosts);
-        await completeHostStatus(db, finished, reviewHosts);
-        await completeIssueStatus(db, finished, issueTrackers);
-        // After the issue status, so IssuePullRequest rows for this run exist. Bounded and never throws.
-        if (claimed)
-            await updateRelatedPullRequests(db, finished, reviewHosts, issueTrackers);
-        if (claimed && providers.executor && reviewHosts && repoAccess) {
-            await startReviewFixAfterReview(runId, {
-                db,
-                executor: providers.executor,
-                hosts: reviewHosts,
-                repoAccess,
-                issueTrackers,
-            });
-        }
-        // Only the call that made the row terminal files, so a run another finalizer (the reconciler) ended is not
-        // filed twice. Bounded and never throws.
-        if (claimed)
-            await fileSelfDefect(db, issueTrackers, finished);
-        return finished;
+        return await finishNativeRun(finishContext, loaded.agent.model, engineResult);
     }
     catch (err) {
         // Defensive backstop: the engine is expected to catch its own errors
         // and return a "failed" EngineResult, but an unexpected throw here
         // (a real bug, or tool-loading failing outside the per-tool try above)
-        // must still never leave the run dangling in "running". A cancellation
-        // is not a failure: it carries the operator's own reason.
-        const { run: finished, claimed } = await finishRunClaimed(db, runId, {
-            status: err instanceof RunCancelledError ? "cancelled" : "failed",
-            error: err instanceof Error ? err.message : String(err),
-            finishedAt: new Date(),
-        });
-        await closeOpenHostCheck(db, finished, reviewHosts);
-        await completeHostStatus(db, finished, reviewHosts);
-        await completeIssueStatus(db, finished, issueTrackers);
-        // After the issue status, so IssuePullRequest rows for this run exist. Bounded and never throws.
-        if (claimed)
-            await updateRelatedPullRequests(db, finished, reviewHosts, issueTrackers);
-        if (claimed && providers.executor && reviewHosts && repoAccess) {
-            await startReviewFixAfterReview(runId, {
-                db,
-                executor: providers.executor,
-                hosts: reviewHosts,
-                repoAccess,
-                issueTrackers,
-            });
+        // must still never leave the run dangling in "running".
+        if (err instanceof RunOwnershipLostError) {
+            // Another execution of this run recorded a step first and owns the run now. Write nothing
+            // and fire no settle side effects: the winner makes the terminal write. Rethrown (not
+            // returned) so the durable executor hands the conflict back to its SDK, which parks this
+            // attempt instead of recording a workflow outcome under the winner.
+            logRunOwnershipLost(runId, err);
+            throw err;
         }
-        // Only the call that made the row terminal files, so a run another finalizer (the reconciler) ended is not
-        // filed twice. Bounded and never throws.
-        if (claimed)
-            await fileSelfDefect(db, issueTrackers, finished);
-        return finished;
+        // A replay that no longer matches its record (a run recorded by a release whose steps differ)
+        // cannot continue: it ends lost, not failed, through the same settle path.
+        if (err instanceof StepReplayMismatchError)
+            return loseNativeRun(finishContext, STEPS_CHANGED_REASON);
+        return failNativeRun(finishContext, err);
     }
 }
 /**