@wardby/cli 0.5.3 → 0.6.0

package/dist/providers/executor/container.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { withBaseCommit } from "../../coding/base-commit.js";
+import { buildClaudeContext, MAX_RECORDED_SKIPS } from "../../coding/claude-context.js";
 import { normalizeCollectExclusions } from "../../coding/collect-exclude.js";
 import { codingProviderForModelProvider } from "../../coding/provider.js";
 import { CodingProfileSchema } from "../../coding/profile.js";
@@ -19,7 +20,7 @@ import { logger } from "../../core/logger.js";
 import { requiredLevel } from "../../core/repo-access.js";
 import { ensurePrivateDirectory } from "../../core/private-directory.js";
 import { codingRunObserver } from "../../coding/observability.js";
-import { CODING_PROTOCOL_VERSION, CodingRunResultSchema, CodingTaskInputSchema, parseCodingAgentOutputJson, redactAndTruncate, } from "../../coding/protocol.js";
+import { CODING_PROTOCOL_VERSION, CodingRunResultSchema, CodingTaskInputSchema, MAX_CODING_INPUT_BYTES, parseCodingAgentOutputJson, redactAndTruncate, } from "../../coding/protocol.js";
 import { parseStoredEntry } from "../llm/catalog-types.js";
 import { resolveCodingEntry } from "../../core/run-pricing.js";
 import { CODING_PROXY_ALIAS, CODING_PROXY_PORT, isImmutableDockerImage } from "../jobs/docker-isolation.js";
@@ -28,6 +29,8 @@ import { ISSUE_KEY, ISSUE_TRACKER_NAMES } from "../issue-tracker/types.js";
 import { HEARTBEAT_TIMEOUT_MS } from "../../core/timing.js";
 import { collectRelatedPullRequests } from "../../core/related-pull-requests.js";
 const containerLog = logger.child({ module: "container-executor" });
+/** A logged context skip path is cut to this many characters: a refused import is reported as written. */
+const MAX_LOGGED_SKIP_PATH_CHARS = 256;
 /** The input path in a spec built only to ask the launcher about capacity; never written or read. */
 const CAPACITY_PROBE_INPUT = "/dev/null";
 const TERMINAL_STATUSES = new Set(["succeeded", "failed", "refused", "lost", "budget_exhausted", "cancelled"]);
