@wardby/cli 0.2.0 → 0.3.0

package/dist/providers/executor/container.js

@@ -1,13 +1,23 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
+import { normalizeCollectExclusions } from "../../coding/collect-exclude.js";
 import { CodingProfileSchema } from "../../coding/profile.js";
+import { parseStoredServices, storedServiceNames, workerServices } from "../../coding/services/catalog.js";
+import { MAX_SERVICE_DECLARATION_BYTES, SERVICE_DECLARATION_PATH } from "../../coding/services/declaration.js";
+import { SERVICE_UNREADY_CATEGORY, SERVICE_UNREADY_ERROR, serviceUnreadyName, serviceUnreadySentence, } from "../../coding/services/wording.js";
+import { PROTECTED_PATH_CATEGORY, protectedPathFromError, protectedPathSentence, } from "../../coding/protected-path-wording.js";
+import { budgetSentence } from "../../core/budget-wording.js";
+import { classifyProviderFailure, providerClassOfCategory, providerSentence, } from "../../core/provider-wording.js";
 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 { getModelPricing } from "../llm/pricing.js";
 import { getAnthropicPricing } from "../llm/pricing-anthropic.js";
-import { isImmutableDockerImage } from "../jobs/docker-isolation.js";
+import { CODING_PROXY_ALIAS, CODING_PROXY_PORT, isImmutableDockerImage } from "../jobs/docker-isolation.js";
+import { normalizeRegistryLockfiles } from "../../coding/registry/lockfiles.js";
 import { HEARTBEAT_TIMEOUT_MS } from "../../core/timing.js";
 const containerLog = logger.child({ module: "container-executor" });
 const TERMINAL_STATUSES = new Set(["succeeded", "failed", "refused", "lost", "budget_exhausted", "cancelled"]);
@@ -32,6 +42,19 @@ function proxyProtocol(provider) {
         return "anthropic-messages";
     throw new Error("coding_provider_unsupported");
 }
