@wardby/cli 0.6.0 → 0.8.0

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

@@ -1,14 +1,33 @@
+import { type PackageAuditEntry, type PackageAuditMode } from "../../coding/registry/audit-mode.js";
 import type { PrismaClient } from "#prisma";
+import type { RunTranscriptRecorder } from "../../coding/transcript/recorder.js";
+import { type McpToolPin } from "../../core/mcp-tools.js";
 import { type CodingProvider } from "../../coding/provider.js";
+import { type TopUpOutcome } from "../../core/budget-topup.js";
 import type { IssueTrackerRegistry } from "../issue-tracker/types.js";
 import { type RepoAccessGate } from "../../core/repo-access.js";
 import { type CodingRunObserver } from "../../coding/observability.js";
-import { type CodingRunResult } from "../../coding/protocol.js";
+import { type CodingRunResult, type DependencyCacheReport } from "../../coding/protocol.js";
 import type { ProxyModelTerms, ProxyProtocol } from "../coding-proxy/types.js";
-import type { JobHandle, JobResourceLimits, WorkspaceJobLauncher } from "../jobs/types.js";
-import type { VcsProvider } from "../vcs/types.js";
+import { type BudgetEventView } from "../../core/budget-events.js";
+import { type JobHandle, type JobResourceLimits, type WorkspaceJobLauncher } from "../jobs/types.js";
+import type { DescriptionWriteOutcome, VcsProvider } from "../vcs/types.js";
 import type { CodingImageSelector, ExecutionRecoveryResult, Executor, PersistedExecutionHandle } from "./types.js";
-import type { RelatedPullRequestEntry } from "../vcs/github.js";
+import { type DescriptionBaseline, type RelatedPullRequestEntry } from "../vcs/github.js";
+/** The longest a no-change fix round's description refresh may hold up the run's terminal write. */
+export declare const DESCRIPTION_REFRESH_TIMEOUT_MS = 60000;
+/**
+ * After the cluster refuses a run's launch for capacity, how long this executor leaves the run
+ * waiting in the queue before trying it again (drainCodingQueue starts it every tick meanwhile).
+ */
+export declare const CAPACITY_RETRY_BACKOFF_MS = 60000;
+/**
+ * What requeueAfterCapacityRefusal did: "requeued" the run waits in the queue again; "not_owned"
+ * the attempt no longer owns the run (another took it, or it ended), and nothing changed;
+ * "spend_recorded" its proxy session has spend against it, so nothing changed and the caller
+ * fails the run instead.
+ */
+export type CapacityRequeueOutcome = "requeued" | "not_owned" | "spend_recorded";
 /**
  * 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
@@ -21,15 +40,77 @@ export interface CodingRunRecord {
     resultBranch?: string;
     /** The commit the run started from. */
     baseSha?: string;
+    /** The worker's dependency cache report (CodingWorkerOutput.dependencyCache), on a run that used it. */
+    dependencyCacheResult?: DependencyCacheReport;
+    /** This run's pull request description outcome (descriptionOutcomeLabel); absent = not attempted. */
+    prDescriptionOutcome?: string;
+    /** A fresh run that wrote its PR's description: the hash, on its own (root) row. */
+    prDescriptionSha256?: string;
+    /** With prDescriptionSha256: the run whose text the description carries (the fresh run itself). */
+    prDescriptionRunId?: string;
+}
+/** The stored form of a description outcome: written, replaced, refreshed:<reason>, unchanged, edited_by_hand, skipped:<reason>. */
+export declare function descriptionOutcomeLabel(outcome: DescriptionWriteOutcome): string;
+/**
+ * What the root run of a legacy pull request (no recorded description hash)
+ * stored, from which the description it wrote is rebuilt. Raw stored values:
+ * the executor validates them.
+ */
+export interface LegacyDescriptionSource {
+    repository: string;
+    baseRef: string;
+    headRef: string;
+    /** The root run's final message (CodingRun.result.summary); absent = nothing to rebuild. */
+    summary?: string;
+    /** CodingRun.result.tests, as stored. */
+    tests?: unknown;
+    /** CodingRun.dependencyCacheResult, as stored. */
+    dependencyCache?: unknown;
+    issueProvider?: string | null;
+    issueKey?: string | null;
 }