@@ -109,6 +112,7 @@ export class PrismaContainerExecutionStore {
             rootCodingRunId: row.codingRun.rootCodingRunId,
             issueProvider: row.codingRun.issueProvider,
             issueKey: row.codingRun.issueKey,
+            mergeOrder: row.codingRun.mergeOrder,
             budgetUsd: Number(row.codingRun.budgetReservedUsd),
             agentBudgetUsd: Number(row.agent.budgetUsd),
             budgetGroupName: row.agent.budgetGroup?.name ?? null,
@@ -126,6 +130,8 @@ export class PrismaContainerExecutionStore {
             workspaceDiskMb: row.codingRun.workspaceDiskMb,
             debugTrace: row.codingRun.debugTrace,
             maxTurns: row.codingRun.maxTurns,
+            repoSkills: row.codingRun.repoSkills,
+            claudeBareMode: row.codingRun.claudeBareMode,
             services: row.codingRun.services,
             failureCategory: row.codingRun.failureCategory,
             profileRepository: row.agent.codingProfile?.repository ?? null,
@@ -141,6 +147,7 @@ export class PrismaContainerExecutionStore {
             repository: pr.repository,
             number: pr.number,
             ...(pr.state ? { state: pr.state } : {}),
+            ...(pr.mergeOrder !== undefined ? { mergeOrder: pr.mergeOrder } : {}),
         }));
     }
     async claimProvisioning(runId, claimId) {
@@ -545,7 +552,7 @@ export class ContainerExecutor {
                 spendEnabled = true;
                 sessionId = session.id;
                 this.options.capabilities.set(runId, session.capability);
-                const inputArtifact = await this.writeInput(run, deadlineAt, workspace.baseCommit);
+                const inputArtifact = await this.writeInput(run, deadlineAt, workspace);
                 const beforeLaunch = await this.requireCurrent(runId);
                 if (TERMINAL_STATUSES.has(beforeLaunch.status))
                     throw new Error("coding_run_no_longer_active");
@@ -715,7 +722,14 @@ export class ContainerExecutor {
             const { issue } = this.issueFor(run);
             return {
                 related: {
-                    entries: [...earlier, { repository: run.repository, self: true }],
+                    entries: [
+                        ...earlier,
+                        {
+                            repository: run.repository,
+                            self: true,
+                            ...(run.mergeOrder != null ? { mergeOrder: run.mergeOrder } : {}),
+                        },
+                    ],
                     ...(issue ? { issue } : {}),
                 },
             };
@@ -920,6 +934,19 @@ export class ContainerExecutor {
             }
             await rm(this.artifactPath(run.runId), { recursive: true, force: true }).catch(() => undefined);
             this.emit({ stage: "cleanup", runId: run.runId, jobId: handle.id, cleanupSucceeded: true });
+            await this.notifyTerminal(run.runId);
+        }
+    }
+    /** Runs the onCodingRunTerminal hook; nothing it does, throws, or rejects reaches the caller. */
+    async notifyTerminal(runId) {
+        const hook = this.options.onCodingRunTerminal;
+        if (!hook)
+            return;
+        try {
+            await hook(runId);
+        }
+        catch (err) {
+            containerLog.warn({ err, runId }, "coding run terminal hook failed");
         }
     }
     /** The package report is informational: any failure loading it (a
@@ -965,8 +992,10 @@ export class ContainerExecutor {
     }
     resolveCodingWorkerImage(selector) {
         if (selector.provider === "claude-code") {
+            // workerImageRef never replaces the Claude Code agent image (the container that holds the
+            // run's key); on a Claude Code agent it selects the tool runner (claudeToolImage).
             this.claudeToolImage(selector);
-            const image = selector.workerImageRef ?? this.options.claudeWorkerImage;
+            const image = this.options.claudeWorkerImage;
             if (!image)
                 throw new Error("coding_provider_not_configured:claude-code");
             if (!isImmutableDockerImage(image))
@@ -976,7 +1005,7 @@ export class ContainerExecutor {
         if (selector.provider !== "codex") {
             throw new Error(`coding_provider_unsupported:${String(selector.provider)}`);
         }
-        if (selector.workerImageRef) {
+        if (selector.workerImageRef !== null) {
             if (!isImmutableDockerImage(selector.workerImageRef))
                 throw new Error("coding_worker_image_invalid");
             return selector.workerImageRef;
@@ -997,10 +1026,20 @@ export class ContainerExecutor {
     resolveCodingToolImage(selector) {
         return selector.provider === "claude-code" ? this.claudeToolImage(selector) : null;
     }
-    /** The tool runner is what runs a Claude agent's commands, so it is what the toolchain selects. */
+    /**
+     * The tool runner is what runs a Claude agent's commands, so it is what the toolchain selects —
+     * unless the agent has a BYO workerImageRef, which replaces the tool runner directly (never the
+     * agent image; see resolveCodingWorkerImage).
+     */
     claudeToolImage(selector) {
         if (!this.options.claudeToolRunnerImage)
             throw new Error("coding_provider_not_configured:claude-code");
+        // An admin-set custom image (workerImageRef) is where this agent's commands run.
+        if (selector.workerImageRef !== null) {
+            if (!isImmutableDockerImage(selector.workerImageRef))
+                throw new Error("coding_worker_image_invalid");
+            return selector.workerImageRef;
+        }
         const image = selector.toolchain === "node" && selector.toolchainVersion === null
             ? this.options.claudeToolRunnerImage
             : selector.toolchainVersion !== null
@@ -1038,6 +1077,10 @@ export class ContainerExecutor {
     supportsCodingServices(provider) {
         return this.options.jobs.supportsServicesFor?.(provider) === true;
     }
+    /** Delegates to the job launcher's own warm-up (Executor.warmUp); a no-op for a launcher without one. */
+    async warmUp() {
+        await this.options.jobs.warmUp?.();
+    }
     async requireCurrent(runId) {
         const current = await this.options.store.load(runId);
         if (!current)
@@ -1099,7 +1142,7 @@ export class ContainerExecutor {
             return this.options.anthropicCredentialRef;
         throw new Error("coding_provider_not_configured:claude-code");
     }
-    async writeInput(run, deadlineAt, baseCommit) {
+    async writeInput(run, deadlineAt, workspace) {
         await ensurePrivateDirectory(this.artifactRoot);
         const rootReal = await realpath(this.artifactRoot);
         const directory = resolve(rootReal, run.runId);
@@ -1111,11 +1154,24 @@ export class ContainerExecutor {
         const destination = join(directory, "input.json");
         const temporary = join(directory, `.input-${randomUUID()}.tmp`);
         const services = parseStoredServices(run.services);
-        const task = withBaseCommit(run.task, baseCommit);
-        if (task === run.task && /^[0-9a-f]{40}$/.test(baseCommit)) {
+        const task = withBaseCommit(run.task, workspace.baseCommit);
+        if (task === run.task && /^[0-9a-f]{40}$/.test(workspace.baseCommit)) {
             containerLog.warn({ event: "coding.base_commit_omitted", runId: run.runId }, "the coding task left no room for the base commit line");
         }
-        const input = CodingTaskInputSchema.parse({
+        // A repository context read must never fail a run ("the run never fails because of context"):
+        // any fs error (an inaccessible workspace, EACCES, ...) is logged once and swallowed, leaving
+        // claudeContext null, exactly as if the run had nothing to load.
+        let claudeContext = null;
+        if (run.provider === "claude-code") {
+            try {
+                claudeContext = await buildClaudeContext(workspace.workspacePath, { skills: run.repoSkills !== false });
+            }
+            catch (error) {
+                const code = error?.code;
+                containerLog.warn({ event: "coding.claude_context_unavailable", runId: run.runId, ...(code ? { code } : {}) }, "repository context could not be read; continuing without it");
+            }
+        }
+        const build = (contextFiles) => CodingTaskInputSchema.parse({
             schemaVersion: CODING_PROTOCOL_VERSION,
             runId: run.runId,
             repository: run.repository,
@@ -1130,11 +1186,45 @@ export class ContainerExecutor {
             ...(run.debugTrace ? { debugTrace: true } : {}),
             // Only when the agent sets one: every other run's input stays exactly what older workers expect.
             ...(run.maxTurns ? { maxTurns: run.maxTurns } : {}),
+            // Only when off: every other run's input stays exactly what older workers expect.
+            ...(run.repoSkills === false ? { repoSkills: false } : {}),
+            // Only when off: every other run's input stays exactly what older workers expect.
+            ...(run.claudeBareMode === false ? { claudeBareMode: false } : {}),
             // Only when there are some: every other run's input stays exactly what older workers expect.
             ...(services.length > 0 ? { services: workerServices(services) } : {}),
+            // Only when there is something to load: every other run's input stays exactly what older workers expect.
+            ...(contextFiles.length > 0 ? { claudeContext: { files: contextFiles } } : {}),
         });
+        // The content limits bound bytes, but JSON escaping can grow them up to sixfold (a control
+        // character becomes \u00XX), so a hostile repository could still push input.json past
+        // MAX_CODING_INPUT_BYTES and fail the launch. Drop context files from the tail (skills, then the
+        // deepest imports; the root instructions go last) until the serialized input fits.
+        const contextFiles = [...(claudeContext?.files ?? [])];
+        const skipped = [...(claudeContext?.skipped ?? [])];
+        let skippedOverflow = claudeContext?.skippedOverflow ?? 0;
+        let serialized = JSON.stringify(build(contextFiles));
+        while (contextFiles.length > 0 && Buffer.byteLength(serialized) > MAX_CODING_INPUT_BYTES) {
+            const dropped = contextFiles.pop();
+            if (skipped.length < MAX_RECORDED_SKIPS)
+                skipped.push({ path: dropped.path, reason: "limit" });
+            else
+                skippedOverflow++;
+            serialized = JSON.stringify(build(contextFiles));
+        }
+        for (const skip of skipped) {
+            containerLog.warn({
+                event: "coding.claude_context_skipped",
+                runId: run.runId,
+                // A refused import is logged as written, which a repository can make arbitrarily long.
+                path: skip.path.slice(0, MAX_LOGGED_SKIP_PATH_CHARS),
+                reason: skip.reason,
+            }, "a repository context file was not loaded");
+        }
+        if (skippedOverflow > 0) {
+            containerLog.warn({ event: "coding.claude_context_skipped", runId: run.runId, overflow: skippedOverflow }, "further repository context files were not loaded");
+        }
         // The run directory is 0700; world-readable mode only crosses Docker's UID boundary.
-        await writeFile(temporary, JSON.stringify(input), { flag: "wx", mode: 0o444 });
+        await writeFile(temporary, serialized, { flag: "wx", mode: 0o444 });
         await rename(temporary, destination);
         return destination;
     }

package/dist/providers/executor/dbos.d.ts

@@ -11,14 +11,56 @@
  * The heartbeat is kept while the workflow runs here so the reconciler's
  * stale-heartbeat detection is unchanged; the reconciler consults
  * `recover()` (Task 6) before declaring a DBOS run lost.
+ *
+ * A stalled-but-alive owner can overlap an adopted attempt of the same run:
+ * whichever records a step second loses ownership, stops at that step
+ * without writing the run, and hands the SDK's conflict back so DBOS parks
+ * it as a duplicate execution (see dbosStep and runInsideWorkflow).
  */
+import pg from "pg";
 import type { PrismaClient } from "#prisma";
 import type { DbosConfig } from "../../config/providers.js";
+import { type StepRunner } from "../engine/types.js";
 import { type NativeRunProviders, type RunnerDb } from "../../core/runner.js";
+import { type DatabaseAuth, type PgAuthOptions } from "../../core/pg-auth.js";
 import type { Executor, ExecutionRecoveryResult, PersistedExecutionHandle } from "./types.js";
 export declare const DBOS_BACKEND = "dbos";
 type Providers = NativeRunProviders;
 type Db = RunnerDb & Pick<PrismaClient, "run">;
+/**
+ * DBOS.setConfig input. Under password auth this is exactly what launch() always passed, and DBOS
+ * opens its own pool from the URL. Under rds-iam DBOS gets a pool whose password is the IAM token;
+ * DBOS then runs its migrations, queries and LISTEN through that pool and never opens a URL
+ * connection (system_database.js: a custom pool skips database creation and is what every
+ * connection borrows from). The pool copies what DBOS would have set on its own: size, connect
+ * timeout and application_name. DBOS never ends a pool it was given — see endSystemPool().
+ */
+export declare function dbosLaunchConfig(config: DbosConfig, executorId: string, auth: DatabaseAuth, pgAuth?: PgAuthOptions): {
+    name: string;
+    systemDatabaseUrl: string;
+    systemDatabaseSchemaName: string;
+    executorID: string;
+    runAdminServer: false;
+    logLevel: "warn";
+    systemDatabasePool?: pg.Pool;
+};
+/**
+ * Bind the engine's step boundary to a DBOS checkpointed step. Never
+ * retried: a retry would re-spend.
+ *
+ * DBOS signals a cancelled workflow by throwing `DBOSWorkflowCancelledError`
+ * out of the next step boundary. Translated here into a `RunCancelledError`
+ * so executeRun's backstop records `cancelled` plus the operator's reason,
+ * rather than `failed` plus an SDK-internal message.
+ *
+ * DBOS signals that another execution of this workflow recorded the step
+ * first by throwing `DBOSWorkflowConflictError` after this attempt's step
+ * body already ran. Translated into a `RunOwnershipLostError` (carrying the
+ * discarded step's usage, if any, for the log) so executeRun's backstop stops
+ * this attempt without writing the run; runInsideWorkflow turns it back into
+ * the SDK error.
+ */
+export declare const dbosStep: StepRunner;
 export declare class DbosExecutor implements Executor {
     private readonly providers;
     private readonly config;

package/dist/providers/executor/dbos.js

@@ -11,16 +11,67 @@
  * The heartbeat is kept while the workflow runs here so the reconciler's
  * stale-heartbeat detection is unchanged; the reconciler consults
  * `recover()` (Task 6) before declaring a DBOS run lost.
+ *
+ * A stalled-but-alive owner can overlap an adopted attempt of the same run:
+ * whichever records a step second loses ownership, stops at that step
+ * without writing the run, and hands the SDK's conflict back so DBOS parks
+ * it as a duplicate execution (see dbosStep and runInsideWorkflow).
  */
 import { DBOS, Error as DbosErrors } from "@dbos-inc/dbos-sdk";
+import pg from "pg";
+import { RunOwnershipLostError } from "../engine/types.js";
 import { executeRun, RunCancelledError } from "../../core/runner.js";
 import { markRunFailedFromExecutorError } from "../../core/dispatch.js";
 import { prisma as defaultDb } from "../../core/db.js";
 import { HEARTBEAT_INTERVAL_MS } from "../../core/timing.js";
 import { logger } from "../../core/logger.js";
+import { databaseAuthFromEnv, pgConnectionConfig } from "../../core/pg-auth.js";
 import { ADOPTION_EXHAUSTED_REASON, decideRecovery, shouldGiveUpAdoption, versionMismatchReason, } from "./dbos-status.js";
 export const DBOS_BACKEND = "dbos";
 const dbosLog = logger.child({ module: "dbos-executor" });
+/** DBOS's own system pool size (DEFAULT_POOL_SIZE in the SDK's system_database.js); kept for ours. */
+const DBOS_SYSTEM_POOL_SIZE = 10;
+/** DBOS's own connect timeout when the URL sets no connect_timeout (getClientConfig in the SDK's utils.js). */
+const DBOS_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * DBOS.setConfig input. Under password auth this is exactly what launch() always passed, and DBOS
+ * opens its own pool from the URL. Under rds-iam DBOS gets a pool whose password is the IAM token;
+ * DBOS then runs its migrations, queries and LISTEN through that pool and never opens a URL
+ * connection (system_database.js: a custom pool skips database creation and is what every
+ * connection borrows from). The pool copies what DBOS would have set on its own: size, connect
+ * timeout and application_name. DBOS never ends a pool it was given — see endSystemPool().
+ */
+export function dbosLaunchConfig(config, executorId, auth, pgAuth) {
+    const url = config.systemDatabaseUrl;
+    const launch = {
+        name: "wardby",
+        systemDatabaseUrl: url,
+        systemDatabaseSchemaName: config.schemaName,
+        executorID: executorId,
+        runAdminServer: false,
+        logLevel: "warn",
+    };
+    if (auth !== "rds-iam")
+        return launch;
+    const connection = pgConnectionConfig(url, auth, pgAuth); // validates the URL first
+    const connectTimeout = Number.parseInt(new URL(url).searchParams.get("connect_timeout") ?? "", 10);
+    const pool = new pg.Pool({
+        application_name: `dbos_transact_${executorId}`,
+        ...connection,
+        max: DBOS_SYSTEM_POOL_SIZE,
+        connectionTimeoutMillis: connectTimeout ? connectTimeout * 1000 : DBOS_CONNECT_TIMEOUT_MS,
+    });
+    // DBOS attaches no listener to a caller's pool; an idle connection's error would otherwise crash the process.
+    pool.on("error", (err) => dbosLog.warn({ err }, "DBOS system database pool error"));
+    return { ...launch, systemDatabasePool: pool };
+}
+/** The pool launch() handed DBOS, if any. Module-level like DBOS itself: whoever shuts DBOS down ends it. */
+let systemPool;
+async function endSystemPool() {
+    const pool = systemPool;
+    systemPool = undefined;
+    await pool?.end().catch((err) => dbosLog.warn({ err }, "failed to close the DBOS system database pool"));
+}
 /** The executor whose deps the registered workflow uses. Set by launch(). */
 let activeExecutor;
 /** Setter (rather than `activeExecutor = this` inline) to avoid aliasing `this` to a variable. */
@@ -44,19 +95,48 @@ const cancellationReasons = new Map();
  * out of the next step boundary. Translated here into a `RunCancelledError`
  * so executeRun's backstop records `cancelled` plus the operator's reason,
  * rather than `failed` plus an SDK-internal message.
+ *
+ * DBOS signals that another execution of this workflow recorded the step
+ * first by throwing `DBOSWorkflowConflictError` after this attempt's step
+ * body already ran. Translated into a `RunOwnershipLostError` (carrying the
+ * discarded step's usage, if any, for the log) so executeRun's backstop stops
+ * this attempt without writing the run; runInsideWorkflow turns it back into
+ * the SDK error.
  */
-const dbosStep = async (name, fn) => {
+export const dbosStep = async (name, fn) => {
+    let ran;
     try {
-        return await DBOS.runStep(fn, { name, retriesAllowed: false });
+        return await DBOS.runStep(async () => {
+            const value = await fn();
+            ran = { value };
+            return value;
+        }, { name, retriesAllowed: false });
     }
     catch (err) {
         if (err instanceof DbosErrors.DBOSWorkflowCancelledError) {
             const reason = cancellationReasons.get(err.workflowID);
             throw new RunCancelledError(`Run cancelled: ${reason ?? "no reason given"}`);
         }
+        if (err instanceof DbosErrors.DBOSWorkflowConflictError) {
+            const discardedUsage = usageOf(ran?.value);
+            throw new RunOwnershipLostError(name, { cause: err, ...(discardedUsage ? { discardedUsage } : {}) });
+        }
         throw err;
     }
 };
+/**
+ * The numeric `usage` fields of a step result, if it has any (an LLM turn's
+ * token counts and cost). Tool steps return a string and yield nothing.
+ */
+function usageOf(value) {
+    if (typeof value !== "object" || value === null || !("usage" in value))
+        return undefined;
+    const usage = value.usage;
+    if (typeof usage !== "object" || usage === null)
+        return undefined;
+    const numeric = Object.entries(usage).filter((entry) => typeof entry[1] === "number");
+    return numeric.length > 0 ? Object.fromEntries(numeric) : undefined;
+}
 /**
  * Registered once at module load — DBOS requires registration before
  * launch(). The body must be deterministic between steps; everything
@@ -112,15 +192,24 @@ export class DbosExecutor {
         }
         setActiveExecutor(this);
         if (!DBOS.isInitialized()) {
-            DBOS.setConfig({
-                name: "wardby",
-                systemDatabaseUrl: this.config.systemDatabaseUrl,
-                systemDatabaseSchemaName: this.config.schemaName,
-                executorID: this.id,
-                runAdminServer: false,
-                logLevel: "warn",
-            });
-            await DBOS.launch();
+            const launchConfig = dbosLaunchConfig(this.config, this.id, databaseAuthFromEnv());
+            systemPool = launchConfig.systemDatabasePool;
+            try {
+                DBOS.setConfig(launchConfig);
+                await DBOS.launch();
+            }
+            catch (err) {
+                // DBOS.launch can throw after it initialized (registering the application version, starting
+                // event receivers). Shut that half-launched DBOS down so the next launch() starts clean, then
+                // end the pool either way: the next launch() makes a new one.
+                if (activeExecutor === this)
+                    setActiveExecutor(undefined);
+                if (DBOS.isInitialized()) {
+                    await DBOS.shutdown().catch((shutdownErr) => dbosLog.warn({ err: shutdownErr }, "failed to shut down DBOS after a failed launch"));
+                }
+                await endSystemPool();
+                throw err;
+            }
         }
         this.launched = true;
         dbosLog.info({ executorId: DBOS.executorID }, "DBOS executor launched");
@@ -131,7 +220,12 @@ export class DbosExecutor {
         this.launched = false;
         if (activeExecutor === this)
             setActiveExecutor(undefined);
-        await DBOS.shutdown({ workflowCompletionTimeoutMS: 5_000 });
+        try {
+            await DBOS.shutdown({ workflowCompletionTimeoutMS: 5_000 });
+        }
+        finally {
+            await endSystemPool();
+        }
     }
     /** Where a run this executor marks failed files its self-defect (no-op without a configured issue tracker). */
     get selfDefects() {
@@ -263,6 +357,18 @@ export class DbosExecutor {
         try {
             await executeRun(runId, this.providers, this.db, undefined, dbosStep);
         }
+        catch (err) {
+            // An ownership loss leaves the workflow body as the SDK's own conflict error, so DBOS takes
+            // its duplicate-execution path: it records nothing and parks this attempt until the winner
+            // records the outcome. Any other error escaping here would be recorded as the workflow's
+            // outcome while the winner still runs. The runner already logged the loss.
+            if (err instanceof RunOwnershipLostError) {
+                throw err.cause instanceof DbosErrors.DBOSWorkflowConflictError
+                    ? err.cause
+                    : new DbosErrors.DBOSWorkflowConflictError(runId);
+            }
+            throw err;
+        }
         finally {
             clearInterval(timer);
             cancellationReasons.delete(runId);

package/dist/providers/executor/deferred.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An Executor for a process that must never start or stop runs itself: the
+ * native sandbox gateway (docs/native-sandbox.md). Sandbox workers can reach
+ * the gateway, so it holds no Docker socket, cluster credential, or in-process
+ * engine; a child it dispatches is only recorded (Run.startDeferredAt) and a
+ * stop it needs only requested (Run.stopRequestedAt). The scheduler leader
+ * carries both out through the server's own executor (`drainDeferredRuns`).
+ *
+ * Coding dispatch still needs the worker image and the repository's service
+ * declaration and knowledge files, resolved at dispatch: those come from a
+ * resolve-only view of the configured coding executor, whose start/stop are
+ * never called here.
+ */
+import type { PrismaClient } from "#prisma";
+import type { CodingImageSelector, Executor } from "./types.js";
+import type { CodingProvider } from "../../coding/provider.js";
+export type DeferredExecutorDb = Pick<PrismaClient, "run">;
+export declare class DeferredExecutor implements Executor {
+    private readonly db;
+    /** Coding resolution only (image, service declaration, repository files); never started or stopped. */
+    private readonly resolver?;
+    constructor(db: DeferredExecutorDb, 
+    /** Coding resolution only (image, service declaration, repository files); never started or stopped. */
+    resolver?: Executor | undefined);
+    start(runId: string): Promise<void>;
+    stop(runId: string, reason?: string): Promise<void>;
+    resolveCodingWorkerImage(selector: CodingImageSelector): string;
+    resolveCodingToolImage(selector: CodingImageSelector): string | null;
+    readCodingServiceDeclaration(input: {
+        repository: string;
+        baseRef: string;
+    }): Promise<string | null>;
+    readCodingRepositoryFile(input: {
+        repository: string;
+        baseRef: string;
+        path: string;
+        maxBytes: number;
+    }): Promise<string | null>;
+    supportsCodingServices(provider: CodingProvider): boolean;
+}
+export interface DrainDeferredRunsOptions {
+    db: Pick<PrismaClient, "run">;
+    executor: Executor;
+    /** Where a start failure is recorded; defaults to marking the run failed with the error. */
+    onStartFailed?: (runId: string, err: unknown) => Promise<void>;
+    limit?: number;
+}
+/**
+ * Starts runs a deferred executor dispatched, and stops runs it asked to stop, through the
+ * server's executor. Called on the scheduler leader's tick. Each row is claimed by clearing its
+ * marker in a conditional update first, so two drains never start or stop the same run twice.
+ */
+export declare function drainDeferredRuns(options: DrainDeferredRunsOptions): Promise<{
+    started: number;
+    stopped: number;
+}>;

package/dist/providers/executor/deferred.js

@@ -0,0 +1,119 @@
+/**
+ * An Executor for a process that must never start or stop runs itself: the
+ * native sandbox gateway (docs/native-sandbox.md). Sandbox workers can reach
+ * the gateway, so it holds no Docker socket, cluster credential, or in-process
+ * engine; a child it dispatches is only recorded (Run.startDeferredAt) and a
+ * stop it needs only requested (Run.stopRequestedAt). The scheduler leader
+ * carries both out through the server's own executor (`drainDeferredRuns`).
+ *
+ * Coding dispatch still needs the worker image and the repository's service
+ * declaration and knowledge files, resolved at dispatch: those come from a
+ * resolve-only view of the configured coding executor, whose start/stop are
+ * never called here.
+ */
+import { logger } from "../../core/logger.js";
+const deferredLog = logger.child({ module: "deferred-executor" });
+export class DeferredExecutor {
+    db;
+    resolver;
+    constructor(db, 
+    /** Coding resolution only (image, service declaration, repository files); never started or stopped. */
+    resolver) {
+        this.db = db;
+        this.resolver = resolver;
+    }
+    async start(runId) {
+        await this.db.run.updateMany({ where: { id: runId, status: "pending" }, data: { startDeferredAt: new Date() } });
+    }
+    async stop(runId, reason) {
+        // Never started: nothing runs it, so it can simply end here.
+        const cancelled = await this.db.run.updateMany({
+            where: { id: runId, status: "pending", startDeferredAt: { not: null } },
+            data: {
+                status: "cancelled",
+                error: reason ?? "Cancelled before it started.",
+                finishedAt: new Date(),
+                startDeferredAt: null,
+            },
+        });
+        if (cancelled.count > 0)
+            return;
+        await this.db.run.updateMany({
+            where: { id: runId, status: { in: ["pending", "running"] } },
+            data: { stopRequestedAt: new Date(), stopRequestReason: reason ?? null },
+        });
+    }
+    resolveCodingWorkerImage(selector) {
+        if (!this.resolver?.resolveCodingWorkerImage)
+            throw new Error("coding_execution_not_configured");
+        return this.resolver.resolveCodingWorkerImage(selector);
+    }
+    resolveCodingToolImage(selector) {
+        if (!this.resolver?.resolveCodingToolImage)
+            throw new Error("coding_execution_not_configured");
+        return this.resolver.resolveCodingToolImage(selector);
+    }
+    async readCodingServiceDeclaration(input) {
+        return this.resolver?.readCodingServiceDeclaration?.(input) ?? null;
+    }
+    async readCodingRepositoryFile(input) {
+        return this.resolver?.readCodingRepositoryFile?.(input) ?? null;
+    }
+    supportsCodingServices(provider) {
+        return this.resolver?.supportsCodingServices?.(provider) === true;
+    }
+}
+/**
+ * Starts runs a deferred executor dispatched, and stops runs it asked to stop, through the
+ * server's executor. Called on the scheduler leader's tick. Each row is claimed by clearing its
+ * marker in a conditional update first, so two drains never start or stop the same run twice.
+ */
+export async function drainDeferredRuns(options) {
+    const { db, executor } = options;
+    const limit = options.limit ?? 50;
+    let started = 0;
+    let stopped = 0;
+    const toStart = await db.run.findMany({
+        where: { startDeferredAt: { not: null }, status: "pending" },
+        orderBy: { startDeferredAt: "asc" },
+        take: limit,
+        select: { id: true },
+    });
+    for (const { id } of toStart) {
+        const claimed = await db.run.updateMany({
+            where: { id, startDeferredAt: { not: null }, status: "pending" },
+            data: { startDeferredAt: null },
+        });
+        if (claimed.count === 0)
+            continue;
+        started += 1;
+        // Not awaited: an in-process executor's start runs the whole run.
+        void executor.start(id).catch(async (err) => {
+            deferredLog.error({ err, runId: id }, "deferred run failed to start");
+            await (options.onStartFailed?.(id, err) ??
+                db.run.updateMany({
+                    where: { id, status: { in: ["pending", "running"] } },
+                    data: { status: "failed", error: err instanceof Error ? err.message : String(err), finishedAt: new Date() },
+                }));
+        });
+    }
+    const toStop = await db.run.findMany({
+        where: { stopRequestedAt: { not: null } },
+        orderBy: { stopRequestedAt: "asc" },
+        take: limit,
+        select: { id: true, stopRequestReason: true, status: true },
+    });
+    for (const row of toStop) {
+        const claimed = await db.run.updateMany({
+            where: { id: row.id, stopRequestedAt: { not: null } },
+            data: { stopRequestedAt: null, stopRequestReason: null },
+        });
+        if (claimed.count === 0 || !["pending", "running"].includes(row.status))
+            continue;
+        stopped += 1;
+        await executor.stop(row.id, row.stopRequestReason ?? undefined).catch((err) => {
+            deferredLog.warn({ err, runId: row.id }, "deferred stop request failed");
+        });
+    }
+    return { started, stopped };
+}