@wardby/cli 0.2.1 → 0.4.0

package/dist/providers/executor/container.js

@@ -1,14 +1,27 @@
 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 { normalizeCollectExclusions } from "../../coding/collect-exclude.js";
+import { codingProviderForModelProvider } from "../../coding/provider.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 { fileSelfDefect } from "../../core/self-defects.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 { 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";
+import { normalizeRegistryLockfiles } from "../../coding/registry/lockfiles.js";
+import { ISSUE_KEY, ISSUE_TRACKER_NAMES } from "../issue-tracker/types.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"]);
@@ -33,6 +46,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;
@@ -40,10 +66,22 @@ export class PrismaContainerExecutionStore {
         this.db = db;
         this.options = options;
     }
+    /** Best effort (bounded, never throws): only called by the write that made the row terminal, so it files once. */
+    async selfDefect(run) {
+        if (this.hasTrackers)
+            await fileSelfDefect(this.db, this.options.issueTrackers, run);
+    }
+    /** An empty registry (no Jira site configured) means no self-defect queries at all. */
+    get hasTrackers() {
+        return Object.values(this.options.issueTrackers ?? {}).some(Boolean);
+    }
     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;
@@ -60,10 +98,14 @@ 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,
+            issueProvider: row.codingRun.issueProvider,
+            issueKey: row.codingRun.issueKey,
             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),
@@ -74,7 +116,15 @@ 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,
+            pricingVersion: row.pricingVersion,
+            pricingSnapshot: row.pricingSnapshot,
         };
     }
     async claimProvisioning(runId, claimId) {
@@ -187,13 +237,14 @@ export class PrismaContainerExecutionStore {
         });
     }
     async complete(runId, status, result) {
-        await this.db.$transaction(async (tx) => {
+        const finishedAt = new Date();
+        const finished = await this.db.$transaction(async (tx) => {
             const run = await tx.run.findUnique({ where: { id: runId }, include: { codingRun: true } });
             if (!run?.codingRun)
                 throw new Error("coding_run_not_found");
             if (TERMINAL_STATUSES.has(run.status)) {
                 if (run.codingRun.result && stableJson(run.codingRun.result) === stableJson(result))
-                    return;
+                    return null;
                 throw new Error("coding_run_terminal_conflict");
             }
             await tx.codingRun.update({
@@ -205,26 +256,40 @@ export class PrismaContainerExecutionStore {
                 data: {
                     status,
                     finalText: result.summary,
-                    finishedAt: new Date(),
+                    finishedAt,
                     heartbeatAt: new Date(),
                     error: null,
                 },
             });
+            return { id: runId, agentId: run.agentId };
         });
+        if (finished && status === "budget_exhausted") {
+            await this.selfDefect({ ...finished, status, error: null, finishedAt });
+        }
     }
     async terminate(runId, status, error, audit) {
-        await this.db.$transaction(async (tx) => {
+        const finishedAt = new Date();
+        const agentId = await this.db.$transaction(async (tx) => {
             const updated = await tx.run.updateMany({
                 where: { id: runId, status: { in: ["pending", "running"] } },
-                data: { status, error, finishedAt: new Date(), heartbeatAt: new Date() },
+                data: { status, error, finishedAt, heartbeatAt: new Date() },
             });
-            if (updated.count && audit) {
+            if (!updated.count)
+                return null;
+            if (audit) {
                 await tx.codingRun.update({
                     where: { runId },
                     data: { failureCategory: audit.failureCategory, diagnosticId: audit.diagnosticId },
                 });
             }
+            if (!this.hasTrackers)
+                return null;
+            const row = await tx.run.findUnique({ where: { id: runId }, select: { agentId: true } });
+            return row?.agentId ?? null;
         });
+        // After commit, so the failure category is readable; cancelled/refused are skipped inside fileSelfDefect.
+        if (agentId)
+            await this.selfDefect({ id: runId, agentId, status, error, finishedAt });
     }
 }
 /** Plain capabilities live only for the short provisioning window. */
@@ -247,6 +312,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;
@@ -273,6 +341,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");
         }
@@ -397,6 +471,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)
@@ -425,11 +502,12 @@ export class ContainerExecutor {
                     allowedModels: [run.model],
                     deadlineAt,
                     budgetUsd: run.budgetUsd,
+                    terms: this.modelTerms(run),
                 });
                 spendEnabled = true;
                 sessionId = session.id;
                 this.options.capabilities.set(runId, session.capability);
-                const inputArtifact = await this.writeInput(run, deadlineAt);
+                const inputArtifact = await this.writeInput(run, deadlineAt, workspace.baseCommit);
                 const beforeLaunch = await this.requireCurrent(runId);
                 if (TERMINAL_STATUSES.has(beforeLaunch.status))
                     throw new Error("coding_run_no_longer_active");
@@ -474,8 +552,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,
@@ -487,9 +570,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 });
         }