+/**
+ * Where a continuation's pull request came from, to find the issue it was
+ * opened for: the root run's tracker issue, and the mention status (issue or
+ * pull request number) of the nearest run above the root that has one.
+ */
+export interface LinkedIssueSource {
+    issueProvider?: string | null;
+    issueKey?: string | null;
+    /** `issueMention`: that run was started by a mention on an issue (isIssueMentionTask), not on a pull request. */
+    hostStatus?: {
+        provider: string;
+        repository: string;
+        number: number;
+        issueMention?: boolean;
+    } | null;
+}
+/** An issue to read for a continuation's task. */
+export type LinkedIssueRef = {
+    provider: "github";
+    repository: string;
+    number: number;
+} | {
+    provider: "jira";
+    key: string;
+};
+/** The longest reading the linked issue may hold up a continuation's launch. */
+export declare const LINKED_ISSUE_READ_TIMEOUT_MS = 15000;
+/** The store's description baseline; `legacySource` only on a legacy pull request. */
+export type StoredDescriptionBaseline = DescriptionBaseline & {
+    legacySource?: LegacyDescriptionSource;
+};
 export interface ContainerRunSnapshot {
     runId: string;
+    agentId: string;
     status: string;
     agentKind: string;
     /** Human-readable agent name (e.g. "knock-knock-implement") -- surfaced in continuation status notifications. */
     agentName: string;
     ownerId: string | null;
     task: string;
+    /** The run's raw request (no standing instructions); absent on older runs. */
+    request?: string;
     repository: string;
     baseRef: string;
     headRef: string;
@@ -49,6 +130,13 @@ export interface ContainerRunSnapshot {
     budgetUsd: number;
     /** The agent's own per-run budget; `budgetUsd` is less when its budget group had less left. */
     agentBudgetUsd?: number;
+    /** The run's budget before the agent's allowed overrun (CodingRun.budgetBaseUsd); absent for older runs. */
+    budgetBaseUsd?: number;
+    /**
+     * The most the run may spend through overrun top-ups (CodingRun.budgetLimitUsd); `budgetUsd` is
+     * what it has been granted so far. Absent for older runs and runs without an allowed overrun.
+     */
+    budgetLimitUsd?: number;
     budgetGroupName?: string | null;
     tokensIn: number;
     tokensOut: number;
@@ -63,12 +151,20 @@ export interface ContainerRunSnapshot {
     workspaceDiskMb: number | null;
     /** Admin-requested debug trace, fixed at dispatch (CodingRun.debugTrace). */
     debugTrace?: boolean;
+    /** The traced run's trace cap in MiB, fixed at dispatch (CodingRun.debugTraceMaxMb); null = the worker default. */
+    debugTraceMaxMb?: number | null;
     /** Claude Code turn limit, fixed at dispatch (CodingRun.maxTurns); null = the worker default. */
     maxTurns?: number | null;
+    /** Claude Code output tokens per reply, fixed at dispatch (CodingRun.maxOutputTokens); null = the worker default. */
+    maxOutputTokens?: number | null;
     /** Load the repo's agent skills, fixed at dispatch (CodingRun.repoSkills); absent on older snapshots = true. */
     repoSkills?: boolean;
     /** Claude Code loading mode, fixed at dispatch (CodingRun.claudeBareMode); absent on older snapshots = true. */
     claudeBareMode?: boolean;
+    /** Dependency cache, fixed at dispatch (CodingRun.dependencyCache); absent on older snapshots = false. */
+    dependencyCache?: boolean;
+    /** Session resume, fixed at dispatch (CodingRun.sessionResume); absent on older snapshots = false. */
+    sessionResume?: boolean;
     /** Coding-run services resolved at dispatch (CodingRun.services); parsed with parseStoredServices. */
     services?: unknown;
     /** The terminal failure category, once the run has one (CodingRun.failureCategory). */
@@ -77,6 +173,12 @@ export interface ContainerRunSnapshot {
     profileRepository: string | null;
     /** How the profile's repository was authorized (CodingAgentProfile.repositoryAuthorizedVia). */
     repositoryAuthorizedVia: string | null;
+    /** The run's repository was chosen from the agent's list (CodingRun.viaRepositoryLink). */
+    viaRepositoryLink: boolean;
+    /** How the agent's current write link for the run's repository was authorized; null when there is none. */
+    repositoryLinkAuthorizedVia: string | null;
+    /** The agent's write link for the run's repository still exists (always false for a run not made via a link). */
+    repositoryLinkExists: boolean;
     /** The run's catalog entry recorded at dispatch (Run.pricingSnapshot); null on runs from before the catalog. */
     pricingVersion: string | null;
     pricingSnapshot: unknown;
@@ -98,6 +200,18 @@ export interface ContainerExecutionStore {
      */
     markQueued?(runId: string): Promise<void>;
     persistHandle(runId: string, claimId: string, handle: JobHandle): Promise<void>;
+    /**
+     * Returns a run whose launch the backend refused for capacity (JobCapacityError) to the coding
+     * queue: pending, no job handle, no proxy session, and queuedAt the run's dispatch time, so it
+     * keeps its place and CODING_QUEUE_TIMEOUT_SEC still counts from when it first waited. Only while
+     * the caller still owns it (the provisioning claim, or the planned handle it persisted — all
+     * recovery has after a crash), and only when its session has no spend; otherwise it changes
+     * nothing and says why. Optional: without it the refused run fails.
+     */
+    requeueAfterCapacityRefusal?(runId: string, owned: {
+        claimId?: string;
+        planned?: JobHandle;
+    }): Promise<CapacityRequeueOutcome>;
     heartbeat(runId: string): Promise<void>;
     /**
      * The pull requests already opened for the same request as this run (same
@@ -105,8 +219,62 @@ export interface ContainerExecutionStore {
      * Related pull requests section. Optional: without it no section is written.
      */
     relatedPullRequests?(runId: string): Promise<RelatedPullRequestEntry[]>;
+    /**
+     * The root run's record of the PR description wardby last wrote, for a fix
+     * round's description update. Optional: without it fix rounds leave the
+     * description alone.
+     */
+    pullRequestDescriptionBaseline?(rootRunId: string): Promise<StoredDescriptionBaseline>;
+    /**
+     * The runs that pushed to the root run's pull request (the root, then its
+     * continuations whose result pushed, oldest first), for the cumulative
+     * Packages section. Optional: without it the section lists this run's only.
+     */
+    pullRequestRunIds?(rootRunId: string): Promise<string[]>;
+    /**
+     * Whether wardby marked the root run's pull request ready for review
+     * (CodingRun.markedReadyAt). Optional: the fallback when the host's draft
+     * state is unknown; without it the pull request counts as a draft.
+     */
+    pullRequestMarkedReady?(rootRunId: string): Promise<boolean>;
+    /**
+     * Where the root run's pull request came from (see LinkedIssueSource).
+     * Optional: without it continuations get no issue text.
+     */
+    linkedIssueSource?(rootRunId: string): Promise<LinkedIssueSource>;
+    /**
+     * Compare-and-set of the root run's description hash and author run: writes
+     * only while the root still records `expectedSha256` (null = none). False
+     * when another write got there first.
+     */
+    recordPullRequestDescription?(input: {
+        rootRunId: string;
+        expectedSha256: string | null;
+        sha256: string;
+        agentTextRunId: string;
+    }): Promise<boolean>;
     complete(runId: string, status: "succeeded" | "budget_exhausted", result: CodingRunResult, record?: CodingRunRecord): Promise<void>;
-    terminate(runId: string, status: "failed" | "refused" | "lost" | "budget_exhausted" | "cancelled", error: string, audit?: CodingFailureAudit): Promise<void>;
+    terminate(runId: string, status: "failed" | "refused" | "lost" | "budget_exhausted" | "cancelled", error: string, audit?: CodingFailureAudit): Promise<boolean>;
+    /**
+     * Copies the proxy session's first budget refusal (CodingProxySession.budgetRefusal, written by the
+     * proxy, which has no access to RunBudgetEvent) into the run's budget events, once per run, whatever
+     * status the run ends with. A session that never recorded one adds nothing. Optional: without it no
+     * event is written.
+     */
+    recordBudgetRefusal?(runId: string, sessionId: string): Promise<void>;
+    /** The run's recorded budget refusal with names filled in, or null. Optional: without it no event is shown. */
+    budgetEvent?(runId: string): Promise<{
+        event: BudgetEventView;
+        agentName: string;
+    } | null>;
+    /**
+     * Grants a run with an overrun limit one top-up when it is close to its grant and its budget group
+     * and run tree have room (budget-topup.ts). Optional: without it a run stops at its base.
+     */
+    topUpBudget?(runId: string): Promise<{
+        outcome: TopUpOutcome;
+        near?: boolean;
+    }>;
 }
 export interface CodingFailureAudit {
     failureCategory: string;
@@ -126,12 +294,35 @@ export declare class PrismaContainerExecutionStore implements ContainerExecution
     private get hasTrackers();
     load(runId: string): Promise<ContainerRunSnapshot | null>;
     relatedPullRequests(runId: string): Promise<RelatedPullRequestEntry[]>;
+    pullRequestMarkedReady(rootRunId: string): Promise<boolean>;
+    pullRequestDescriptionBaseline(rootRunId: string): Promise<StoredDescriptionBaseline>;
+    linkedIssueSource(rootRunId: string): Promise<LinkedIssueSource>;
+    pullRequestRunIds(rootRunId: string): Promise<string[]>;
+    recordPullRequestDescription(input: {
+        rootRunId: string;
+        expectedSha256: string | null;
+        sha256: string;
+        agentTextRunId: string;
+    }): Promise<boolean>;
     claimProvisioning(runId: string, claimId: string): Promise<ProvisioningClaim>;
     markQueued(runId: string): Promise<void>;
+    requeueAfterCapacityRefusal(runId: string, owned: {
+        claimId?: string;
+        planned?: JobHandle;
+    }): Promise<CapacityRequeueOutcome>;
     persistHandle(runId: string, claimId: string, handle: JobHandle): Promise<void>;
     heartbeat(runId: string): Promise<void>;
     complete(runId: string, status: "succeeded" | "budget_exhausted", result: CodingRunResult, record?: CodingRunRecord): Promise<void>;
-    terminate(runId: string, status: "failed" | "refused" | "lost" | "budget_exhausted" | "cancelled", error: string, audit?: CodingFailureAudit): Promise<void>;
+    recordBudgetRefusal(runId: string, sessionId: string): Promise<void>;
+    budgetEvent(runId: string): Promise<{
+        event: BudgetEventView;
+        agentName: string;
+    } | null>;
+    topUpBudget(runId: string): Promise<{
+        outcome: TopUpOutcome;
+        near?: boolean;
+    }>;
+    terminate(runId: string, status: "failed" | "refused" | "lost" | "budget_exhausted" | "cancelled", error: string, audit?: CodingFailureAudit): Promise<boolean>;
 }
 export interface CodingSessionController {
     createSession(input: {
@@ -143,6 +334,10 @@ export interface CodingSessionController {
         budgetUsd: number;
         /** The run's catalog entry; the proxy prices and shapes the run's requests from it. */
         terms?: ProxyModelTerms;
+        /** The run's pinned MCP tools; set with mcpTokenHash, only when the agent has at least one. */
+        mcpTools?: McpToolPin[];
+        /** The hash of the run's MCP token (src/coding/mcp-token.ts); the token itself stays in the vault. */
+        mcpTokenHash?: string;
     }): Promise<{
         id: string;
         capability: string;
@@ -153,19 +348,38 @@ export interface CodingSessionController {
     /** The code of the first model-provider failure the proxy relayed for this session, if any. */
     upstreamFailure?(sessionId: string): Promise<string | null>;
 }
-/** Plain capabilities live only for the short provisioning window. */
+/**
+ * Plain capabilities live only for the short provisioning window. A run with MCP tools keeps its
+ * MCP token here too, next to the capability, so the launcher delivers it the same way; both are
+ * deleted together.
+ */
 export declare class RunCapabilityVault {
     private readonly values;
+    private readonly mcpTokens;
     set(runId: string, capability: string): void;
     get(runId: string): Promise<string>;
+    setMcpToken(runId: string, token: string): void;
+    /** The run's MCP token; undefined for a run without MCP tools (and once the launch is over). */
+    mcpToken(runId: string): Promise<string | undefined>;
     delete(runId: string): void;
 }
 export interface ContainerExecutorOptions {
+    /** Session resume: stores a run's transcript before its job is removed. Absent = never captured. */
+    transcripts?: Pick<RunTranscriptRecorder, "record">;
     store: ContainerExecutionStore;
     jobs: WorkspaceJobLauncher;
     vcs: VcsProvider;
     sessions: CodingSessionController;
     capabilities: RunCapabilityVault;
+    /**
+     * The agent's MCP tool pins (composition wires loadMcpToolPins; [] when WARDBY_MCP_SERVERS=off).
+     * Absent = no coding run gets MCP tools. A run with pins gets an MCP token, delivered as
+     * WARDBY_MCP_TOKEN; one without gets neither. `readOnlyOnly` comes from the run's dispatched
+     * provider (isCodexCoding(run.provider)), never the agent's current profile.
+     */
+    mcpToolPins?: (agentId: string, options: {
+        readOnlyOnly: boolean;
+    }) => Promise<McpToolPin[]>;
     artifactRoot: string;
     /**
      * The Codex worker for the "node" toolchain (CODING_WORKER_IMAGE). Optional on a Claude-only
@@ -218,6 +432,16 @@ export interface ContainerExecutorOptions {
      * reporting failure must never fail the run itself.
      */
     registryReport?: (runId: string) => Promise<RegistryReport>;
+    /**
+     * Reads an issue's title and body for a continuation's task (composition
+     * wires the review host's issue read and the issue tracker). Null when it
+     * isn't an issue (a pull request number) or can't be found. Optional:
+     * without it continuations get no issue text.
+     */
+    readLinkedIssue?: (ref: LinkedIssueRef) => Promise<{
+        title: string;
+        body: string;
+    } | null>;
     /** Browse URL for an issue of a tracker provider (composition wires the issue-tracker registry); undefined when unconfigured. */
     issueUrl?: (provider: string, key: string) => string | undefined;
     /**
@@ -227,18 +451,26 @@ export interface ContainerExecutorOptions {
      */
     repoAccess: RepoAccessGate;
 }
-/** A run's deduplicated served packages and refusals (see summarizeRegistryFetches). */
+/** A run's deduplicated served packages and refusals (see summarizeRegistryFetches), and its package audit. */
+/** The poll interval, at most, while a run with an overrun limit is near its grant. */
+export declare const TOP_UP_NEAR_POLL_MS = 1000;
 export interface RegistryReport {
     packages: Array<{
         ecosystem: string;
         name: string;
         version: string;
+        acceptedAdvisories?: string[];
     }>;
     packageRefusals: Array<{
         ecosystem: string;
         name: string;
         reason: string;
+        listingOnly?: boolean;
     }>;
+    /** The run's package audit mode (CodingRun.packageAuditMode); absent when it was off. */
+    packageAuditMode?: PackageAuditMode;
+    /** What the registry served only because of it (summarizePackageAudit entries). */
+    packageAudit?: PackageAuditEntry[];
 }
 export declare class ContainerExecutor implements Executor {
     private readonly options;
@@ -248,6 +480,11 @@ export declare class ContainerExecutor implements Executor {
     private readonly now;
     private readonly observer;
     private readonly startedAt;
+    /**
+     * When the cluster last refused each queued run's launch for capacity (this.now() ms). Per
+     * process: another replica's drain may start the run again inside the backoff.
+     */
+    private readonly capacityRefusedAt;
     constructor(options: ContainerExecutorOptions);
     start(runId: string): Promise<void>;
     stop(runId: string, reason?: string): Promise<void>;
@@ -285,14 +522,118 @@ export declare class ContainerExecutor implements Executor {
      * access. Throws RepoAccessError (refused before anything is cloned).
      */
     private authorizeRepository;
-    /** The originating issue for the PR title/body: control-plane data from the CodingRun row, key re-validated. */
+    /**
+     * The CodingRun's recorded issue as the Related section shows it (a Jira or
+     * GitHub issue): control-plane data from the CodingRun row, key re-validated.
+     */
+    private recordedIssue;
+    /**
+     * The originating tracker issue for the PR title/body. A GitHub issue is not
+     * one: its line comes from issueSourceFor (`From issue #N`).
+     */
     private issueFor;
+    /**
+     * The PR title/body's originating issue, whichever system it is in: the
+     * CodingRun's tracker issue (issueFor), else the GitHub issue in the same
+     * repository whose mention started the run tree (`From issue #N`). Read from
+     * the root run, so a continuation's rebuilt body keeps the root's line.
+     * Never throws: a failed lookup gives no issue line.
+     */
+    private issueSourceFor;
     /** The new PR's Related pull requests input: earlier PRs of the same request, then this one. Never throws. */
     private relatedFor;
     /** The run's stored model terms; a run from before the catalog resolves them from the current catalog. */
     private modelTerms;
+    /**
+     * `launched`: the run's job was already launched (it is running, or done and
+     * only its push is left). The cost check applies only before launch: one
+     * reply can cost more than its hold, so a launched run may already be past
+     * its limit, and its finished work is still delivered.
+     */
     private preflight;
     private finishTerminal;
+    /** Whether the run's workspace merged its pull request's target branch (PreparedWorkspace.targetMerge). */
+    private mergedTargetBranch;
+    /**
+     * Pushes a finished job's changes: copies the job's workspace into the run's,
+     * then, right before finalizeChanges pushes, checks again that the owner still
+     * has access and that the run was not stopped meanwhile. Shared by a finished
+     * run and one stopped at its budget; throws whatever stops the push.
+     */
+    private pushChanges;
+    /**
+     * A run stopped at its budget whose worker exited cleanly keeps its changes so
+     * far: they are pushed as the usual draft (or branch), with a summary that says
+     * the work is unfinished. A fresh pull request's description starts with that
+     * summary; a continuation leaves its pull request's description alone (the
+     * status comment says the run stopped), and pushes nothing onto a pull request
+     * that is no longer a draft. Null when there was nothing to push or the push
+     * failed or was skipped for any reason: the run then ends out of budget without
+     * them. Once pushed, the pushed outcome is always returned. Throws only when the
+     * run was stopped meanwhile (the stop wrote its terminal row).
+     */
+    private keepStoppedChanges;
+    /**
+     * The pull request description a continuation run is about to replace, for
+     * its task. Undefined for a fresh run or when it cannot be loaded: the run
+     * goes ahead without the note.
+     */
+    private currentDescriptionText;
+    /**
+     * The issue a continuation's pull request was opened for, read for its task
+     * the way the first run had it: the root run's Jira issue, else the GitHub
+     * issue whose mention started the work (same repository), else the issue the
+     * description wardby last wrote closes (same repository). Each candidate is
+     * read in turn until one is an issue. Undefined for a fresh or local run, or
+     * on any failure: the run goes ahead without it.
+     */
+    private linkedIssueFor;
+    private readLinkedIssue;
+    /**
+     * A fix round's description baseline (null: no description flow -- a fresh
+     * run, or a store without it). Never throws: a load failure is recorded as
+     * skipped:error and the push goes ahead without a description update.
+     */
+    /**
+     * Whether a continuation's pull request is still a draft: the host's answer
+     * when it has one, else the root run's record of wardby marking it ready.
+     * A failed record lookup counts as not a draft (nothing unfinished is pushed).
+     */
+    private continuationStillDraft;
+    private descriptionStateFor;
+    /**
+     * A legacy pull request's description as its root run wrote it, rebuilt from
+     * stored records (the final message, tests, packages, dependency cache line
+     * and issue line; the Related section is not hashed), and hashed. Undefined
+     * when the root stored no final message, or on any failure: the description
+     * then counts as edited, the safe direction. A lock file line the root's
+     * refusal warning may have carried is not stored, so such a description
+     * never matches.
+     */
+    private legacyDescriptionSha256;
+    /**
+     * The Packages section's input: on a continuation, every package installed
+     * by the runs that pushed to the pull request plus this run (merged in run
+     * order); refusals are this run's only, since they describe the current
+     * state. A fresh run, or a failed listing, reports this run's alone.
+     */
+    private pullRequestRegistryReport;
+    /**
+     * The run's description columns for store.complete. A fresh run that wrote
+     * its PR records the hash on its own (root) row; a fix round that wrote or
+     * kept wardby's text compare-and-sets the root's hash. Never throws.
+     */
+    private recordDescription;
+    /**
+     * refreshDescriptionWithoutPush, capped at DESCRIPTION_REFRESH_TIMEOUT_MS so a
+     * slow host cannot hold up store.complete; a timeout is skipped:error.
+     */
+    private refreshDescriptionInTime;
+    /**
+     * A fix round that changed nothing still re-derives its PR description (no
+     * push). Never throws: any failure is recorded as skipped:error.
+     */
+    private refreshDescriptionWithoutPush;
     /** Runs the onCodingRunTerminal hook; nothing it does, throws, or rejects reaches the caller. */
     private notifyTerminal;
     /** The package report is informational: any failure loading it (a
@@ -325,7 +666,27 @@ export declare class ContainerExecutor implements Executor {
     supportsCodingServices(provider: CodingProvider): boolean;
     /** Delegates to the job launcher's own warm-up (Executor.warmUp); a no-op for a launcher without one. */
     warmUp(): Promise<void>;
+    /**
+     * Throws coding_run_no_longer_active once something else made the run terminal (a stop's
+     * cancellation fence): nothing may then be pushed, opened, or rewritten on the host for it.
+     */
+    private requireActive;
     private requireCurrent;
+    /**
+     * Recovery's half of a capacity refusal: the launcher recorded it, but the process died before the
+     * store put the run back in the queue. The planned handle the attempt persisted is the ownership
+     * proof; the run waits in the queue again, never reported ended.
+     */
+    private finishCapacityRequeue;
+    /**
+     * After drainCodingQueue failed a queued run (coding_queue_timeout): releases what an earlier
+     * attempt the cluster refused left behind, as stop() does for a queued run. A refused
+     * continuation already marked its pull request as being worked on; that check is finished
+     * here. Best effort; the artifact is removed only where this process wrote it.
+     */
+    cleanupQueueTimeout(runId: string): Promise<void>;
+    private recordCapacityRefusal;
+    private inCapacityBackoff;
     /**
      * False when the launcher reports this run's job would not fit the cluster right now; the run
      * is then queued and drainCodingQueue retries it. Launchers and stores without the hooks, and
@@ -336,9 +697,27 @@ export declare class ContainerExecutor implements Executor {
     private credentialRef;
     private writeInput;
     private artifactPath;
+    /**
+     * A continuation's pull request from the run record alone, for the host-side
+     * finish signals when the workspace is gone (another control-plane process
+     * launched the run). Null for a fresh run: it has no pull request yet.
+     */
+    private continuationTargetOf;
+    /**
+     * Session resume: never throws, never changes the run's outcome. The recorder redacts; only a status
+     * code is logged. The run capability is already gone from the vault, so it is not passed (the recorder
+     * removes its fixed token shape).
+     */
+    private recordTranscript;
     private preflightForCleanup;
     private abandon;
     private cleanupTerminal;
+    /**
+     * Records the session's budget refusal on the run, at every ending: a run the proxy refused once may
+     * still finish, fail for another reason, or be stopped. A session with no refusal adds nothing.
+     * Best effort; never throws.
+     */
+    private recordRefusal;
     /** Whether the proxy refused this run's session for budget. Never throws. */
     private outOfBudget;
     /** The model-provider failure the proxy relayed for this run's session, classified. Never throws. */
@@ -350,6 +729,8 @@ export declare class ContainerExecutor implements Executor {
      * still logged under its diagnostic id.
      */
     private providerFailureOf;
+    /** The overrun sentence for a finished run that spent past its base budget, as status details. */
+    private overrunDetails;
     /** The host-safe sentence for a run that ran out of budget. */
     private budgetSentence;
     /**
@@ -372,3 +753,7 @@ export declare class ContainerExecutor implements Executor {
 }
 /** Operator-facing failure text: the message plus its cause chain, redacted. */
 export declare function describeFailure(error: unknown, depth?: number): string;
+/** The agent's MCP tool pins could not be read at launch (a database error): the run fails, nothing launched. */
+export declare const MCP_PINS_UNAVAILABLE_ERROR = "coding_mcp_pins_unavailable";
+/** Its category: the run's error is coding_failure_mcp_pins_unavailable:<diagnostic id>. */
+export declare const MCP_PINS_UNAVAILABLE_CATEGORY = "mcp_pins_unavailable";