@wardby/cli 0.5.3 → 0.6.0

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

@@ -1,4 +1,4 @@
-import type { V1NetworkPolicy, V1Pod, V1Secret } from "@kubernetes/client-node";
+import type { V1Container, V1NetworkPolicy, V1Pod, V1Secret } from "@kubernetes/client-node";
 import { type ResolvedCodingService } from "../../coding/services/catalog.js";
 import type { JobSpec } from "./types.js";
 import { type KubernetesPlatform } from "./kubernetes-platform.js";
@@ -81,6 +81,8 @@ export interface RunPodOptions {
 export declare function buildRunPod(spec: JobSpec, options: RunPodOptions): V1Pod;
 export declare function buildRunNetworkPolicy(spec: JobSpec, namespace: string): V1NetworkPolicy;
 export declare function buildCapabilitySecret(spec: JobSpec, namespace: string, capability: string, toolSetup?: string): V1Secret;
+/** A copy of a container's resources with every quantity in one rendering ("1" and "1000m" alike); see normalizeResources. */
+export declare function canonicalResources(r?: V1Container["resources"]): V1Container["resources"];
 /**
  * A copy of `pod` with ONLY the API server's own defaulting and aliasing undone
  * — the same `normalizeSpec` pass `assertRunPodMatches` runs, and nothing else.

package/dist/providers/jobs/kubernetes-isolation.js

@@ -561,6 +561,12 @@ function normalizeResources(r) {
             bag["ephemeral-storage"] = memoryBytes(bag["ephemeral-storage"]);
     }
 }
+/** A copy of a container's resources with every quantity in one rendering ("1" and "1000m" alike); see normalizeResources. */
+export function canonicalResources(r) {
+    const copy = r ? JSON.parse(JSON.stringify(r)) : undefined;
+    normalizeResources(copy);
+    return copy;
+}
 function normalizeProbe(p) {
     if (!p)
         return;

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

@@ -29,7 +29,7 @@
  * regresses to a documentation-only fixture again.
  */
 import type { V1PodSpec, V1Toleration } from "@kubernetes/client-node";
-export type KubernetesPlatform = "generic" | "gke-autopilot";
+export type KubernetesPlatform = "generic" | "gke-autopilot" | "eks";
 export declare const KUBERNETES_PLATFORMS: readonly KubernetesPlatform[];
 export declare const KUBERNETES_PLATFORM_ERROR = "kubernetes_platform_unconformable";
 /** A request the platform cannot legally run, refused here instead of being silently adjusted by the platform. */
@@ -84,6 +84,9 @@ export interface KubernetesPlatformProfile {
     /** gVisor is mandatory: an unset or different runtime class is refused at startup, not warned about. */
     requiresGvisor: boolean;
 }
+/** Node label and taint key of the EKS sandbox node group; deploy/aws and overlays/eks use the same strings. */
+export declare const EKS_SANDBOX_NODE_LABEL = "wardby.dev/sandbox";
+export declare const EKS_SANDBOX_TAINT_KEY = "sandbox";
 export declare function platformProfile(name: KubernetesPlatform): KubernetesPlatformProfile;
 export interface ContainerResourceRequest {
     cpuMillicores: number;

package/dist/providers/jobs/kubernetes-platform.js

@@ -1,4 +1,8 @@
-export const KUBERNETES_PLATFORMS = Object.freeze(["generic", "gke-autopilot"]);
+export const KUBERNETES_PLATFORMS = Object.freeze([
+    "generic",
+    "gke-autopilot",
+    "eks",
+]);
 export const KUBERNETES_PLATFORM_ERROR = "kubernetes_platform_unconformable";
 /** A request the platform cannot legally run, refused here instead of being silently adjusted by the platform. */
 export class KubernetesPlatformError extends Error {
@@ -109,9 +113,42 @@ const GKE_AUTOPILOT = {
     },
     requiresGvisor: true,
 };
+/** Node label and taint key of the EKS sandbox node group; deploy/aws and overlays/eks use the same strings. */
+export const EKS_SANDBOX_NODE_LABEL = "wardby.dev/sandbox";
+export const EKS_SANDBOX_TAINT_KEY = "sandbox";
+/**
+ * Amazon EKS with a dedicated gVisor node group (deploy/aws). EKS has no managed sandbox runtime, so
+ * the node group's launch template installs runsc and the overlay's `gvisor` RuntimeClass schedules
+ * onto it: the RuntimeClass admission plugin merges its `scheduling` block into the pod, which is
+ * the toleration and nodeSelector below — wardby never sets either itself (see SYMMETRY CAVEAT).
+ *
+ * PROVISIONAL: written from the RuntimeClass spec, not yet a server-side dry-run capture. EKS has no
+ * Autopilot-style resource admission, so resources are the generic rules plus explicit ephemeral
+ * storage (kubelet eviction accounting on a shared sandbox node). Replace the fixture with a real
+ * capture before relying on the allowance list (fixtures/eks-dry-run.json).
+ */
+const EKS = {
+    name: "eks",
+    resources: {
+        cpuFloorMillicores: 0,
+        cpuIncrementMillicores: 1,
+        memoryPerCpuMinMib: 0,
+        memoryPerCpuMaxMib: Number.POSITIVE_INFINITY,
+        explicitEphemeralStorage: true,
+    },
+    metadata: {
+        podAnnotationKeyPrefixes: [],
+        podLabelKeyPrefixes: [],
+        tolerations: [{ key: EKS_SANDBOX_TAINT_KEY, operator: "Equal", value: GVISOR_RUNTIME_CLASS, effect: "NoSchedule" }],
+        nodeSelector: { [EKS_SANDBOX_NODE_LABEL]: GVISOR_RUNTIME_CLASS },
+        dropsPodSeccompProfile: false,
+    },
+    requiresGvisor: true,
+};
 const PROFILES = Object.freeze({
     generic: freezeProfile(GENERIC),
     "gke-autopilot": freezeProfile(GKE_AUTOPILOT),
+    eks: freezeProfile(EKS),
 });
 export function platformProfile(name) {
     const profile = PROFILES[name];

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

@@ -40,7 +40,8 @@ export interface CanaryResult {
  * probe (`enforcementProbeScript`), which had to make the same distinction after a live cluster
  * with no NetworkPolicy at all passed a boolean version of this check; preflight and gate must
  * agree on what counts as evidence, or one of them is vacuous. `internet`, `metadata` and `proxy`
- * stay plain reachability, where "connected" is the only thing that matters.
+ * stay plain reachability, where "connected" is the only thing that matters; `metadata` is true if
+ * **any** cloud metadata endpoint connects.
  *
  * CNIs program a new pod's policy a few seconds after it starts, so the script first waits (up to
  * 20 s) for the deny-port connect to be *dropped*; if it never is, `proxyDeny` reports true.

package/dist/providers/jobs/kubernetes-preflight.js

@@ -11,6 +11,7 @@ import { randomBytes } from "node:crypto";
 import { CODING_PROXY_DENY_PORT, CODING_PROXY_PORT } from "./docker-isolation.js";
 import { KUBERNETES_ISOLATION_ERROR, WORKER_CONTAINER, buildRunNetworkPolicy, buildRunPod, isRegistryDigest, } from "./kubernetes-isolation.js";
 import { KubernetesPlatformError, assertPlatformConfig, platformProfile } from "./kubernetes-platform.js";
+import { CLOUD_METADATA_PROBES } from "./metadata-probes.js";
 import { readProxyWitness } from "./kubernetes-witness.js";
 /**
  * The image the preflight canary runs (it only needs node): the Codex worker when configured,
@@ -40,7 +41,8 @@ const CANARY_KEYS = Object.keys(EXPECTED).sort();
  * probe (`enforcementProbeScript`), which had to make the same distinction after a live cluster
  * with no NetworkPolicy at all passed a boolean version of this check; preflight and gate must
  * agree on what counts as evidence, or one of them is vacuous. `internet`, `metadata` and `proxy`
- * stay plain reachability, where "connected" is the only thing that matters.
+ * stay plain reachability, where "connected" is the only thing that matters; `metadata` is true if
+ * **any** cloud metadata endpoint connects.
  *
  * CNIs program a new pod's policy a few seconds after it starts, so the script first waits (up to
  * 20 s) for the deny-port connect to be *dropped*; if it never is, `proxyDeny` reports true.
@@ -81,7 +83,7 @@ export const CANARY_SCRIPT = [
     "    ),",
     `    proxyDeny: !(await dropped(process.env.WARDBY_CANARY_PROXY_IP, ${CODING_PROXY_DENY_PORT})),`,
     '    internet: await reachable("1.1.1.1", 443),',
-    '    metadata: await reachable("169.254.169.254", 80),',
+    `    metadata: (await Promise.all(${JSON.stringify(CLOUD_METADATA_PROBES.map((p) => [p.host, p.port]))}.map(([host, port]) => reachable(host, port)))).some(Boolean),`,
     `    proxy: await reachable(process.env.WARDBY_CANARY_PROXY_IP, ${CODING_PROXY_PORT}),`,
     "  };",
     "  console.log(JSON.stringify({ wardbyCanary }));",

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,6 +20,11 @@ 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;
@@ -67,6 +73,7 @@ export declare class KubernetesJobLauncher implements WorkspaceJobLauncher {
     /** 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:
@@ -94,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

package/dist/providers/jobs/kubernetes.js

@@ -29,7 +29,8 @@ 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";
@@ -386,9 +387,11 @@ export class KubernetesJobLauncher {
     /** 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("/"))
@@ -495,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}` };
@@ -618,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 {
@@ -862,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/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>;