+/**
+ * Claude Code's commands run in its tool runner, which never reports back through the agent, so the
+ * host rewrites registry-proxy download URLs in collected lockfiles itself (the Codex driver does it
+ * in the worker). Best effort and symlink-safe (lockfiles.ts); a Codex workspace is left alone.
+ */
+export async function normalizeCollectedLockfiles(provider, workspacePath) {
+    if (provider !== "claude-code")
+        return [];
+    return normalizeRegistryLockfiles({
+        workspace: workspacePath,
+        proxyBaseUrl: `http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`,
+    });
+}
 export class PrismaContainerExecutionStore {
     db;
     options;
@@ -42,7 +65,10 @@ export class PrismaContainerExecutionStore {
     async load(runId) {
         const row = await this.db.run.findUnique({
             where: { id: runId },
-            include: { agent: true, codingRun: { include: { proxySession: true } } },
+            include: {
+                agent: { include: { codingProfile: true, budgetGroup: { select: { name: true } } } },
+                codingRun: { include: { proxySession: true } },
+            },
         });
         if (!row?.codingRun)
             return null;
@@ -59,10 +85,12 @@ export class PrismaContainerExecutionStore {
             provider: row.codingRun.provider,
             model: row.codingRun.model,
             timeoutSec: row.codingRun.timeoutSec,
-            allowedEgress: row.codingRun.allowedEgress,
             protectedPaths: row.codingRun.protectedPaths,
+            collectExclude: row.codingRun.collectExclude,
             rootCodingRunId: row.codingRun.rootCodingRunId,
             budgetUsd: Number(row.codingRun.budgetReservedUsd),
+            agentBudgetUsd: Number(row.agent.budgetUsd),
+            budgetGroupName: row.agent.budgetGroup?.name ?? null,
             tokensIn: row.tokensIn,
             tokensOut: row.tokensOut,
             costUsd: Number(row.costUsd),
@@ -73,7 +101,13 @@ export class PrismaContainerExecutionStore {
             proxySessionId: row.codingRun.proxySession?.id ?? null,
             result: row.codingRun.result,
             workerImage: row.codingRun.workerImage,
+            toolImage: row.codingRun.toolImage,
             workspaceDiskMb: row.codingRun.workspaceDiskMb,
+            debugTrace: row.codingRun.debugTrace,
+            services: row.codingRun.services,
+            failureCategory: row.codingRun.failureCategory,
+            profileRepository: row.agent.codingProfile?.repository ?? null,
+            repositoryAuthorizedVia: row.agent.codingProfile?.repositoryAuthorizedVia ?? null,
         };
     }
     async claimProvisioning(runId, claimId) {
@@ -246,6 +280,9 @@ export class RunCapabilityVault {
 }
 class PreflightError extends Error {
 }
+/** A refusal by repository authorization; its message is the failure category's prefix (repo_access_*). */
+class RepoAccessError extends PreflightError {
+}
 export class ContainerExecutor {
     options;
     artifactRoot;
@@ -272,6 +309,12 @@ export class ContainerExecutor {
             if (image !== undefined && !isImmutableDockerImage(image))
                 throw new Error("coding_worker_image_invalid");
         }
+        for (const versions of Object.values(options.claudeToolRunnerImages ?? {})) {
+            for (const image of Object.values(versions)) {
+                if (!isImmutableDockerImage(image))
+                    throw new Error("coding_worker_image_invalid");
+            }
+        }
         if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,199}$/.test(options.credentialRef)) {
             throw new Error("coding_credential_ref_invalid");
         }
@@ -396,6 +439,9 @@ export class ContainerExecutor {
                 if ((await this.options.store.claimProvisioning(runId, claimId)) !== "claimed")
                     return;
             }
+            // A launched run (recovered after a restart) is in flight: a transient
+            // host error is retried once before it is stopped.
+            await this.authorizeRepository(run, { inFlight: Boolean(handle) });
             try {
                 workspace = await this.options.vcs.recoverWorkspace(prepared);
                 if (!workspace && handle)
@@ -473,8 +519,13 @@ export class ContainerExecutor {
                 await this.options.sessions.cancelSession(sessionId).catch(() => undefined);
             if (handle)
                 await this.options.jobs.stop(handle, "executor_failure").catch(() => undefined);
-            const status = !spendEnabled && error instanceof PreflightError ? "refused" : "failed";
-            const failure = this.failure(error);
+            const outOfBudget = spendEnabled && (await this.outOfBudget(sessionId));
+            const status = outOfBudget
+                ? "budget_exhausted"
+                : !spendEnabled && error instanceof PreflightError
+                    ? "refused"
+                    : "failed";
+            const failure = outOfBudget ? this.budgetFailure(error) : this.failure(error);
             this.emit({
                 stage: "stopping",
                 runId,
@@ -486,9 +537,17 @@ export class ContainerExecutor {
             this.terminal(run, status, failure.audit);
             if (handle)
                 await this.options.jobs.remove(handle).catch(() => undefined);
+            // A service sidecar that never became ready (kubernetes.ts waitForKeeper) is named on the host.
+            const unreadyService = outOfBudget ? null : serviceUnreadyName(error);
+            const protectedPath = outOfBudget ? null : protectedPathFromError(error);
             if (workspace) {
                 await this.options.vcs.cleanup(workspace).catch(() => undefined);
-                await this.options.vcs.notifyContinuationFinished?.(workspace, "failed", { agentName: run.agentName });
+                await this.options.vcs.notifyContinuationFinished?.(workspace, outOfBudget ? "budget_exhausted" : "failed", {
+                    agentName: run.agentName,
+                    ...(outOfBudget ? { budgetSentence: this.budgetSentence(run) } : {}),
+                    ...(unreadyService ? { serviceSentence: serviceUnreadySentence([unreadyService]) } : {}),
+                    ...(protectedPath ? { protectedPathSentence: protectedPathSentence(protectedPath) } : {}),
+                });
             }
             this.emit({ stage: "cleanup", runId, jobId: handle?.id, cleanupSucceeded: true });
         }
@@ -530,6 +589,26 @@ export class ContainerExecutor {
             clearInterval(timer);
         }
     }
+    /**
+     * The run may use its repository only if the agent's current owner still
+     * has write on it, or the profile's approval (admin or grandfathered)
+     * covers exactly this repository. A profile changed since dispatch no
+     * longer covers the run's repository, so that falls back to the owner's
+     * access. Throws RepoAccessError (refused before anything is cloned).
+     */
+    async authorizeRepository(run, opts) {
+        const sameRepository = run.profileRepository !== null && run.profileRepository === run.repository;
+        const decision = await this.options.repoAccess.authorizeUse({
+            ownerId: run.ownerId,
+            provider: "github",
+            repository: run.repository,
+            required: requiredLevel("coding"),
+            authorizedVia: sameRepository ? run.repositoryAuthorizedVia : "host_permission",
+            retryTransient: opts.inFlight,
+        });
+        if (!decision.ok)
+            throw new RepoAccessError(`repo_access_${decision.reason}`);
+    }
     preflight(run) {
         try {
             if (run.status !== "pending" && run.status !== "running")
@@ -551,7 +630,6 @@ export class ContainerExecutor {
                 baseRef: run.baseRef,
                 defaultTask: null,
                 timeoutSec: run.timeoutSec,
-                allowedEgress: run.allowedEgress,
                 protectedPaths: run.protectedPaths,
             });
             const expectedHeadRunId = run.rootCodingRunId ?? run.runId;
@@ -576,6 +654,7 @@ export class ContainerExecutor {
                 baseRef: profile.baseRef,
                 headRef: run.headRef,
                 protectedPaths: profile.protectedPaths,
+                collectExclude: [...normalizeCollectExclusions(run.collectExclude).paths],
                 continuation: run.rootCodingRunId ? { rootRunId: run.rootCodingRunId } : undefined,
             };
         }
@@ -588,16 +667,34 @@ export class ContainerExecutor {
         if (sessionId)
             await this.options.sessions.cancelSession(sessionId).catch(() => undefined);
         // For notifyContinuationFinished in the `finally` below -- defaults to
-        // "failed" and is only flipped right before an actual success return.
+        // "failed" and is only flipped right before a success or out-of-budget return.
         let outcome = "failed";
         let finishedSummary;
+        // Set when a failed job's session relayed a model-provider failure; names it on the host.
+        // Only a failed job: a transient provider error the worker retried past did not end the run.
+        let providerClass;
+        // Set when finalizeChanges refused the collected diff for touching a protected path; names it on the host.
+        let protectedPath;
         try {
             if (jobState !== "succeeded") {
                 const collected = await this.options.jobs.collect(handle).catch(() => null);
                 const reason = collected?.diagnostic ?? collected?.reason ?? jobState;
                 this.emit({ stage: "collected", runId: run.runId, jobId: handle.id });
+                // The worker usually fails outright when the proxy refuses a model
+                // request for budget; the session records that refusal.
+                if (await this.outOfBudget(sessionId)) {
+                    const failure = this.budgetFailure(`job_${reason}`, { issues: collected?.diagnosticIssues });
+                    await this.options.store.terminate(run.runId, "budget_exhausted", failure.error, failure.audit);
+                    this.terminal(run, "budget_exhausted", failure.audit);
+                    outcome = "budget_exhausted";
+                    return;
+                }
                 const status = jobState === "lost" ? "lost" : "failed";
-                const failure = this.failure(`job_${reason}`);
+                const provider = status === "failed" ? await this.providerFailure(sessionId) : null;
+                const failure = provider
+                    ? this.providerFailureOf(run, provider, `job_${reason}`, { issues: collected?.diagnosticIssues })
+                    : this.failure(`job_${reason}`, { issues: collected?.diagnosticIssues });
+                providerClass = provider?.class;
                 await this.options.store.terminate(run.runId, status, failure.error, failure.audit);
                 this.terminal(run, status, failure.audit);
                 return;
@@ -614,6 +711,7 @@ export class ContainerExecutor {
                 this.emit({ stage: "budget_cutoff", runId: run.runId, jobId: handle.id });
                 await this.options.store.complete(run.runId, "budget_exhausted", this.resultFor(output, current, "budget_exhausted"));
                 this.terminal(current, "budget_exhausted");
+                outcome = "budget_exhausted";
                 return;
             }
             if (output.outcome === "no_changes") {
@@ -628,17 +726,24 @@ export class ContainerExecutor {
             if (!workspace)
                 throw new Error("coding_workspace_lost");
             await this.options.jobs.materializeWorkspace(handle, workspace.workspacePath);
+            await normalizeCollectedLockfiles(current.provider, workspace.workspacePath);
             current = await this.requireCurrent(run.runId);
             if (current.costUsd > current.budgetUsd) {
                 this.emit({ stage: "budget_cutoff", runId: run.runId, jobId: handle.id });
                 await this.options.store.complete(run.runId, "budget_exhausted", this.resultFor(output, current, "budget_exhausted"));
                 this.terminal(current, "budget_exhausted");
+                outcome = "budget_exhausted";
                 return;
             }
+            // One more (usually cached) check right before anything is pushed: access
+            // revoked while the run was working stops the push.
+            await this.authorizeRepository(current, { inFlight: true });
+            const report = await this.loadRegistryReport(run.runId);
             const finalized = await this.options.vcs.finalizeChanges(workspace, {
                 summary: output.summary,
                 tests: output.tests,
                 tag: output.tag,
+                ...report,
             });
             const result = this.resultFor(output, current, finalized.outcome, finalized);
             await this.options.store.complete(run.runId, "succeeded", result);
@@ -650,9 +755,18 @@ export class ContainerExecutor {
             finishedSummary = output.summary;
         }
         catch (error) {
-            const failure = this.failure(error);
-            await this.options.store.terminate(run.runId, "failed", failure.error, failure.audit);
-            this.terminal(run, "failed", failure.audit);
+            if (await this.outOfBudget(sessionId)) {
+                const failure = this.budgetFailure(error);
+                await this.options.store.terminate(run.runId, "budget_exhausted", failure.error, failure.audit);
+                this.terminal(run, "budget_exhausted", failure.audit);
+                outcome = "budget_exhausted";
+            }
+            else {
+                const failure = this.failure(error);
+                await this.options.store.terminate(run.runId, "failed", failure.error, failure.audit);
+                this.terminal(run, "failed", failure.audit);
+                protectedPath = protectedPathFromError(error) ?? undefined;
+            }
         }
         finally {
             await this.options.jobs.remove(handle).catch(() => undefined);
@@ -663,12 +777,34 @@ export class ContainerExecutor {
                 await this.options.vcs.notifyContinuationFinished?.(workspace, outcome, {
                     summary: finishedSummary,
                     agentName: run.agentName,
+                    ...(outcome === "budget_exhausted" ? { budgetSentence: this.budgetSentence(run) } : {}),
+                    ...(outcome === "failed" && providerClass ? { providerSentence: providerSentence(providerClass) } : {}),
+                    ...(outcome === "failed" && protectedPath
+                        ? { protectedPathSentence: protectedPathSentence(protectedPath) }
+                        : {}),
                 });
             }
             await rm(this.artifactPath(run.runId), { recursive: true, force: true }).catch(() => undefined);
             this.emit({ stage: "cleanup", runId: run.runId, jobId: handle.id, cleanupSucceeded: true });
         }
     }
+    /** The package report is informational: any failure loading it (a
+     *  rejection, a synchronous throw, or a malformed result) yields no
+     *  package section rather than failing finalization. */
+    async loadRegistryReport(runId) {
+        try {
+            const report = await this.options.registryReport?.(runId);
+            const packages = Array.isArray(report?.packages) ? report.packages : [];
+            const packageRefusals = Array.isArray(report?.packageRefusals) ? report.packageRefusals : [];
+            return {
+                ...(packages.length > 0 ? { packages } : {}),
+                ...(packageRefusals.length > 0 ? { packageRefusals } : {}),
+            };
+        }
+        catch {
+            return {};
+        }
+    }
     resultFor(output, run, forcedOutcome, finalized) {
         const outcome = forcedOutcome ?? (output.outcome === "budget_exhausted" ? "budget_exhausted" : "no_changes");
         return CodingRunResultSchema.parse({
@@ -693,15 +829,12 @@ export class ContainerExecutor {
     }
     resolveCodingWorkerImage(selector) {
         if (selector.provider === "claude-code") {
-            if (selector.toolchain !== "node" || selector.toolchainVersion !== null) {
-                throw new Error("coding_toolchain_unsupported:claude-code");
-            }
+            this.claudeToolImage(selector);
             const image = selector.workerImageRef ?? this.options.claudeWorkerImage;
-            if (!image || !this.options.claudeToolRunnerImage)
+            if (!image)
                 throw new Error("coding_provider_not_configured:claude-code");
-            if (!isImmutableDockerImage(image) || !isImmutableDockerImage(this.options.claudeToolRunnerImage)) {
+            if (!isImmutableDockerImage(image))
                 throw new Error("coding_worker_image_invalid");
-            }
             return image;
         }
         if (selector.provider !== "codex") {
@@ -721,6 +854,40 @@ export class ContainerExecutor {
         }
         return image;
     }
+    /** Claude's tool-runner image for the agent's toolchain, at dispatch (Executor.resolveCodingToolImage); null for Codex. */
+    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. */
+    claudeToolImage(selector) {
+        if (!this.options.claudeToolRunnerImage)
+            throw new Error("coding_provider_not_configured:claude-code");
+        const image = selector.toolchain === "node" && selector.toolchainVersion === null
+            ? this.options.claudeToolRunnerImage
+            : selector.toolchainVersion !== null
+                ? this.options.claudeToolRunnerImages?.[selector.toolchain]?.[selector.toolchainVersion]
+                : undefined;
+        if (!image)
+            throw new Error("coding_toolchain_unsupported:claude-code");
+        if (!isImmutableDockerImage(image))
+            throw new Error("coding_worker_image_invalid");
+        return image;
+    }
+    /** Coding-run services: the repository's declaration at its base ref (Executor.readCodingServiceDeclaration). */
+    async readCodingServiceDeclaration(input) {
+        if (!this.options.vcs.readRepositoryFile)
+            return null;
+        return this.options.vcs.readRepositoryFile({
+            repository: input.repository,
+            ref: input.baseRef,
+            path: SERVICE_DECLARATION_PATH,
+            maxBytes: MAX_SERVICE_DECLARATION_BYTES,
+        });
+    }
+    /** The job launcher decides (Kubernetes and Docker start services for both providers). */
+    supportsCodingServices(provider) {
+        return this.options.jobs.supportsServicesFor?.(provider) === true;
+    }
     async requireCurrent(runId) {
         const current = await this.options.store.load(runId);
         if (!current)
@@ -735,16 +902,24 @@ export class ContainerExecutor {
         if (run.workspaceDiskMb && run.workspaceDiskMb > this.options.maxDiskMb) {
             throw new Error("coding_workspace_disk_exceeds_limit");
         }
+        const services = parseStoredServices(run.services);
+        // Dispatch refuses services this deployment can't start; this is the backstop.
+        if (services.length > 0 && !this.supportsCodingServices(provider)) {
+            throw new Error("coding_services_unsupported_launcher");
+        }
         return {
             kind: "coding-agent",
             runId: run.runId,
             provider,
             image: run.workerImage ?? this.options.workerImage,
-            ...(provider === "claude-code" ? { toolImage: this.options.claudeToolRunnerImage } : {}),
+            // A run keeps the tool image it was dispatched with; rows from before CodingRun.toolImage use the default.
+            ...(provider === "claude-code" ? { toolImage: run.toolImage ?? this.options.claudeToolRunnerImage } : {}),
             inputArtifact,
             timeoutSec: run.timeoutSec,
             limits: { ...this.options.limits, ...(run.workspaceDiskMb ? { diskMb: run.workspaceDiskMb } : {}) },
             labels: {},
+            collectExclude: normalizeCollectExclusions(run.collectExclude),
+            ...(services.length > 0 ? { services } : {}),
         };
     }
     credentialRef(provider) {
@@ -755,7 +930,7 @@ export class ContainerExecutor {
         throw new Error("coding_provider_not_configured:claude-code");
     }
     async writeInput(run, deadlineAt) {
-        await mkdir(this.artifactRoot, { recursive: true, mode: 0o700 });
+        await ensurePrivateDirectory(this.artifactRoot);
         const rootReal = await realpath(this.artifactRoot);
         const directory = resolve(rootReal, run.runId);
         if (!directory.startsWith(`${rootReal}${sep}`))
@@ -765,6 +940,7 @@ export class ContainerExecutor {
             throw new Error("coding_artifact_path_invalid");
         const destination = join(directory, "input.json");
         const temporary = join(directory, `.input-${randomUUID()}.tmp`);
+        const services = parseStoredServices(run.services);
         const input = CodingTaskInputSchema.parse({
             schemaVersion: CODING_PROTOCOL_VERSION,
             runId: run.runId,
@@ -776,6 +952,10 @@ export class ContainerExecutor {
             budgetUsd: run.budgetUsd,
             deadlineAt: deadlineAt.toISOString(),
             continuationOf: run.rootCodingRunId ? { runId: run.rootCodingRunId } : undefined,
+            // Only when true: an untraced run's input stays exactly what older workers expect.
+            ...(run.debugTrace ? { debugTrace: true } : {}),
+            // Only when there are some: every other run's input stays exactly what older workers expect.
+            ...(services.length > 0 ? { services: workerServices(services) } : {}),
         });
         // The run directory is 0700; world-readable mode only crosses Docker's UID boundary.
         await writeFile(temporary, JSON.stringify(input), { flag: "wx", mode: 0o444 });
@@ -788,12 +968,20 @@ export class ContainerExecutor {
     preflightForCleanup(run) {
         if (!Array.isArray(run.protectedPaths) || !run.protectedPaths.every((path) => typeof path === "string"))
             return null;
+        let collectExclude;
+        try {
+            collectExclude = [...normalizeCollectExclusions(run.collectExclude).paths];
+        }
+        catch {
+            return null;
+        }
         return {
             runId: run.runId,
             repository: run.repository,
             baseRef: run.baseRef,
             headRef: run.headRef,
             protectedPaths: run.protectedPaths,
+            collectExclude,
             continuation: run.rootCodingRunId ? { rootRunId: run.rootCodingRunId } : undefined,
         };
     }
@@ -837,11 +1025,71 @@ export class ContainerExecutor {
             // notification actually firing) -- safe to call again because
             // notifyContinuationFinished is find-and-update-or-no-op, never
             // find-or-create.
-            await this.options.vcs.notifyContinuationFinished?.(workspace, run.status === "succeeded" ? "succeeded" : "failed", { agentName: run.agentName });
+            const outcome = run.status === "succeeded" ? "succeeded" : run.status === "budget_exhausted" ? "budget_exhausted" : "failed";
+            const providerClass = run.status === "failed" ? providerClassOfCategory(run.failureCategory) : null;
+            const unreadyServices = run.status === "failed" && run.failureCategory === SERVICE_UNREADY_CATEGORY
+                ? storedServiceNames(run.services)
+                : null;
+            // No path survives to the stored run (only the category does -- see
+            // protected-path-wording.ts), so this can only ever use the pathless sentence.
+            const protectedPathFailed = run.status === "failed" && run.failureCategory === PROTECTED_PATH_CATEGORY;
+            await this.options.vcs.notifyContinuationFinished?.(workspace, outcome, {
+                agentName: run.agentName,
+                ...(outcome === "budget_exhausted" ? { budgetSentence: this.budgetSentence(run) } : {}),
+                ...(providerClass ? { providerSentence: providerSentence(providerClass) } : {}),
+                ...(unreadyServices ? { serviceSentence: serviceUnreadySentence(unreadyServices) } : {}),
+                ...(protectedPathFailed ? { protectedPathSentence: protectedPathSentence(null) } : {}),
+            });
         }
         await rm(this.artifactPath(run.runId), { recursive: true, force: true }).catch(() => undefined);
         this.emit({ stage: "cleanup", runId: run.runId, jobId: run.jobHandle?.id, cleanupSucceeded: true });
     }
+    /** Whether the proxy refused this run's session for budget. Never throws. */
+    async outOfBudget(sessionId) {
+        if (!sessionId || !this.options.sessions.budgetExhausted)
+            return false;
+        return this.options.sessions.budgetExhausted(sessionId).catch(() => false);
+    }
+    /** The model-provider failure the proxy relayed for this run's session, classified. Never throws. */
+    async providerFailure(sessionId) {
+        if (!sessionId || !this.options.sessions.upstreamFailure)
+            return null;
+        const code = await this.options.sessions.upstreamFailure(sessionId).catch(() => null);
+        return code ? { class: classifyProviderFailure(code), code } : null;
+    }
+    /**
+     * A failure the model provider's refusal caused. The persisted error names
+     * the class only; the raw upstream code (a fixed identifier, never a message)
+     * goes to one operator line an alert can key on, and the failure itself is
+     * still logged under its diagnostic id.
+     */
+    providerFailureOf(run, provider, error, options = {}) {
+        const logged = this.failure(error, options);
+        containerLog.warn({ event: "coding.provider_failure", runId: run.runId, class: provider.class, upstreamCode: provider.code }, "the model provider refused this coding run's requests");
+        return {
+            error: `coding_provider_${provider.class}`,
+            audit: { failureCategory: `provider_${provider.class}`, diagnosticId: logged.audit.diagnosticId },
+        };
+    }
+    /** The host-safe sentence for a run that ran out of budget. */
+    budgetSentence(run) {
+        return budgetSentence({
+            runBudgetUsd: run.budgetUsd,
+            agentBudgetUsd: run.agentBudgetUsd ?? run.budgetUsd,
+            budgetGroupName: run.budgetGroupName,
+        });
+    }
+    /**
+     * A failure the proxy's budget refusal caused. The failure itself is still
+     * logged under its diagnostic id, so the operator keeps the real reason.
+     */
+    budgetFailure(error, options = {}) {
+        const logged = this.failure(error, options);
+        return {
+            error: "coding_budget_exhausted",
+            audit: { failureCategory: "budget", diagnosticId: logged.audit.diagnosticId },
+        };
+    }
     emit(event) {
         try {
             this.observer.emit(event);
@@ -881,7 +1129,13 @@ export class ContainerExecutor {
         // keyed by the same diagnostic id. Token-shaped values are redacted, and a
         // cause chain is kept because the outer message is often just a wrapper.
         // A user asking to stop is not a failure, so it gets the same id at info.
-        const line = { diagnosticId, category, reason: describeFailure(error) };
+        // `issues` names only which output-schema fields failed (see SAFE_CODING_OUTPUT_ISSUE).
+        const line = {
+            diagnosticId,
+            category,
+            reason: describeFailure(error),
+            ...(options.issues ? { issues: options.issues } : {}),
+        };
         if (options.cancelled === true)
             containerLog.info(line, "coding run cancelled; the persisted error is its id only");
         else
@@ -906,7 +1160,36 @@ function safeError(error) {
     const message = error instanceof Error ? error.message : "unknown";
     return `coding_executor:${redactAndTruncate(message, 200).replace(/[^A-Za-z0-9_.:-]/g, "_")}`;
 }
+/**
+ * Error-code prefixes that name their category outright, checked before the
+ * substring heuristics below. Those heuristics filed every `github_*` error
+ * (a failed PR lookup or create after the push, a token mint) under
+ * "workspace" because "github" contains "git".
+ */
+const CATEGORY_BY_PREFIX = [
+    // A service sidecar never became ready (src/providers/jobs/kubernetes.ts).
+    [SERVICE_UNREADY_ERROR, SERVICE_UNREADY_CATEGORY],
+    // Services on a launcher that can't start them: refused at dispatch, failed here as a backstop.
+    ["coding_services_unsupported", "preflight"],
+    // Claude Code's tool runner failed to start or never became ready: the same category on both launchers.
+    ["docker_tool_runner_", "job"],
+    ["kubernetes_tool_runner_", "job"],
+    // Checked first: the host could not be asked (after one retry), not a lost permission.
+    ["repo_access_check_unavailable", "repo_access_unavailable"],
+    ["repo_access_", "repo_access"],
+    ["github_", "github"],
+    // Checked before the generic "vcs_" fallback: the collected diff touched a
+    // path this agent may not edit, not a generic workspace/git failure.
+    ["vcs_protected_path:", PROTECTED_PATH_CATEGORY],
+    ["vcs_", "workspace"],
+    ["git_", "workspace"],
+];
 function failureCategory(error) {
+    const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    for (const [prefix, category] of CATEGORY_BY_PREFIX) {
+        if (raw.startsWith(prefix))
+            return category;
+    }
     const message = safeError(error);
     if (message.includes("preflight") || message.includes("ownership") || message.includes("image"))
         return "preflight";

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

@@ -12,13 +12,12 @@
  * stale-heartbeat detection is unchanged; the reconciler consults
  * `recover()` (Task 6) before declaring a DBOS run lost.
  */
-import type { PrismaClient } from "@prisma/client";
-import type { ProviderRegistry } from "../index.js";
+import type { PrismaClient } from "#prisma";
 import type { DbosConfig } from "../../config/providers.js";
-import { type RunnerDb } from "../../core/runner.js";
+import { type NativeRunProviders, type RunnerDb } from "../../core/runner.js";
 import type { Executor, ExecutionRecoveryResult, PersistedExecutionHandle } from "./types.js";
 export declare const DBOS_BACKEND = "dbos";
-type Providers = Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory">;
+type Providers = NativeRunProviders;
 type Db = RunnerDb & Pick<PrismaClient, "run">;
 export declare class DbosExecutor implements Executor {
     private readonly providers;

package/dist/providers/executor/in-process.d.ts

@@ -5,14 +5,13 @@
  * heartbeat and recovers the run to `lost` rather than leaving it stuck
  * `running` forever.
  */
-import type { ProviderRegistry } from "../index.js";
-import { type RunnerDb } from "../../core/runner.js";
+import { type NativeRunProviders, type RunnerDb } from "../../core/runner.js";
 import type { Executor } from "./types.js";
 export declare class InProcessExecutor implements Executor {
     private readonly providers;
     private readonly db;
     private readonly heartbeatIntervalMs;
-    constructor(providers: Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory">, db?: RunnerDb, heartbeatIntervalMs?: number);
+    constructor(providers: NativeRunProviders, db?: RunnerDb, heartbeatIntervalMs?: number);
     start(runId: string): Promise<void>;
     stop(_runId: string, _reason?: string): Promise<void>;
 }

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

@@ -1,4 +1,5 @@
 import type { CodingImageSelector, Executor, ExecutionRecoveryResult, PersistedExecutionHandle } from "./types.js";
+import type { CodingProvider } from "../../coding/provider.js";
 export interface ExecutionKindResolver {
     kindForRun(runId: string): Promise<"native" | "coding" | null>;
 }
@@ -21,6 +22,12 @@ export declare class RoutingExecutor implements Executor {
     launch(): Promise<void>;
     close(): Promise<void>;
     resolveCodingWorkerImage(selector: CodingImageSelector): string;
+    resolveCodingToolImage(selector: CodingImageSelector): string | null;
+    readCodingServiceDeclaration(input: {
+        repository: string;
+        baseRef: string;
+    }): Promise<string | null>;
+    supportsCodingServices(provider: CodingProvider): boolean;
 }
 export declare class PrismaExecutionKindResolver implements ExecutionKindResolver {
     private readonly db;

package/dist/providers/executor/routing.js

@@ -54,6 +54,19 @@ export class RoutingExecutor {
             throw new Error("coding_execution_not_configured");
         return this.coding.resolveCodingWorkerImage(selector);
     }
+    resolveCodingToolImage(selector) {
+        if (!this.coding.resolveCodingToolImage)
+            throw new Error("coding_execution_not_configured");
+        return this.coding.resolveCodingToolImage(selector);
+    }
+    async readCodingServiceDeclaration(input) {
+        if (!this.coding.readCodingServiceDeclaration)
+            return null;
+        return this.coding.readCodingServiceDeclaration(input);
+    }
+    supportsCodingServices(provider) {
+        return this.coding.supportsCodingServices?.(provider) === true;
+    }
 }
 export class PrismaExecutionKindResolver {
     db;