@@ -531,18 +622,70 @@ 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}`);
+    }
+    /** The originating issue for the PR title/body: control-plane data from the CodingRun row, key re-validated. */
+    issueFor(run) {
+        const { issueProvider, issueKey } = run;
+        if (!issueProvider || !issueKey || !ISSUE_KEY.test(issueKey))
+            return {};
+        let url;
+        try {
+            url = this.options.issueUrl?.(issueProvider, issueKey);
+        }
+        catch {
+            url = undefined;
+        }
+        const trackerName = Object.hasOwn(ISSUE_TRACKER_NAMES, issueProvider)
+            ? ISSUE_TRACKER_NAMES[issueProvider]
+            : undefined;
+        return {
+            issue: {
+                key: issueKey,
+                ...(url?.startsWith("https://") ? { url } : {}),
+                ...(trackerName ? { trackerName } : {}),
+            },
+        };
+    }
+    /** The run's stored model terms; a run from before the catalog resolves them from the current catalog. */
+    modelTerms(run) {
+        if (run.provider !== "codex" && run.provider !== "claude-code")
+            throw new Error("coding_provider_unsupported");
+        const stored = parseStoredEntry(run.pricingSnapshot);
+        if (stored && run.pricingVersion) {
+            if (stored.modelId !== run.model || codingProviderForModelProvider(stored.provider) !== run.provider) {
+                throw new Error("coding_run_pricing_mismatch");
+            }
+            return { version: run.pricingVersion, entry: stored };
+        }
+        const entry = resolveCodingEntry(run.provider, run.model);
+        return { version: entry.priceVersion, entry: parseStoredEntry(entry) };
+    }
     preflight(run) {
         try {
             if (run.status !== "pending" && run.status !== "running")
                 throw new Error("coding_run_status_invalid");
             if (run.agentKind !== "coding" || !run.ownerId)
                 throw new Error("coding_run_ownership_invalid");
-            if (run.provider === "codex")
-                getModelPricing(run.model);
-            else if (run.provider === "claude-code")
-                getAnthropicPricing(run.model);
-            else
-                throw new Error("coding_provider_unsupported");
+            this.modelTerms(run);
             if (!Number.isFinite(run.budgetUsd) || run.budgetUsd <= 0 || run.costUsd > run.budgetUsd) {
                 throw new Error("coding_run_budget_invalid");
             }
@@ -552,7 +695,6 @@ export class ContainerExecutor {
                 baseRef: run.baseRef,
                 defaultTask: null,
                 timeoutSec: run.timeoutSec,
-                allowedEgress: run.allowedEgress,
                 protectedPaths: run.protectedPaths,
             });
             const expectedHeadRunId = run.rootCodingRunId ?? run.runId;
@@ -577,6 +719,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,
             };
         }
@@ -589,16 +732,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}`, { issues: collected?.diagnosticIssues });
+                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;
@@ -615,6 +776,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") {
@@ -629,17 +791,25 @@ 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,
+                ...this.issueFor(current),
             });
             const result = this.resultFor(output, current, finalized.outcome, finalized);
             await this.options.store.complete(run.runId, "succeeded", result);
@@ -651,9 +821,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);
@@ -664,12 +843,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({
@@ -694,15 +895,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") {
@@ -722,6 +920,51 @@ 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,
+        });
+    }
+    /** One repository file at the run's base ref (Executor.readCodingRepositoryFile). */
+    async readCodingRepositoryFile(input) {
+        if (!this.options.vcs.readRepositoryFile)
+            return null;
+        return this.options.vcs.readRepositoryFile({
+            repository: input.repository,
+            ref: input.baseRef,
+            path: input.path,
+            maxBytes: input.maxBytes,
+        });
+    }
+    /** 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)
@@ -736,16 +979,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 +1006,7 @@ export class ContainerExecutor {
             return this.options.anthropicCredentialRef;
         throw new Error("coding_provider_not_configured:claude-code");
     }
-    async writeInput(run, deadlineAt) {
+    async writeInput(run, deadlineAt, baseCommit) {
         await ensurePrivateDirectory(this.artifactRoot);
         const rootReal = await realpath(this.artifactRoot);
         const directory = resolve(rootReal, run.runId);
@@ -766,17 +1017,26 @@ 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 task = withBaseCommit(run.task, baseCommit);
+        if (task === run.task && /^[0-9a-f]{40}$/.test(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({
             schemaVersion: CODING_PROTOCOL_VERSION,
             runId: run.runId,
             repository: run.repository,
             baseRef: run.baseRef,
             headRef: run.headRef,
-            task: run.task,
+            task,
             model: run.model,
             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 });
@@ -789,12 +1049,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,
         };
     }
@@ -838,11 +1106,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);
@@ -913,7 +1241,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";