@wardby/cli 0.5.2 → 0.6.0

package/dist/providers/jobs/kubernetes.d.ts

@@ -1,5 +1,6 @@
 import { type Readable } from "node:stream";
 import type { KubernetesJobConfig } from "../../config/providers.js";
+import { type Power } from "../../core/power.js";
 import { type KubernetesApi } from "./kubernetes-api.js";
 import { type ServiceStateReporter } from "./service-state.js";
 import type { CodingProvider } from "../../coding/provider.js";
@@ -19,20 +20,29 @@ export interface KubernetesJobLauncherOptions {
      * the gate probes the address `provision` re-reads for that launch, not this memoized one.
      */
     preflight?: () => Promise<KubernetesClusterInfo | void>;
+    /**
+     * Low-power mode: `launch()` wakes the (possibly scaled-to-zero) coding proxy before its preflight,
+     * and `warmUp()` defers the preflight while the proxy is asleep. Default `DISABLED_POWER` (no-op).
+     */
+    power?: Power;
     now?: () => number;
     sleep?: (milliseconds: number) => Promise<void>;
     readyTimeoutMs?: number;
     /**
      * How long to wait for the run's NetworkPolicy to be enforced before seeding. Default 30_000,
-     * but never *less* than `enforcementExecTimeoutMs * ENFORCEMENT_BLOCKED_STREAK`: see the
-     * constructor. An explicit override here is a floor raise, not an escape hatch — the gate still
-     * needs room for a full streak of probes at whatever the effective exec timeout is.
+     * but never *less* than one full streak exec's timeout
+     * (`enforcementExecTimeoutMs * ENFORCEMENT_BLOCKED_STREAK + ENFORCEMENT_POLL_MS * (ENFORCEMENT_BLOCKED_STREAK - 1)`,
+     * 31_000 at the default exec timeout): see the constructor. An explicit override here is a floor
+     * raise, not an escape hatch — the gate still needs room for a full streak of probes at whatever
+     * the effective per-probe budget is.
      */
     enforcementTimeoutMs?: number;
     /**
-     * Bound for a single enforcement probe exec. Default 10_000 (DEFAULT_ENFORCEMENT_EXEC_TIMEOUT_MS).
-     * Raise this on a resource-constrained cluster (e.g. `kind` on a laptop) where a healthy probe
-     * can legitimately take longer than 10 s to run inside the keeper's CPU/memory limits.
+     * Time budget for a single enforcement probe. Default 10_000 (DEFAULT_ENFORCEMENT_EXEC_TIMEOUT_MS).
+     * A streak's probes share one exec, whose timeout is this times ENFORCEMENT_BLOCKED_STREAK plus
+     * the poll gaps between them. Raise this on a resource-constrained cluster (e.g. `kind` on a
+     * laptop) where a healthy probe can legitimately take longer than 10 s to run inside the
+     * keeper's CPU/memory limits.
      */
     enforcementExecTimeoutMs?: number;
     createArchive?: (directory: string) => {
@@ -60,7 +70,10 @@ export declare class KubernetesJobLauncher implements WorkspaceJobLauncher {
     private readonly warn;
     private readonly enforcementTimeoutMs;
     private readonly enforcementExecTimeoutMs;
+    /** Timeout of one streak exec: ENFORCEMENT_BLOCKED_STREAK probes plus the gaps between them. */
+    private readonly streakExecTimeoutMs;
     private preflightResult?;
+    private readonly power;
     constructor(options: KubernetesJobLauncherOptions);
     /**
      * Services run as native sidecars in the run pod (kubernetes-isolation.ts), for either provider:
@@ -88,7 +101,35 @@ export declare class KubernetesJobLauncher implements WorkspaceJobLauncher {
     materializeWorkspace(handle: JobHandle, destination: string): Promise<void>;
     stop(handle: JobHandle, _reason?: string): Promise<void>;
     remove(handle: JobHandle): Promise<void>;
-    /** Memoized: the preflight (or, without one, a single proxy-witness read) runs once per launcher. */
+    /**
+     * Low-power mode: whether the proxy is scaled to zero. A failed check is logged by code only (the
+     * leading reason code, else the error's class name -- never the raw message, which could carry
+     * cluster detail) and counts as awake, so warm-up runs the preflight as it would without the mode.
+     */
+    private proxyAsleep;
+    /**
+     * Starts the memoized cluster preflight (`runPreflight`) right away, instead of waiting for the
+     * first `launch()`, so a long-running server process's own start-up pays the preflight's cost (a
+     * canary pod on `kind`: ~20s) rather than that process's first coding run. Never throws: it only
+     * reports the outcome (an info line on success, a warning naming the failure code otherwise) so
+     * an operator sees a misconfigured cluster at boot. Any `launch()` already awaiting this same
+     * attempt (concurrent with this call) still fails exactly as it does today when the preflight
+     * failed — it shares the same rejected promise. But unlike a preflight `launch()` starts on its
+     * own, a start-up failure here is **not** left stuck memoized: a transient cluster problem at
+     * process start must not fail every coding run until restart, so the failed attempt is cleared
+     * (only if nothing has already started a newer one — compared by identity, never by state) and
+     * the *next* `launch()` runs the preflight fresh. A successful warm-up stays memoized as always.
+     * In low-power mode, while the proxy is asleep, warm-up is skipped (the memo stays unset) rather
+     * than waking the proxy only for the preflight; the first `launch()` wakes it and runs the preflight.
+     */
+    warmUp(): Promise<void>;
+    /**
+     * Memoized: the preflight (or, without one, a single proxy-witness read) runs once per launcher —
+     * including its failure, which stays memoized and fails every subsequent `launch()` immediately,
+     * for a preflight `launch()` itself started (there was no `warmUp()`, or `warmUp()`'s own failed
+     * attempt was already cleared). `warmUp()` is the one caller that clears a failed attempt instead
+     * of leaving it stuck; see its own doc comment.
+     */
     private runPreflight;
     /**
      * Waits until the run's NetworkPolicy is enforced on this pod: the keeper (same network namespace
@@ -96,6 +137,14 @@ export declare class KubernetesJobLauncher implements WorkspaceJobLauncher {
      * proxy on CODING_PROXY_PORT and fail to reach it on CODING_PROXY_DENY_PORT. Anything else resets
      * the streak; the wall-clock bound still applies.
      *
+     * The whole streak runs in ONE keeper exec (`enforcementStreakScript`), so exec and interpreter
+     * start-up is paid once per streak rather than once per probe. That exec exits 0 only after the
+     * full streak was proven; otherwise it stops at the first non-proven probe and exits with that
+     * probe's code. Any non-zero exit is a broken streak: if the bound has been reached it is the
+     * verdict, else the launcher waits ENFORCEMENT_POLL_MS and starts a fresh streak from zero. The
+     * exec is bounded by `streakExecTimeoutMs` (the per-probe budget times the streak, plus the gaps);
+     * an exec that times out or fails throws, failing the launch exactly as a failed probe exec did.
+     *
      * "Fail to reach" means the connect *timed out* — the packet was dropped. A refusal (RST) is not
      * a denial: it proves the SYN reached the destination host, so the deny port is merely unserved
      * and witnesses nothing. That is its own verdict, below.

package/dist/providers/jobs/kubernetes.js

@@ -29,11 +29,12 @@ import { finished } from "node:stream/promises";
 import { createHash } from "node:crypto";
 import { isIP } from "node:net";
 import { logger } from "../../core/logger.js";
-import { MAX_CODING_ARTIFACT_BYTES, MAX_DEBUG_TRACE_LINE_BYTES, parseCodingAgentOutputJson, } from "../../coding/protocol.js";
+import { DISABLED_POWER, wakeTimeoutMs } from "../../core/power.js";
+import { MAX_CODING_ARTIFACT_BYTES, MAX_CODING_INPUT_BYTES, MAX_DEBUG_TRACE_LINE_BYTES, parseCodingAgentOutputJson, } from "../../coding/protocol.js";
 import { CODING_PROXY_DENY_PORT, CODING_PROXY_PORT } from "./docker-isolation.js";
 import { parseWorkerDiagnosticLine } from "./docker.js";
 import { KubernetesAlreadyExistsError, KubernetesConflictError } from "./kubernetes-api.js";
-import { ENFORCEMENT_PROBE_DENY_REACHABLE, ENFORCEMENT_PROBE_PROVEN, ENFORCEMENT_PROBE_DENY_REFUSED, ENFORCEMENT_PROBE_PROXY_UNREACHABLE, KEEPER_CONTAINER, KEEPER_SEEDED_MARKER, KUBERNETES_ISOLATION_ERROR, STORAGE_ROOT, TOOL_RUNNER_CONTAINER, WORKER_CONTAINER, assertRunNetworkPolicyMatches, assertRunPodMatches, buildCapabilitySecret, buildRunNetworkPolicy, buildRunPod, enforcementProbeScript, kubernetesRunNames, kubernetesRunNamesForToken, runLabels, serviceContainerName, validateKubernetesSpec, } from "./kubernetes-isolation.js";
+import { ENFORCEMENT_PROBE_DENY_REACHABLE, ENFORCEMENT_PROBE_PROVEN, ENFORCEMENT_PROBE_DENY_REFUSED, ENFORCEMENT_PROBE_PROXY_UNREACHABLE, KEEPER_CONTAINER, KEEPER_SEEDED_MARKER, KUBERNETES_ISOLATION_ERROR, STORAGE_ROOT, TOOL_RUNNER_CONTAINER, WORKER_CONTAINER, assertRunNetworkPolicyMatches, assertRunPodMatches, buildCapabilitySecret, buildRunNetworkPolicy, buildRunPod, enforcementStreakScript, kubernetesRunNames, kubernetesRunNamesForToken, runLabels, serviceContainerName, validateKubernetesSpec, } from "./kubernetes-isolation.js";
 import { claudeToolSetup } from "./claude-tool-setup.js";
 import { podQuotaUsage, quotaShortfall } from "./kubernetes-quota.js";
 import { readProxyWitness } from "./kubernetes-witness.js";
@@ -60,14 +61,17 @@ const ENFORCEMENT_POLL_MS = 500;
 /** Consecutive proven probes required (8787 reachable, 8788 blocked): one dropped SYN must not open the gate. */
 const ENFORCEMENT_BLOCKED_STREAK = 3;
 /**
- * Default bound for one enforcement probe exec (the probe makes two sequential connects, so it
+ * Default time budget for ONE enforcement probe (the probe makes two sequential connects, so it
  * gives up after at most 6 s of its own connect timeouts). Overridable per KubernetesJobConfig's
  * `enforcementExecTimeoutMs` (KUBERNETES_ENFORCEMENT_EXEC_TIMEOUT_MS) — a resource-constrained
  * keeper (e.g. a laptop `kind` cluster's default 250m CPU / 128Mi limit) can take noticeably
- * longer than this to run even a healthy probe to completion. DEFAULT_ENFORCEMENT_TIMEOUT_MS
- * above is exactly this default times ENFORCEMENT_BLOCKED_STREAK, which is not a coincidence: see
- * the constructor, which derives the effective overall bound the same way from whichever exec
- * timeout is actually configured, so the two never drift apart.
+ * longer than this to run even a healthy probe to completion.
+ *
+ * The probes of one streak run inside a single exec (`enforcementStreakScript`), so the exec's own
+ * timeout is derived from this per-probe budget: ENFORCEMENT_BLOCKED_STREAK probes plus the
+ * ENFORCEMENT_POLL_MS gaps between them (`streakExecTimeoutMs`; 31_000 at this default). The
+ * constructor then floors the overall wall-clock bound at that one-streak-exec value, so a raised
+ * per-probe budget can never leave the bound shorter than a single streak.
  */
 const DEFAULT_ENFORCEMENT_EXEC_TIMEOUT_MS = 10_000;
 /**
@@ -81,12 +85,10 @@ const DEFAULT_ENFORCEMENT_EXEC_TIMEOUT_MS = 10_000;
  * and sending an operator to the CNI over a dead exec wastes the one clue they were given.
  */
 const ENFORCEMENT_VERDICTS = {
-    [ENFORCEMENT_PROBE_PROVEN]: {
-        code: "kubernetes_policy_not_enforced",
-        // Reaching the bound on a proven probe means the streak kept being broken: enforcement was
-        // observed, but never ENFORCEMENT_BLOCKED_STREAK times running, so it is not stable evidence.
-        detail: `the last probe was proven, but never ${ENFORCEMENT_BLOCKED_STREAK} consecutive times within the bound — enforcement is flapping rather than absent`,
-    },
+    // No ENFORCEMENT_PROBE_PROVEN entry, deliberately: the whole streak runs in one exec
+    // (enforcementStreakScript), which exits PROVEN only after ENFORCEMENT_BLOCKED_STREAK consecutive
+    // proven probes — and that opens the gate before the bound is ever checked. A streak broken by
+    // flapping exits with the breaking probe's own code, so the verdict is always one of these.
     [ENFORCEMENT_PROBE_DENY_REACHABLE]: {
         code: "kubernetes_policy_not_enforced",
         detail: `the deny port ${CODING_PROXY_DENY_PORT} accepted a connection, so no policy is blocking it (or the policy is not port-scoped) — look at the CNI`,
@@ -110,12 +112,8 @@ const ENFORCEMENT_PROBE_DID_NOT_RUN = {
 };
 /** Same shape as ENFORCEMENT_VERDICTS/ENFORCEMENT_PROBE_DID_NOT_RUN, but for the `pre_marker` stage. */
 const ENFORCEMENT_VERDICTS_PRE_MARKER = {
-    [ENFORCEMENT_PROBE_PROVEN]: {
-        code: "kubernetes_policy_enforcement_lost_before_marker",
-        detail: `the policy was proven enforced earlier in this launch, but the re-probe run immediately before ` +
-            `opening the gate never reached ${ENFORCEMENT_BLOCKED_STREAK} consecutive proven probes within the ` +
-            "bound — enforcement held at the initial proof but is flapping now, immediately before release",
-    },
+    // No ENFORCEMENT_PROBE_PROVEN entry, for the same reason as ENFORCEMENT_VERDICTS: a proven streak
+    // exec opens the gate, so it never reaches enforcementVerdict.
     [ENFORCEMENT_PROBE_DENY_REACHABLE]: {
         code: "kubernetes_policy_enforcement_lost_before_marker",
         detail: `the deny port ${CODING_PROXY_DENY_PORT} was proven blocked earlier in this launch, but the re-probe ` +
@@ -386,10 +384,14 @@ export class KubernetesJobLauncher {
     warn;
     enforcementTimeoutMs;
     enforcementExecTimeoutMs;
+    /** Timeout of one streak exec: ENFORCEMENT_BLOCKED_STREAK probes plus the gaps between them. */
+    streakExecTimeoutMs;
     preflightResult;
+    power;
     constructor(options) {
         this.options = options;
         this.api = options.api;
+        this.power = options.power ?? DISABLED_POWER;
         this.namespace = options.config.namespace;
         this.workspaceRoot = resolve(options.workspaceRoot);
         if (this.workspaceRoot === resolve("/"))
@@ -398,13 +400,18 @@ export class KubernetesJobLauncher {
         this.sleep = options.sleep ?? ((ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)));
         this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
         this.enforcementExecTimeoutMs = options.enforcementExecTimeoutMs ?? DEFAULT_ENFORCEMENT_EXEC_TIMEOUT_MS;
-        // Never less than a full blocked-streak's worth of worst-case probes: a longer configured exec
-        // timeout that left this unchanged could make the wall-clock bound expire before the loop ever
-        // has a chance to observe ENFORCEMENT_BLOCKED_STREAK consecutive probes, which would turn "the
-        // keeper is just slow" into an indistinguishable "the policy is not enforced" false negative.
-        // DEFAULT_ENFORCEMENT_TIMEOUT_MS (30_000) already equals the default exec timeout times the
-        // streak (10_000 * 3), so this is a no-op unless a longer exec timeout is actually configured.
-        this.enforcementTimeoutMs = Math.max(options.enforcementTimeoutMs ?? DEFAULT_ENFORCEMENT_TIMEOUT_MS, this.enforcementExecTimeoutMs * ENFORCEMENT_BLOCKED_STREAK);
+        // One exec runs a whole streak: ENFORCEMENT_BLOCKED_STREAK probes, each within its own
+        // per-probe budget, with ENFORCEMENT_POLL_MS between consecutive probes.
+        this.streakExecTimeoutMs =
+            this.enforcementExecTimeoutMs * ENFORCEMENT_BLOCKED_STREAK +
+                ENFORCEMENT_POLL_MS * (ENFORCEMENT_BLOCKED_STREAK - 1);
+        // Never less than one full streak exec's worst case: a longer configured per-probe budget that
+        // left this unchanged could make the wall-clock bound expire inside the first slow streak exec,
+        // leaving no room to retry a streak broken while the policy was still being programmed — which
+        // would turn "the keeper is just slow" into an indistinguishable "the policy is not enforced"
+        // false negative. At the defaults this raises DEFAULT_ENFORCEMENT_TIMEOUT_MS (30_000) to the
+        // default streak exec timeout (10_000 * 3 + 500 * 2 = 31_000).
+        this.enforcementTimeoutMs = Math.max(options.enforcementTimeoutMs ?? DEFAULT_ENFORCEMENT_TIMEOUT_MS, this.streakExecTimeoutMs);
         this.createArchive = options.createArchive ?? hostTarArchive;
         this.warn = options.onWarning ?? ((message) => kubernetesLog.warn(message));
     }
@@ -491,6 +498,11 @@ export class KubernetesJobLauncher {
                 this.warn(`kubernetes_spec_rejected: ${error.message}`);
             throw error;
         }
+        // Low-power mode: the proxy may be scaled to zero; wake it before the preflight reads it. Guarded
+        // (not just a no-op await) so mode off keeps launch() joining an in-flight warm-up synchronously.
+        if (this.power.enabled) {
+            await this.power.ensureAwake("proxy", { timeoutMs: wakeTimeoutMs(this.readyTimeoutMs), runId: spec.runId });
+        }
         await this.runPreflight();
         const names = kubernetesRunNames(spec.runId);
         const handle = { backend: BACKEND, id: `${this.namespace}/${names.token}` };
@@ -614,7 +626,69 @@ export class KubernetesJobLauncher {
     }
     // -------------------------------------------------------------------------
     // Launch
-    /** Memoized: the preflight (or, without one, a single proxy-witness read) runs once per launcher. */
+    /**
+     * Low-power mode: whether the proxy is scaled to zero. A failed check is logged by code only (the
+     * leading reason code, else the error's class name -- never the raw message, which could carry
+     * cluster detail) and counts as awake, so warm-up runs the preflight as it would without the mode.
+     */
+    async proxyAsleep() {
+        try {
+            return await this.power.isAsleep("proxy");
+        }
+        catch (error) {
+            const code = (error instanceof Error && /^[a-z][a-z0-9_]*(?=:)/.exec(error.message)?.[0]) ||
+                (error instanceof Error ? error.name : "unknown");
+            this.warn(`kubernetes_preflight_power_check_failed: ${code}`);
+            return false;
+        }
+    }
+    /**
+     * Starts the memoized cluster preflight (`runPreflight`) right away, instead of waiting for the
+     * first `launch()`, so a long-running server process's own start-up pays the preflight's cost (a
+     * canary pod on `kind`: ~20s) rather than that process's first coding run. Never throws: it only
+     * reports the outcome (an info line on success, a warning naming the failure code otherwise) so
+     * an operator sees a misconfigured cluster at boot. Any `launch()` already awaiting this same
+     * attempt (concurrent with this call) still fails exactly as it does today when the preflight
+     * failed — it shares the same rejected promise. But unlike a preflight `launch()` starts on its
+     * own, a start-up failure here is **not** left stuck memoized: a transient cluster problem at
+     * process start must not fail every coding run until restart, so the failed attempt is cleared
+     * (only if nothing has already started a newer one — compared by identity, never by state) and
+     * the *next* `launch()` runs the preflight fresh. A successful warm-up stays memoized as always.
+     * In low-power mode, while the proxy is asleep, warm-up is skipped (the memo stays unset) rather
+     * than waking the proxy only for the preflight; the first `launch()` wakes it and runs the preflight.
+     */
+    async warmUp() {
+        if (this.power.enabled && (await this.proxyAsleep())) {
+            kubernetesLog.info("kubernetes_preflight_deferred: proxy asleep (low-power mode); the first coding run runs the preflight");
+            return;
+        }
+        const attempt = this.runPreflight();
+        try {
+            await attempt;
+            kubernetesLog.info("kubernetes_preflight_warm_up_succeeded: cluster preflight passed at start-up");
+        }
+        catch (error) {
+            // Only clear the memo if it still holds this exact attempt: a concurrent launch() or warmUp()
+            // may have already seen this same rejection and started a fresh one (which must survive), and
+            // nothing else could have replaced this attempt with anything but a newer one, since
+            // runPreflight() never overwrites an already-set, still-pending-or-resolved promise.
+            if (this.preflightResult === attempt)
+                this.preflightResult = undefined;
+            // Same code-only convention as every other failure this launcher logs (e.g. launch()'s
+            // kubernetes_spec_rejected above): the error's own message is the fixed reason code set by
+            // runPreflight's errorWithCode (KUBERNETES_ISOLATION_ERROR) — never the raw cause, which could
+            // carry cluster detail.
+            const code = error instanceof Error ? error.message : String(error);
+            this.warn(`kubernetes_preflight_warm_up_failed: ${code}`);
+        }
+    }
+    /**
+     * Memoized: the preflight (or, without one, a single proxy-witness read) runs once per launcher —
+     * including its failure, which stays memoized and fails every subsequent `launch()` immediately,
+     * for a preflight `launch()` itself started (there was no `warmUp()`, or `warmUp()`'s own failed
+     * attempt was already cleared). `warmUp()` is the one caller that clears a failed attempt instead
+     * of leaving it stuck; see its own doc comment.
+     */
     runPreflight() {
         this.preflightResult ??= (async () => {
             try {
@@ -639,6 +713,14 @@ export class KubernetesJobLauncher {
      * proxy on CODING_PROXY_PORT and fail to reach it on CODING_PROXY_DENY_PORT. Anything else resets
      * the streak; the wall-clock bound still applies.
      *
+     * The whole streak runs in ONE keeper exec (`enforcementStreakScript`), so exec and interpreter
+     * start-up is paid once per streak rather than once per probe. That exec exits 0 only after the
+     * full streak was proven; otherwise it stops at the first non-proven probe and exits with that
+     * probe's code. Any non-zero exit is a broken streak: if the bound has been reached it is the
+     * verdict, else the launcher waits ENFORCEMENT_POLL_MS and starts a fresh streak from zero. The
+     * exec is bounded by `streakExecTimeoutMs` (the per-probe budget times the streak, plus the gaps);
+     * an exec that times out or fails throws, failing the launch exactly as a failed probe exec did.
+     *
      * "Fail to reach" means the connect *timed out* — the packet was dropped. A refusal (RST) is not
      * a denial: it proves the SYN reached the destination host, so the deny port is merely unserved
      * and witnesses nothing. That is its own verdict, below.
@@ -659,17 +741,16 @@ export class KubernetesJobLauncher {
      * must not open the gate at the initial proof either.
      */
     async waitForPolicyEnforcement(names, proxyIp, stage = "initial") {
-        const command = ["node", "-e", enforcementProbeScript(proxyIp)];
+        const command = ["node", "-e", enforcementStreakScript(proxyIp, ENFORCEMENT_BLOCKED_STREAK, ENFORCEMENT_POLL_MS)];
         const started = this.now();
-        let blocked = 0;
         for (;;) {
-            // `exitCode` is this iteration's probe, and the bound below is only ever reached from here —
-            // so the verdict is always the *last* probe's, never a remembered earlier one.
+            // `exitCode` is this attempt's streak, which stops at (and exits with) its first non-proven
+            // probe, and the bound below is only ever reached from here — so the verdict is always the
+            // *last* probe's, never a remembered earlier one.
             const exitCode = await this.api.exec(this.namespace, names.pod, KEEPER_CONTAINER, command, {
-                timeoutMs: this.enforcementExecTimeoutMs,
+                timeoutMs: this.streakExecTimeoutMs,
             });
-            blocked = exitCode === 0 ? blocked + 1 : 0;
-            if (blocked >= ENFORCEMENT_BLOCKED_STREAK)
+            if (exitCode === ENFORCEMENT_PROBE_PROVEN)
                 return;
             if (this.now() - started >= this.enforcementTimeoutMs) {
                 throw enforcementVerdict(exitCode, proxyIp, stage);
@@ -851,14 +932,14 @@ export class KubernetesJobLauncher {
         const staging = await mkdtemp(join(tmpdir(), "wardby-k8s-input-"));
         try {
             const source = await lstat(inputArtifact);
-            if (!source.isFile() || source.size > MAX_CODING_ARTIFACT_BYTES) {
+            if (!source.isFile() || source.size > MAX_CODING_INPUT_BYTES) {
                 throw new Error("kubernetes_input_artifact_invalid");
             }
             const copy = join(staging, "input.json");
             await copyFile(inputArtifact, copy);
             // Re-check the copy: the source could have changed between lstat and copy.
             const copied = await lstat(copy);
-            if (!copied.isFile() || copied.size > MAX_CODING_ARTIFACT_BYTES) {
+            if (!copied.isFile() || copied.size > MAX_CODING_INPUT_BYTES) {
                 throw new Error("kubernetes_input_artifact_invalid");
             }
             await this.seedDirectory(names, staging, INPUT_STORAGE, timeoutMs);

package/dist/providers/jobs/metadata-probes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cloud metadata endpoints a coding or native worker pod must never reach: they hand out node or
+ * workload credentials. The instance metadata service (GCE, EC2 IPv4), the EKS Pod Identity agent (IPv4
+ * and IPv6), and EC2's IPv6 IMDS endpoint. Probed on port 80, where every one of them serves. A pod without
+ * IPv6 fails the last connect immediately, which counts as unreachable — correct either way.
+ * src/sandbox/fetch-policy.ts blocks the same addresses for in-process fetches.
+ */
+export declare const CLOUD_METADATA_PROBES: readonly {
+    host: string;
+    port: number;
+}[];

package/dist/providers/jobs/metadata-probes.js

@@ -0,0 +1,13 @@
+/**
+ * Cloud metadata endpoints a coding or native worker pod must never reach: they hand out node or
+ * workload credentials. The instance metadata service (GCE, EC2 IPv4), the EKS Pod Identity agent (IPv4
+ * and IPv6), and EC2's IPv6 IMDS endpoint. Probed on port 80, where every one of them serves. A pod without
+ * IPv6 fails the last connect immediately, which counts as unreachable — correct either way.
+ * src/sandbox/fetch-policy.ts blocks the same addresses for in-process fetches.
+ */
+export const CLOUD_METADATA_PROBES = Object.freeze([
+    Object.freeze({ host: "169.254.169.254", port: 80 }),
+    Object.freeze({ host: "169.254.170.23", port: 80 }),
+    Object.freeze({ host: "fd00:ec2::254", port: 80 }),
+    Object.freeze({ host: "fd00:ec2::23", port: 80 }),
+]);

package/dist/providers/jobs/types.d.ts

@@ -88,6 +88,15 @@ export interface JobLauncher {
      * itself stays the authority.
      */
     hasCapacityFor?: (spec: JobSpec) => Promise<boolean>;
+    /**
+     * Starts any one-time start-up check (e.g. Kubernetes's memoized cluster preflight) right away,
+     * instead of waiting for the first `launch()`. Never throws — a failure is only logged — and
+     * `launch()` still runs and reports the same check itself, memoized exactly as if this had never
+     * been called. Composition roots call this, fire-and-forget, only from a long-running server
+     * process's own start-up (`wardby serve`, the MCP server, `wardby scheduler`); never from a
+     * one-shot CLI command. Absent on a launcher with nothing to warm up (e.g. Docker).
+     */
+    warmUp?: () => Promise<void>;
     launch: (spec: JobSpec) => Promise<JobHandle>;
     status: (handle: JobHandle) => Promise<JobStatus>;
     collect: (handle: JobHandle) => Promise<JobResult>;

package/dist/providers/llm/openai.js

@@ -153,7 +153,6 @@ export class OpenAiLlmProvider {
             store: false,
             ...(req.tools ? { tools: toOpenAiTools(req.tools) } : {}),
             ...(req.maxTokens !== undefined ? { max_output_tokens: Math.max(req.maxTokens, MIN_MAX_OUTPUT_TOKENS) } : {}),
-            // The SDK's ReasoningEffort type predates xhigh/max; the API accepts them.
             ...(sendEffort ? { reasoning: { effort: req.effort } } : {}),
             ...(sendTemperature ? { temperature: req.temperature } : {}),
         };

package/dist/providers/review-host/github.d.ts

@@ -5,7 +5,7 @@
  * and revokes it afterwards. See docs/private/2026-09-25-code-review-host-design.md §5.1.
  */
 import { type GitHubAppClient } from "../vcs/github.js";
-import { ReviewHostError, type CiView, type CodeReviewHost, type CommentInput, type CommentRef, type CompleteCheckInput, type EditCommentInput, type FileListView, type FileReadResult, type HostPermission, type HostUser, type PublishReviewInput, type PublishReviewResult, type PullRequestHead, type PullRequestOrigin, type PullRequestView, type StartCheckInput } from "./types.js";
+import { ReviewHostError, type CiView, type CodeReviewHost, type CommentInput, type CommentRef, type CompleteCheckInput, type EditCommentInput, type FileListView, type FileReadResult, type HostPermission, type HostUser, type PublishReviewInput, type PublishReviewResult, type PullRequestHead, type PullRequestOrigin, type PullRequestView, type StartCheckInput, type UpsertNamedCheckInput } from "./types.js";
 /** listFiles leaves out vendored trees and lockfiles; every host applies the same filter. */
 export declare function skippedInListing(path: string): boolean;
 type Json = Record<string, unknown>;
@@ -16,6 +16,7 @@ export declare class GitHubReviewHost implements CodeReviewHost {
     private readonly client;
     readonly provider: "github";
     constructor(client: GitHubAppClient);
+    appOwnerLogin(): Promise<string>;
     /** Runs `action` with a token for exactly `permissions`, translating failures to ReviewHostError. */
     protected withToken<T>(repository: string, permissions: Record<string, "read" | "write">, action: (get: (path: string, init?: RequestInit, expected?: number[]) => Promise<Response>, graphql: GraphQl) => Promise<T>): Promise<T>;
     repositoryPermission(repository: string, user: HostUser): Promise<{
@@ -70,5 +71,14 @@ export declare class GitHubReviewHost implements CodeReviewHost {
         checkId: string;
     }>;
     completeCheck(repository: string, input: CompleteCheckInput): Promise<void>;
+    /**
+     * Creates or updates, by fixed name, a check run on `input.headSha` that
+     * this App owns: lists the commit's check runs filtered to that name and
+     * patches the newest one `fromApp` owns, else creates one. Writes nothing
+     * when that run already carries the same status, conclusion, and output.
+     * A completed run is never moved back to in_progress (GitHub does not
+     * allow reopening a completed check run): a fresh one is created instead.
+     */
+    upsertNamedCheck(repository: string, input: UpsertNamedCheckInput): Promise<void>;
 }
 export {};

package/dist/providers/review-host/github.js

@@ -22,6 +22,12 @@ export function skippedInListing(path) {
     return VENDORED.test(path) || path.endsWith("package-lock.json");
 }
 const CHECK_TEXT_LIMIT = 65_535;
+/**
+ * Cap on a named check's output.title. Not a documented GitHub limit (none
+ * is published for the title); a conservative length that keeps the title
+ * a one-line heading in the checks UI.
+ */
+const CHECK_TITLE_LIMIT = 255;
 const COMMENT_WRITE = { issues: "write", pull_requests: "write" };
 const REVIEW_WRITE = { pull_requests: "write", checks: "write" };
 /** Always implicitly granted to an installation token; enough for the collaborator-permission endpoint. */
@@ -201,6 +207,9 @@ export class GitHubReviewHost {
     constructor(client) {
         this.client = client;
     }
+    async appOwnerLogin() {
+        return (await this.client.appIdentity()).ownerLogin;
+    }
     /** Runs `action` with a token for exactly `permissions`, translating failures to ReviewHostError. */
     async withToken(repository, permissions, action) {
         try {
@@ -708,4 +717,45 @@ export class GitHubReviewHost {
         const base = repoPath(repository);
         await this.withToken(repository, { checks: "write" }, (get) => this.patchCheck(get, base, input));
     }
+    /**
+     * Creates or updates, by fixed name, a check run on `input.headSha` that
+     * this App owns: lists the commit's check runs filtered to that name and
+     * patches the newest one `fromApp` owns, else creates one. Writes nothing
+     * when that run already carries the same status, conclusion, and output.
+     * A completed run is never moved back to in_progress (GitHub does not
+     * allow reopening a completed check run): a fresh one is created instead.
+     */
+    async upsertNamedCheck(repository, input) {
+        // A caller's bad input, like path_invalid: never interpolated into the URL.
+        if (!SAFE_SHA.test(input.headSha))
+            throw new ReviewHostError("host_api_error", "head_sha_invalid");
+        const base = repoPath(repository);
+        const output = {
+            title: input.title.slice(0, CHECK_TITLE_LIMIT),
+            summary: input.summary.slice(0, CHECK_TEXT_LIMIT),
+        };
+        const conclusion = input.status === "completed" ? input.conclusion : undefined;
+        await this.withToken(repository, { checks: "write" }, async (get) => {
+            const { id: appId } = await this.client.appIdentity();
+            const payload = record(await (await get(`${base}/commits/${input.headSha}/check-runs?check_name=${encodeURIComponent(input.name)}`)).json());
+            const existing = list(payload.check_runs ?? [])
+                .filter((r) => fromApp(r, appId))
+                .sort((a, b) => num(b.id) - num(a.id))[0];
+            const body = { status: input.status, ...(conclusion ? { conclusion } : {}), output };
+            if (existing) {
+                const current = record(existing.output ?? {});
+                const unchanged = existing.status === input.status &&
+                    (existing.conclusion ?? undefined) === conclusion &&
+                    current.title === output.title &&
+                    current.summary === output.summary;
+                if (unchanged)
+                    return;
+                if (!(existing.status === "completed" && input.status !== "completed")) {
+                    await get(`${base}/check-runs/${encodeURIComponent(String(num(existing.id)))}`, { method: "PATCH", body: JSON.stringify(body) }, [200]);
+                    return;
+                }
+            }
+            await get(`${base}/check-runs`, { method: "POST", body: JSON.stringify({ name: input.name, head_sha: input.headSha, ...body }) }, [201]);
+        });
+    }
 }

package/dist/providers/review-host/types.d.ts

@@ -207,6 +207,18 @@ export interface CompleteCheckInput {
     text?: string;
     detailsUrl?: string;
 }
+export type UpsertNamedCheckInput = {
+    headSha: string;
+    /** The check's fixed name, e.g. MERGE_ORDER_CHECK_NAME ("wardby merge order"); identifies which run to update. */
+    name: string;
+    title: string;
+    summary: string;
+} & ({
+    status: "in_progress";
+} | {
+    status: "completed";
+    conclusion: "success" | "failure";
+});
 /**
  * A user's effective permission on one repository, host-neutral and ranked
  * none < read < triage < write < maintain < admin. GitHub maps its
@@ -222,6 +234,8 @@ export interface HostUser {
 }
 export interface CodeReviewHost {
     readonly provider: ReviewHostProvider;
+    /** The GitHub App's owner account (always served; see WARDBY_GITHUB_ALLOWED_ACCOUNTS). Hosts without an App omit it. */
+    appOwnerLogin?(): Promise<string>;
     /**
      * The user's effective permission on `repository`, asked with the App's own
      * installation credential (never a user token). Answers only for the user
@@ -274,6 +288,15 @@ export interface CodeReviewHost {
         checkId: string;
     }>;
     completeCheck(repository: string, input: CompleteCheckInput): Promise<void>;
+    /**
+     * Creates or updates, by fixed name, a check run on one commit that isn't
+     * tied to a run's own startCheck/completeCheck lifecycle (e.g. the
+     * `wardby merge order` check, recomputed fresh and reposted on demand).
+     * Finds the one this App owns among the commit's check runs with that
+     * name and patches it; creates one when none exists. Hosts that can't
+     * post checks (e.g. a local repository) leave this out.
+     */
+    upsertNamedCheck?(repository: string, input: UpsertNamedCheckInput): Promise<void>;
 }
 export type ReviewHostErrorCode = "host_not_installed" | "host_permission_missing" | "host_api_error" | "host_invalid_response";
 export declare class ReviewHostError extends Error {

package/dist/providers/vcs/github.d.ts

@@ -149,9 +149,16 @@ export interface RelatedPullRequestEntry {
     state?: RelatedPullRequestState;
     /** The pull request whose description this section is in. */
     self?: boolean;
+    /**
+     * Step in the delegating agent's declared merge order (1-99), from
+     * CodingRun.mergeOrder; absent = the delegating agent set no order
+     * (an open entry is listed under "Not ordered:" when any other entry,
+     * open or done, has one).
+     */
+    mergeOrder?: number;
 }
 export interface RelatedPullRequestsInput {
-    /** In suggested merge order (the order the request's coding runs were dispatched). */
+    /** In merge order: by mergeOrder when set, else the order the request's coding runs were dispatched. */
     entries: readonly RelatedPullRequestEntry[];
     issue?: {
         key: string;
@@ -162,9 +169,18 @@ export interface RelatedPullRequestsInput {
 /**
  * The "Related pull requests" block, markers included, built only from
  * stored rows (never agent text). Open (and draft, and not-yet-known) pull
- * requests form the numbered suggested merge order; merged and closed ones
- * follow as context. Undefined when no other valid pull request is left after
- * validation: a set of one is not a set.
+ * requests form the merge order; merged and closed ones follow as context.
+ * Undefined when no other valid pull request is left after validation: a
+ * set of one is not a set.
+ *
+ * When any valid entry (open, merged or closed) carries a `mergeOrder` (set
+ * by the delegating agent), steps are counted over all of them, so a
+ * label never changes as pull requests merge: the open entries that have
+ * one are numbered under "Merge order" and labelled with their step (equal
+ * `mergeOrder` values share a step label), any open entry without one is
+ * listed after under "Not ordered:", and a merged or closed entry that has
+ * one carries its step label in the context list too. Otherwise every open
+ * entry is numbered in the unordered "Suggested merge order" list.
  */
 export declare function renderRelatedSection(input: RelatedPullRequestsInput): string | undefined;
 /**
@@ -228,11 +244,21 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
      */
     readFileAtRef(input: RepositoryFileInput): Promise<string | null>;
     private identity?;
-    /** The App's id and slug (its @-mention handle), read once with the App JWT. */
-    appIdentity(): Promise<{
+    /**
+     * The App's id, slug (its @-mention handle), and owner account, read once
+     * with the App JWT and memoized. `fresh` re-reads GET /app and replaces the
+     * memo (used before a destructive action, since the owner can change).
+     * A rejection is never cached.
+     */
+    appIdentity(opts?: {
+        fresh?: boolean;
+    }): Promise<{
         id: number;
         slug: string;
+        ownerLogin: string;
     }>;
+    /** Removes this App from an installation (an account outside the trusted set). */
+    deleteInstallation(installationId: number): Promise<void>;
     upsertContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
     updateContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
     createContinuationCheckRun(input: ContinuationCheckRunInput): Promise<void>;