From e9e41ee196d8d0050118f105ef99f862eaecfa5d Mon Sep 17 00:00:00 2001
From: debuggingfuture <hi@debuggingfuture.com>
Date: Thu, 22 Oct 2026 16:33:37 +0800
Subject: [PATCH 1/5] feat(dispatch): skip webhook runs a repo never opted in
 to

A run declares optIn: ({ input }) => CONFIG_KV keys. The webhook receiver
reads them before it creates a Workflow; with none present it dispatches
nothing and lists the run in skipped with reason not-configured. check,
offload-test and worker-deploy declare the command keys their bodies read.
A dispatch carrying its own command needs no read, and a failed read
dispatches as before.

Spec: specs/adr/0007-cost-efficient-execution.md (Dispatch only work)
---
 apps/dispatcher/src/opt-in.ts              |  41 ++++++
 apps/dispatcher/src/routes/webhook.test.ts | 151 ++++++++++++++++++++-
 apps/dispatcher/src/routes/webhook.ts      |  34 ++++-
 packages/core/src/define-run.ts            |  16 +++
 packages/core/src/index.ts                 |   1 +
 runs/check.test.ts                         |  10 ++
 runs/check.ts                              |   6 +
 runs/offload-test.test.ts                  |  10 ++
 runs/offload-test.ts                       |   8 ++
 runs/worker-deploy.test.ts                 |   9 ++
 runs/worker-deploy.ts                      |   5 +
 11 files changed, 283 insertions(+), 8 deletions(-)
 create mode 100644 apps/dispatcher/src/opt-in.ts

diff --git a/apps/dispatcher/src/opt-in.ts b/apps/dispatcher/src/opt-in.ts
new file mode 100644
index 00000000..2fd347d9
--- /dev/null
+++ b/apps/dispatcher/src/opt-in.ts
@@ -0,0 +1,41 @@
+// FlareDispatch Dispatcher — receiver-side opt-in.
+//
+// A run may declare `optIn: ({ input }) => keys` (packages/core define-run.ts):
+// the CONFIG_KV keys whose presence means the repo opted in. The webhook
+// receiver reads them before it creates a Workflow, so a repo that never
+// configured the run costs no Workflow, check-run, admission slot or container
+// (specs/adr/0007-cost-efficient-execution.md § Dispatch only work).
+//
+// The read fails open. A KV error, or a deploy without CONFIG_KV, dispatches
+// exactly as the receiver did before the check existed: the run body still
+// resolves its own command and no-ops when there is none, so a failed read
+// costs one wasted run, never a configured repo's verdict.
+
+/** The receiver's decision for one triggered run. */
+export type OptInVerdict = "dispatch" | "not-configured";
+
+/**
+ * Decide whether to dispatch a run whose `optIn` named `keys`.
+ *
+ * `keys` empty (the inputs carry their own command) or no `configKv` →
+ * `dispatch` with no read. Otherwise any present key → `dispatch`; none →
+ * `not-configured`. A rejected read logs and answers `dispatch`.
+ */
+export const resolveOptIn = async (args: {
+  readonly configKv: KVNamespace | undefined;
+  readonly runName: string;
+  readonly keys: readonly string[];
+}): Promise<OptInVerdict> => {
+  const { configKv, runName, keys } = args;
+  if (keys.length === 0 || configKv === undefined) return "dispatch";
+  try {
+    const values = await Promise.all(keys.map((key) => configKv.get(key)));
+    return values.some((value) => value !== null) ? "dispatch" : "not-configured";
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    console.error(
+      `[webhook] opt-in read failed run="${runName}" keys=${JSON.stringify(keys)}: ${message} — dispatching`,
+    );
+    return "dispatch";
+  }
+};
diff --git a/apps/dispatcher/src/routes/webhook.test.ts b/apps/dispatcher/src/routes/webhook.test.ts
index 762f2462..6c1f88cd 100644
--- a/apps/dispatcher/src/routes/webhook.test.ts
+++ b/apps/dispatcher/src/routes/webhook.test.ts
@@ -69,7 +69,12 @@ const webhookRequest = async (
 };
 
 const fixture = (
-  opts: { withWebhookSecret?: boolean; withKv?: boolean; publicOrigin?: string } = {},
+  opts: {
+    withWebhookSecret?: boolean;
+    withKv?: boolean;
+    publicOrigin?: string;
+    configKv?: KVNamespace;
+  } = {},
 ) => {
   const workflow = makeFakeWorkflow();
   const storage = makeFakeR2();
@@ -81,6 +86,7 @@ const fixture = (
     idempotencyKv: idempotencyKv?.binding,
     githubWebhookSecret: opts.withWebhookSecret === false ? undefined : WEBHOOK_SECRET,
     ...(opts.publicOrigin !== undefined ? { publicOrigin: opts.publicOrigin } : {}),
+    ...(opts.configKv !== undefined ? { configKv: opts.configKv } : {}),
   });
   return { workflow, storage, env, idempotencyKv };
 };
@@ -566,3 +572,146 @@ describe("POST /v1/webhooks/github — pull request closed", () => {
   });
 });
 
+describe("POST /v1/webhooks/github — receiver opt-in", () => {
+  /** A pull_request payload passing the check / offload-test gates. */
+  const prPayload = {
+    action: "synchronize",
+    pull_request: {
+      number: 7,
+      draft: false,
+      labels: [],
+      user: { login: "octocat" },
+      head: { sha: "aaaa111122223333" },
+      base: { sha: "base000000000000" },
+    },
+    repository: { full_name: "owner/test-repo" },
+    installation: { id: 99999 },
+  };
+
+  /** A default-branch check_suite payload passing worker-deploy's gate. */
+  const checkSuitePayload = {
+    action: "requested",
+    check_suite: { head_branch: "main", head_sha: "dddd111122223333" },
+    repository: { full_name: "owner/test-repo", default_branch: "main" },
+    installation: { id: 99999 },
+  };
+
+  type Body = {
+    dispatched: Array<{ run: string }>;
+    skipped?: Array<{ run: string; reason: string }>;
+  };
+
+  const deliver = async (
+    env: Parameters<typeof handleRequest>[1],
+    payload: unknown,
+    event: string,
+  ): Promise<Body> => {
+    const res = await handleRequest(await webhookRequest(payload, { event }), env);
+    expect(res.status).toBe(202);
+    return (await res.json()) as Body;
+  };
+
+  const createdRuns = (workflow: ReturnType<typeof makeFakeWorkflow>): string[] =>
+    workflow.calls.map((c) => (c.params as { run: string }).run);
+
+  it("a repo with none of a run's keys creates no Workflow and lists it not-configured", async () => {
+    const configKv = makeFakeKv();
+    const { env, workflow } = fixture({ configKv: configKv.binding });
+
+    const body = await deliver(env, prPayload, "pull_request");
+
+    expect(body.skipped).toEqual(
+      expect.arrayContaining([
+        { run: "check", reason: "not-configured" },
+        { run: "offload-test", reason: "not-configured" },
+      ]),
+    );
+    expect(body.dispatched.map((d) => d.run)).not.toContain("check");
+    expect(body.dispatched.map((d) => d.run)).not.toContain("offload-test");
+    expect(createdRuns(workflow)).not.toContain("check");
+    expect(createdRuns(workflow)).not.toContain("offload-test");
+    // A run without `optIn` dispatches as before.
+    expect(body.dispatched.map((d) => d.run)).toContain("pr-review");
+  });
+
+  it("a present per-repo command key dispatches that run only", async () => {
+    const configKv = makeFakeKv();
+    configKv.store.set("check.command:owner/test-repo", "pnpm lint");
+    const { env, workflow } = fixture({ configKv: configKv.binding });
+
+    const body = await deliver(env, prPayload, "pull_request");
+
+    expect(body.dispatched.map((d) => d.run)).toContain("check");
+    expect(createdRuns(workflow)).toContain("check");
+    expect(body.skipped).toEqual([{ run: "offload-test", reason: "not-configured" }]);
+  });
+
+  it("offload-test opts in through the dispatcher-wide command or the stages key", async () => {
+    for (const key of ["offload-test.command", "offload-test.stages:owner/test-repo"]) {
+      const configKv = makeFakeKv();
+      configKv.store.set(key, "unit");
+      const { env } = fixture({ configKv: configKv.binding });
+
+      const body = await deliver(env, prPayload, "pull_request");
+
+      expect(body.dispatched.map((d) => d.run)).toContain("offload-test");
+      expect(body.skipped?.map((s) => s.run)).not.toContain("offload-test");
+    }
+  });
+
+  it("worker-deploy skips a repo without its command key and dispatches one with it", async () => {
+    const configKv = makeFakeKv();
+    const { env, workflow } = fixture({ configKv: configKv.binding });
+
+    const skippedBody = await deliver(env, checkSuitePayload, "check_suite");
+    expect(skippedBody.skipped).toEqual(
+      expect.arrayContaining([{ run: "worker-deploy", reason: "not-configured" }]),
+    );
+    expect(createdRuns(workflow)).not.toContain("worker-deploy");
+
+    configKv.store.set("worker-deploy.command:owner/test-repo", "pnpm deploy");
+    const { env: configured, workflow: configuredWorkflow } = fixture({
+      configKv: configKv.binding,
+    });
+    const body = await deliver(configured, checkSuitePayload, "check_suite");
+    expect(body.dispatched.map((d) => d.run)).toContain("worker-deploy");
+    expect(createdRuns(configuredWorkflow)).toContain("worker-deploy");
+  });
+
+  it("a failed opt-in read dispatches as before and logs", async () => {
+    const configKv = {
+      get: async () => {
+        throw new Error("kv unavailable");
+      },
+    } as unknown as KVNamespace;
+    const { env, workflow } = fixture({ configKv });
+    const errors: string[] = [];
+    const original = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    };
+    try {
+      const body = await deliver(env, prPayload, "pull_request");
+      expect(body.dispatched.map((d) => d.run)).toEqual(
+        expect.arrayContaining(["check", "offload-test"]),
+      );
+      expect(body.skipped).toBeUndefined();
+      expect(createdRuns(workflow)).toEqual(expect.arrayContaining(["check", "offload-test"]));
+    } finally {
+      console.error = original;
+    }
+    expect(errors.some((e) => e.includes("opt-in read failed") && e.includes('run="check"'))).toBe(
+      true,
+    );
+  });
+
+  it("a deploy without CONFIG_KV dispatches as before", async () => {
+    const { env } = fixture();
+    const body = await deliver(env, prPayload, "pull_request");
+    expect(body.dispatched.map((d) => d.run)).toEqual(
+      expect.arrayContaining(["check", "offload-test"]),
+    );
+    expect(body.skipped).toBeUndefined();
+  });
+});
+
diff --git a/apps/dispatcher/src/routes/webhook.ts b/apps/dispatcher/src/routes/webhook.ts
index 2849c004..a7204fe0 100644
--- a/apps/dispatcher/src/routes/webhook.ts
+++ b/apps/dispatcher/src/routes/webhook.ts
@@ -35,6 +35,7 @@
 import { checkAndArmCooldown } from "../cooldown";
 import { verify } from "../hmac";
 import { toInstanceId } from "../instance-id";
+import { resolveOptIn } from "../opt-in";
 import { closedGroups, closeInstanceId, type CloseGroupPayload } from "../pr-close";
 import { triggersByEvent } from "../registry";
 import { resolveReleaseApproval } from "../release-approval";
@@ -268,12 +269,15 @@ export const handleGithubWebhook = async (request: Request, env: Env): Promise<R
   }
 
   const dispatched: Array<{ run: string; executionId: string }> = [];
-  const skipped: Array<{
-    run: string;
-    executionId: string;
-    reason: "cooldown";
-    retryAfterSec: number;
-  }> = [];
+  const skipped: Array<
+    | {
+        run: string;
+        executionId: string;
+        reason: "cooldown";
+        retryAfterSec: number;
+      }
+    | { run: string; reason: "not-configured" }
+  > = [];
   for (const { run, trigger } of matches) {
     if (
       trigger.actions !== undefined &&
@@ -287,6 +291,21 @@ export const handleGithubWebhook = async (request: Request, env: Env): Promise<R
     const id = toInstanceId(trigger.idempotencyKey(ctx));
     const inputs = trigger.inputs(ctx);
 
+    // Opt-in (when declared) — a repo with none of the run's CONFIG_KV keys
+    // gets no Workflow, no check-run and no admission slot. Read before the
+    // cooldown so an unconfigured repo never arms a window.
+    if (run.optIn !== undefined) {
+      const optIn = await resolveOptIn({
+        configKv: env.CONFIG_KV,
+        runName: run.name,
+        keys: run.optIn({ input: inputs }),
+      });
+      if (optIn === "not-configured") {
+        skipped.push({ run: run.name, reason: "not-configured" });
+        continue;
+      }
+    }
+
     // Run cooldown (when declared) — same check-and-arm Action mode applies,
     // so the cap holds across BOTH dispatch paths. A skipped trigger is
     // reported (not silently dropped) with the execution it collapsed into.
@@ -354,7 +373,8 @@ export const handleGithubWebhook = async (request: Request, env: Env): Promise<R
       event,
       deliveryId,
       dispatched,
-      // Shape-stable: `skipped` appears only when a cooldown actually fired.
+      // Shape-stable: `skipped` appears only when a cooldown or an opt-in
+      // check actually skipped a run.
       ...(skipped.length > 0 ? { skipped } : {}),
       ...(closed.length > 0 ? { closed } : {}),
     },
diff --git a/packages/core/src/define-run.ts b/packages/core/src/define-run.ts
index d422d4a9..dbdbd6e8 100644
--- a/packages/core/src/define-run.ts
+++ b/packages/core/src/define-run.ts
@@ -54,6 +54,11 @@ export type CooldownSpec<I> = {
   readonly scope: (input: I) => string;
 };
 
+/** What a run's `optIn` reads its keys from: the dispatch's inputs. */
+export type OptInContext<I> = {
+  readonly input: I;
+};
+
 /** The raw GitHub webhook delivery; a run narrows it per-event itself. */
 export type WebhookPayload = Record<string, any>;
 
@@ -157,6 +162,17 @@ export type RunSpec<I, O, IEnc, OEnc> = {
    * Schedule mode is exempt (crons self-pace).
    */
   readonly cooldown?: CooldownSpec<I>;
+  /**
+   * The CONFIG_KV keys whose presence means the repo opted in to this run —
+   * exactly the keys the run body reads its command from. The webhook
+   * receiver reads them before it creates a Workflow: with none present it
+   * dispatches nothing and reports the run `skipped` as `not-configured`. An
+   * empty list means the inputs already carry the command (an Action or a
+   * fan-out parent named it), so no read happens. A failed read dispatches.
+   * The run body keeps its own opt-in check. See
+   * specs/adr/0007-cost-efficient-execution.md § Dispatch only work.
+   */
+  readonly optIn?: (ctx: OptInContext<I>) => readonly string[];
   /**
    * Declares that this run PAUSES for a human decision partway through — it
    * hibernates in `step.waitForEvent` until a person approves or rejects, and
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 4512ebec..14105fe6 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -17,6 +17,7 @@ export {
   type RunSpec,
   type RunLimits,
   type CooldownSpec,
+  type OptInContext,
   type HumanGateSpec,
   type SandboxImage,
   type SerializeSpec,
diff --git a/runs/check.test.ts b/runs/check.test.ts
index f4b7437c..51db7e11 100644
--- a/runs/check.test.ts
+++ b/runs/check.test.ts
@@ -654,6 +654,16 @@ describe("check", () => {
       }),
     ).toBe(false);
   });
+
+  it("optIn — names the command keys resolve-config reads; none when the dispatch carries one", () => {
+    const input = check.triggers![0]!.inputs({ payload: prPayload() });
+    expect(check.optIn?.({ input })).toEqual(["check.command:owner/name"]);
+    expect(check.optIn?.({ input: { ...input, checkLabel: "codegen" } })).toEqual([
+      "check.command:owner/name:codegen",
+      "check.command:owner/name",
+    ]);
+    expect(check.optIn?.({ input: { ...input, command: "pnpm lint" } })).toEqual([]);
+  });
 });
 
 // --- Source guard: no direct Date.now() / crypto.randomUUID() in the run -----
diff --git a/runs/check.ts b/runs/check.ts
index bdb35213..346257d5 100644
--- a/runs/check.ts
+++ b/runs/check.ts
@@ -278,6 +278,12 @@ export const check = defineRun({
     },
   ],
 
+  // The command keys `resolve-config` reads — the receiver skips a repo with
+  // none of them (specs/adr/0007-cost-efficient-execution.md § Dispatch only
+  // work). A webhook dispatch is unlabelled, so it reads `check.command:<repo>`.
+  optIn: ({ input }) =>
+    input.command !== undefined ? [] : commandKeys(input.repo, input.checkLabel),
+
   limits: {
     // Run-body wall-time ceiling, enforced by the dispatcher: one full 2700 s
     // exec (the per-stage ceiling a fan-out gate passes) plus checkout, upload
diff --git a/runs/offload-test.test.ts b/runs/offload-test.test.ts
index 796ce114..ce8a0394 100644
--- a/runs/offload-test.test.ts
+++ b/runs/offload-test.test.ts
@@ -469,6 +469,16 @@ describe("offload-test", () => {
     ).toBe(false);
   });
 
+  it("optIn — names the keys resolve-command decides on; none when the dispatch carries a command", () => {
+    const input = offloadTest.triggers![0]!.inputs({ payload: prPayload() });
+    expect(offloadTest.optIn?.({ input })).toEqual([
+      "offload-test.command:owner/name",
+      "offload-test.command",
+      "offload-test.stages:owner/name",
+    ]);
+    expect(offloadTest.optIn?.({ input: { ...input, command: "pnpm test" } })).toEqual([]);
+  });
+
   it.effect(
     "command resolution — a dispatch without `command` resolves it from CONFIG_KV (per-repo wins over the default)",
     () => {
diff --git a/runs/offload-test.ts b/runs/offload-test.ts
index b5077783..b2256418 100644
--- a/runs/offload-test.ts
+++ b/runs/offload-test.ts
@@ -506,6 +506,14 @@ export const offloadTest = defineRun({
   inputs: OffloadTestInput,
   outputs: OffloadTestOutput,
 
+  // The keys `resolve-command` decides on: the per-repo command, the
+  // dispatcher-wide default, and the stages key (staged mode runs with neither
+  // command). See specs/adr/0007-cost-efficient-execution.md § Dispatch only work.
+  optIn: ({ input }) =>
+    input.command !== undefined
+      ? []
+      : [repoCommandKey(input.repo), COMMAND_KEY, repoStagesKey(input.repo)],
+
   limits: {
     // Run-body wall-time ceiling — specs/02-runs.md § 1, enforced by the
     // dispatcher. One documented 1800 s exec plus checkout, install and
diff --git a/runs/worker-deploy.test.ts b/runs/worker-deploy.test.ts
index e0a298e4..3d6f2b2e 100644
--- a/runs/worker-deploy.test.ts
+++ b/runs/worker-deploy.test.ts
@@ -646,6 +646,15 @@ describe("worker-deploy", () => {
       }),
     ).toBe(false);
   });
+
+  it("optIn — names the command key resolve-config reads; none when the dispatch carries one", () => {
+    const input = workerDeploy.triggers![0]!.inputs({ payload: checkSuitePayload() });
+    expect(workerDeploy.optIn?.({ input })).toEqual(["worker-deploy.command:owner/name"]);
+    expect(workerDeploy.optIn?.({ input: { ...input, checkLabel: "docs" } })).toEqual([
+      "worker-deploy.command:owner/name:docs",
+    ]);
+    expect(workerDeploy.optIn?.({ input: { ...input, command: "pnpm deploy" } })).toEqual([]);
+  });
 });
 
 // --- Source guard: no direct Date.now() / crypto.randomUUID() in the run -----
diff --git a/runs/worker-deploy.ts b/runs/worker-deploy.ts
index 17bb88a4..e60b28c4 100644
--- a/runs/worker-deploy.ts
+++ b/runs/worker-deploy.ts
@@ -332,6 +332,11 @@ export const workerDeploy = defineRun({
   inputs: WorkerDeployInput,
   outputs: WorkerDeployOutput,
 
+  // The command key `resolve-config` reads — the receiver skips a repo without
+  // it (specs/adr/0007-cost-efficient-execution.md § Dispatch only work).
+  optIn: ({ input }) =>
+    input.command !== undefined ? [] : [commandKey(input.repo, input.checkLabel)],
+
   limits: {
     maxDurationSec: 1800,
   },

From 76ece772a66a49b61fb857dfa86296fe6c7b4856 Mon Sep 17 00:00:00 2001
From: debuggingfuture <hi@debuggingfuture.com>
Date: Thu, 22 Oct 2026 16:37:14 +0800
Subject: [PATCH 2/5] fix(dispatch): fail open when a run's optIn throws, and
 unit-test resolveOptIn

resolveOptIn takes the key list as a thunk, so a throwing optIn takes the
same log-and-dispatch branch as a rejected KV read instead of failing the
whole delivery for the sibling triggers.
---
 apps/dispatcher/src/opt-in.test.ts    | 73 +++++++++++++++++++++++++++
 apps/dispatcher/src/opt-in.ts         | 21 +++++---
 apps/dispatcher/src/routes/webhook.ts |  9 ++--
 3 files changed, 91 insertions(+), 12 deletions(-)
 create mode 100644 apps/dispatcher/src/opt-in.test.ts

diff --git a/apps/dispatcher/src/opt-in.test.ts b/apps/dispatcher/src/opt-in.test.ts
new file mode 100644
index 00000000..468755a5
--- /dev/null
+++ b/apps/dispatcher/src/opt-in.test.ts
@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveOptIn } from "./opt-in";
+import { makeFakeKv } from "./test-helpers";
+
+const KEYS = ["check.command:acme/widgets:docs", "check.command:acme/widgets"] as const;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("resolveOptIn", () => {
+  it("answers not-configured when no key is present", async () => {
+    const kv = makeFakeKv();
+    expect(await resolveOptIn({ configKv: kv.binding, runName: "check", keys: () => KEYS })).toBe(
+      "not-configured",
+    );
+  });
+
+  it("dispatches when any one key is present, the least specific included", async () => {
+    const kv = makeFakeKv();
+    kv.store.set("check.command:acme/widgets", "pnpm lint");
+    expect(await resolveOptIn({ configKv: kv.binding, runName: "check", keys: () => KEYS })).toBe(
+      "dispatch",
+    );
+  });
+
+  it("treats a present key as opted in whatever its value — the run body judges the value", async () => {
+    const kv = makeFakeKv();
+    kv.store.set("check.command:acme/widgets", "");
+    expect(await resolveOptIn({ configKv: kv.binding, runName: "check", keys: () => KEYS })).toBe(
+      "dispatch",
+    );
+  });
+
+  it("dispatches without a read when the inputs carry the command", async () => {
+    const get = vi.fn();
+    const configKv = { get } as unknown as KVNamespace;
+    expect(await resolveOptIn({ configKv, runName: "check", keys: () => [] })).toBe("dispatch");
+    expect(get).not.toHaveBeenCalled();
+  });
+
+  it("dispatches without computing keys on a deploy with no CONFIG_KV", async () => {
+    const keys = vi.fn(() => KEYS);
+    expect(await resolveOptIn({ configKv: undefined, runName: "check", keys })).toBe("dispatch");
+    expect(keys).not.toHaveBeenCalled();
+  });
+
+  it("fails open on a rejected read and logs the run and keys", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const configKv = {
+      get: async () => {
+        throw new Error("kv unavailable");
+      },
+    } as unknown as KVNamespace;
+    expect(await resolveOptIn({ configKv, runName: "check", keys: () => KEYS })).toBe("dispatch");
+    expect(String(error.mock.calls[0]?.[0])).toContain('run="check"');
+    expect(String(error.mock.calls[0]?.[0])).toContain("kv unavailable");
+  });
+
+  it("fails open when the run's optIn throws", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const kv = makeFakeKv();
+    const verdict = await resolveOptIn({
+      configKv: kv.binding,
+      runName: "check",
+      keys: () => {
+        throw new Error("input has no repo");
+      },
+    });
+    expect(verdict).toBe("dispatch");
+    expect(String(error.mock.calls[0]?.[0])).toContain("input has no repo");
+  });
+});
diff --git a/apps/dispatcher/src/opt-in.ts b/apps/dispatcher/src/opt-in.ts
index 2fd347d9..bcd7badc 100644
--- a/apps/dispatcher/src/opt-in.ts
+++ b/apps/dispatcher/src/opt-in.ts
@@ -6,8 +6,8 @@
 // configured the run costs no Workflow, check-run, admission slot or container
 // (specs/adr/0007-cost-efficient-execution.md § Dispatch only work).
 //
-// The read fails open. A KV error, or a deploy without CONFIG_KV, dispatches
-// exactly as the receiver did before the check existed: the run body still
+// The read fails open. A KV error, a throwing `optIn`, or a deploy without
+// CONFIG_KV dispatches as if the run declared no opt-in: the run body still
 // resolves its own command and no-ops when there is none, so a failed read
 // costs one wasted run, never a configured repo's verdict.
 
@@ -15,20 +15,25 @@
 export type OptInVerdict = "dispatch" | "not-configured";
 
 /**
- * Decide whether to dispatch a run whose `optIn` named `keys`.
+ * Decide whether to dispatch a run whose `optIn` names `keys`.
  *
- * `keys` empty (the inputs carry their own command) or no `configKv` →
+ * No `configKv`, or `keys` empty (the inputs carry their own command) →
  * `dispatch` with no read. Otherwise any present key → `dispatch`; none →
- * `not-configured`. A rejected read logs and answers `dispatch`.
+ * `not-configured`. `keys` is a thunk so a throwing `optIn` lands in the same
+ * fail-open branch as a rejected read: it logs and answers `dispatch`, and
+ * never fails the delivery for the sibling triggers.
  */
 export const resolveOptIn = async (args: {
   readonly configKv: KVNamespace | undefined;
   readonly runName: string;
-  readonly keys: readonly string[];
+  readonly keys: () => readonly string[];
 }): Promise<OptInVerdict> => {
-  const { configKv, runName, keys } = args;
-  if (keys.length === 0 || configKv === undefined) return "dispatch";
+  const { configKv, runName } = args;
+  if (configKv === undefined) return "dispatch";
+  let keys: readonly string[] = [];
   try {
+    keys = args.keys();
+    if (keys.length === 0) return "dispatch";
     const values = await Promise.all(keys.map((key) => configKv.get(key)));
     return values.some((value) => value !== null) ? "dispatch" : "not-configured";
   } catch (cause) {
diff --git a/apps/dispatcher/src/routes/webhook.ts b/apps/dispatcher/src/routes/webhook.ts
index a7204fe0..29182e81 100644
--- a/apps/dispatcher/src/routes/webhook.ts
+++ b/apps/dispatcher/src/routes/webhook.ts
@@ -294,13 +294,14 @@ export const handleGithubWebhook = async (request: Request, env: Env): Promise<R
     // Opt-in (when declared) — a repo with none of the run's CONFIG_KV keys
     // gets no Workflow, no check-run and no admission slot. Read before the
     // cooldown so an unconfigured repo never arms a window.
-    if (run.optIn !== undefined) {
-      const optIn = await resolveOptIn({
+    const optIn = run.optIn;
+    if (optIn !== undefined) {
+      const verdict = await resolveOptIn({
         configKv: env.CONFIG_KV,
         runName: run.name,
-        keys: run.optIn({ input: inputs }),
+        keys: () => optIn({ input: inputs }),
       });
-      if (optIn === "not-configured") {
+      if (verdict === "not-configured") {
         skipped.push({ run: run.name, reason: "not-configured" });
         continue;
       }

From d5c360d02f0576a8ab6658dd57b851721e93db56 Mon Sep 17 00:00:00 2001
From: debuggingfuture <hi@debuggingfuture.com>
Date: Thu, 22 Oct 2026 17:14:02 +0800
Subject: [PATCH 3/5] feat(supersede): count each supersession and label
 superseded executions

Each cancelled tree logs one supersede.cancelled line naming its group,
root and superseding execution, with the children, admitted slots and
open check-runs it ended. A cancelled member's run_supersessions row
turns 'cancelled' instead of being deleted, so the dashboard execution
list reads superseded_by and labels the row with what superseded it.
---
 apps/dispatcher/src/admission-parent.test.ts  |  2 +-
 apps/dispatcher/src/dashboard.test.ts         | 35 ++++++++++++
 apps/dispatcher/src/dashboard.ts              | 19 ++++++-
 apps/dispatcher/src/executions-read.ts        | 15 +++++-
 apps/dispatcher/src/http-app.ts               |  1 +
 apps/dispatcher/src/supersede.test.ts         | 50 ++++++++++++-----
 apps/dispatcher/src/supersede.ts              | 53 ++++++++++++++-----
 apps/dispatcher/src/workflow.ts               |  6 +--
 infra/migrations/0010_run_supersessions.sql   |  6 ++-
 packages/runtime-cf/src/index.ts              |  1 +
 packages/runtime-cf/src/run-supersede-d1.ts   | 36 +++++++++----
 .../src/run-supersede-d1.workers.test.ts      | 24 ++++++++-
 12 files changed, 204 insertions(+), 44 deletions(-)

diff --git a/apps/dispatcher/src/admission-parent.test.ts b/apps/dispatcher/src/admission-parent.test.ts
index d2f77914..a6d2e883 100644
--- a/apps/dispatcher/src/admission-parent.test.ts
+++ b/apps/dispatcher/src/admission-parent.test.ts
@@ -67,7 +67,7 @@ describe("leaveQueueForEndedParent", () => {
         { executionId: "part-a", parentExecutionId: "gate", parentStatus: "failure" },
         {
           stepDo: (name, body) => Effect.promise(async () => { events.push(`step:${name}`); return body(); }),
-          store: { cancel: (ids) => Effect.sync(() => { events.push(`cancel:${ids.join(",")}`); }) },
+          store: { cancel: (ids) => Effect.sync(() => { events.push(`cancel:${ids.join(",")}`); return { admittedSlots: 0 }; }) },
           concludeCancelled: (summary) => Effect.sync(() => { events.push(`conclude:${summary}`); }),
         },
       ),
diff --git a/apps/dispatcher/src/dashboard.test.ts b/apps/dispatcher/src/dashboard.test.ts
index 72f2ff18..d7973509 100644
--- a/apps/dispatcher/src/dashboard.test.ts
+++ b/apps/dispatcher/src/dashboard.test.ts
@@ -27,6 +27,7 @@ const baseRow = (over: Partial<DashboardRow> = {}): DashboardRow => ({
   logsUrl: null,
   demosUrl: null,
   selfHealPrUrl: null,
+  supersededBy: null,
   ...over,
 });
 
@@ -114,6 +115,24 @@ describe("renderDashboard", () => {
     expect(html).not.toContain("badge selfheal");
   });
 
+  it("labels a cancelled execution with the execution that superseded it", () => {
+    const html = renderDashboard(data([baseRow({ status: "cancelled", supersededBy: "gate-newer" })]));
+    expect(html).toContain('superseded by <span class="sha">gate-newer</span>');
+  });
+
+  it("labels a cancelled execution a pull-request close superseded", () => {
+    const html = renderDashboard(
+      data([baseRow({ status: "cancelled", supersededBy: "pr-closed:1000:contextful-gate:o/r#7" })]),
+    );
+    expect(html).toContain("pull request closed");
+    expect(html).not.toContain("superseded by");
+  });
+
+  it("labels no execution that is not cancelled", () => {
+    const html = renderDashboard(data([baseRow({ status: "running", supersededBy: "gate-newer" })]));
+    expect(html).not.toContain("superseded by");
+  });
+
   it("escapes HTML in execution fields", () => {
     const html = renderDashboard(data([baseRow({ repo: "<script>" })]));
     expect(html).not.toContain("<script>");
@@ -448,6 +467,22 @@ describe("GET /v1/dashboard.json — SPA feed", () => {
     expect(body.rows[0]?.selfHealPrUrl).toBeNull();
   });
 
+  it("carries the superseding execution of a cancelled row, null otherwise", async () => {
+    const { env } = fixture([
+      execRow({ id: "old", status: "cancelled", superseded_by: "new", started_at: 1000 }),
+      execRow({ id: "new", status: "running", started_at: 2000 }),
+    ]);
+    const res = await handleRequest(
+      new Request("https://dispatcher.example.com/v1/dashboard.json"),
+      env,
+    );
+    const body = (await res.json()) as { rows: { id: string; supersededBy: string | null }[] };
+    expect(body.rows.map((row) => [row.id, row.supersededBy])).toEqual([
+      ["new", null],
+      ["old", "new"],
+    ]);
+  });
+
   it("sets selfHealPrUrl for a self-heal-pr run that opened a fix PR (prStaged)", async () => {
     const { env } = fixture([
       execRow({
diff --git a/apps/dispatcher/src/dashboard.ts b/apps/dispatcher/src/dashboard.ts
index 0648ca79..22efaa5c 100644
--- a/apps/dispatcher/src/dashboard.ts
+++ b/apps/dispatcher/src/dashboard.ts
@@ -11,6 +11,8 @@
 // I/O, so it stays trivially testable (dashboard.test.ts). The route that feeds
 // it (query-param parsing, the D1 reads, the Access gate) is wired in http-app.ts.
 
+import { isCloseMarker } from "./pr-close";
+
 /** One execution row, pre-resolved with its tokened viewer links. */
 export interface DashboardRow {
   readonly id: string;
@@ -38,6 +40,12 @@ export interface DashboardRow {
    * — a non-null value means flare-dispatch drove a PR to fix a bug here.
    */
   readonly selfHealPrUrl: string | null;
+  /**
+   * The execution that superseded this one, or a pull-request close marker,
+   * from `run_supersessions.superseded_by`; `null` when nothing superseded it.
+   * A `cancelled` row with a value is labelled with it.
+   */
+  readonly supersededBy: string | null;
 }
 
 export interface DashboardData {
@@ -241,6 +249,15 @@ const STYLE = `
   footer a { margin-right: 1rem; }
 `;
 
+/** "superseded by <id>" (or "pull request closed") under a cancelled row's badge. */
+const supersededLabel = (row: DashboardRow): string => {
+  if (row.status !== "cancelled" || row.supersededBy === null) return "";
+  const text = isCloseMarker(row.supersededBy)
+    ? "pull request closed"
+    : `superseded by <span class="sha">${esc(row.supersededBy)}</span>`;
+  return ` <span class="when superseded">${text}</span>`;
+};
+
 const renderRow = (row: DashboardRow, nowMs: number): string => {
   const links: string[] = [];
   if (row.logsUrl !== null) {
@@ -264,7 +281,7 @@ const renderRow = (row: DashboardRow, nowMs: number): string => {
       ? ` <a class="badge selfheal" href="${esc(row.selfHealPrUrl)}" title="View flare-dispatch self-heal fix PRs">🩹 self-heal</a>`
       : "";
   return `<tr${clickable ? ' class="rowlink"' : ""}>
-    <td><span class="badge ${badgeClass(row.status)}">${esc(row.status)}</span></td>
+    <td><span class="badge ${badgeClass(row.status)}">${esc(row.status)}</span>${supersededLabel(row)}</td>
     <td class="run">${runCell}${selfHealPill}</td>
     <td><span class="repo">${esc(row.repo)}</span> <span class="sha">${esc(shortSha(row.sha))}</span></td>
     <td class="when">${esc(relativeTime(row.startedAt, nowMs))}</td>
diff --git a/apps/dispatcher/src/executions-read.ts b/apps/dispatcher/src/executions-read.ts
index 2a90b794..0eeec8ec 100644
--- a/apps/dispatcher/src/executions-read.ts
+++ b/apps/dispatcher/src/executions-read.ts
@@ -38,6 +38,12 @@ export type ExecutionRow = {
   readonly output_tokens: number | null;
   readonly vcpu_seconds: number | null;
   readonly model: string | null;
+  // --- Supersession (infra/migrations/0010; `listExecutions` only) -----------
+  /**
+   * The execution (or pull-request close marker) that superseded this one,
+   * from its `run_supersessions` row; NULL when nothing did or the row aged out.
+   */
+  readonly superseded_by?: string | null;
 };
 
 /** One row of the `steps` table. */
@@ -79,7 +85,8 @@ export type ListFilters = {
 
 /**
  * List executions newest-first, with optional `run`/`repo`/`status` filters and
- * a `(started_at, id)` keyset cursor. Returns at most `limit` rows.
+ * a `(started_at, id)` keyset cursor, each with the `superseded_by` of its
+ * `run_supersessions` row. Returns at most `limit` rows.
  */
 export const listExecutions = async (
   db: D1Database,
@@ -111,7 +118,11 @@ export const listExecutions = async (
     }
   }
   const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
-  const sql = `SELECT * FROM executions ${whereSql}
+  // The filter columns exist only on `executions`, so they stay unqualified.
+  const sql = `SELECT executions.*, run_supersessions.superseded_by
+                 FROM executions
+                 LEFT JOIN run_supersessions ON run_supersessions.execution_id = executions.id
+               ${whereSql}
                ORDER BY started_at DESC
                LIMIT ?`;
   binds.push(filters.limit);
diff --git a/apps/dispatcher/src/http-app.ts b/apps/dispatcher/src/http-app.ts
index bdf32d75..c0a0ca77 100644
--- a/apps/dispatcher/src/http-app.ts
+++ b/apps/dispatcher/src/http-app.ts
@@ -322,6 +322,7 @@ const dashboardData = Effect.gen(function* () {
         logsUrl: Option.getOrNull(logsUrl),
         demosUrl: Option.getOrNull(demosUrl),
         selfHealPrUrl,
+        supersededBy: row.superseded_by ?? null,
       } satisfies DashboardRow;
     }),
   );
diff --git a/apps/dispatcher/src/supersede.test.ts b/apps/dispatcher/src/supersede.test.ts
index 65c40ff0..638f228c 100644
--- a/apps/dispatcher/src/supersede.test.ts
+++ b/apps/dispatcher/src/supersede.test.ts
@@ -1,7 +1,7 @@
 import { Effect, Exit } from "effect";
 import type { ChecksService } from "@fractalboxdev/flare-dispatch-core";
 import type { SupersededRow } from "@fractalboxdev/flare-dispatch-runtime-cf";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   cancelSupersededTree,
   enterSupersession,
@@ -31,7 +31,7 @@ const fixture = (tree: readonly SupersededRow[], statuses: Record<string, Status
       markCancelled: (id) => Effect.sync(() => { events.push(`mark:${id}`); }),
       status: () => Effect.succeed("cancelled"),
       openTree: (id) => Effect.sync(() => { events.push(`tree:${id}`); return tree; }),
-      cancel: (ids) => Effect.sync(() => { events.push(`cancel:${ids.join(",")}`); }),
+      cancel: (ids) => Effect.sync(() => { events.push(`cancel:${ids.join(",")}`); return { admittedSlots: 0 }; }),
     },
     terminate: async (id) => {
       events.push(`terminate:${id}`);
@@ -49,7 +49,7 @@ describe("cancelSupersededTree", () => {
   it("marks the root before reading its tree, then ends and frees every open row", async () => {
     const tree = [row("old-gate", { status: "cancelled" }), row("part-a"), row("part-b", { status: "queued" })];
     const { ports, events } = fixture(tree);
-    const ids = await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", ports));
+    const ids = await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", "g", ports));
     expect(ids).toEqual(["old-gate", "part-a", "part-b"]);
     expect(events.slice(0, 4)).toEqual(["mark:old-gate", "tree:old-gate", "terminate:old-gate", "tree:old-gate"]);
     expect(events).toContain("terminate:part-a");
@@ -61,7 +61,7 @@ describe("cancelSupersededTree", () => {
   it("concludes every open check-run of the tree cancelled, naming the newer execution", async () => {
     const tree = [row("old-gate"), row("part-a"), row("part-done"), row("part-noop", { checkRunId: "noop" })];
     const { ports, updates } = fixture(tree, { "cr-part-done": "completed" });
-    await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", ports));
+    await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", "g", ports));
     expect(updates.map((u) => [u.checkRunId, u.conclusion])).toEqual([
       ["cr-old-gate", "cancelled"],
       ["cr-part-a", "cancelled"],
@@ -70,9 +70,35 @@ describe("cancelSupersededTree", () => {
     expect(supersededSummary("new-gate")).toContain("`new-gate`");
   });
 
+  it("logs one supersede.cancelled line counting the children, admitted slots and check-runs it ended", async () => {
+    const tree = [row("old-gate"), row("part-a"), row("part-done"), row("part-noop", { checkRunId: "noop" })];
+    const { ports } = fixture(tree, { "cr-part-done": "completed" });
+    const counted: SupersedePorts = { ...ports, store: { ...ports.store, cancel: () => Effect.succeed({ admittedSlots: 2 }) } };
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    try {
+      await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", "contextful-gate:o/r#7", counted));
+      const lines = log.mock.calls
+        .map(([line]) => (typeof line === "string" && line.startsWith("{") ? JSON.parse(line) : undefined))
+        .filter((line) => line?.event === "supersede.cancelled");
+      expect(lines).toEqual([
+        {
+          event: "supersede.cancelled",
+          group: "contextful-gate:o/r#7",
+          root: "old-gate",
+          supersededBy: "new-gate",
+          children: 3,
+          admittedSlots: 2,
+          checkRuns: 2,
+        },
+      ]);
+    } finally {
+      log.mockRestore();
+    }
+  });
+
   it("retries cleanup for a root already marked cancelled", async () => {
     const { ports, events } = fixture([row("gone")]);
-    const exit = await Effect.runPromiseExit(cancelSupersededTree("gone", "new-gate", ports));
+    const exit = await Effect.runPromiseExit(cancelSupersededTree("gone", "new-gate", "g", ports));
     expect(Exit.isSuccess(exit)).toBe(true);
     expect(events).toContain("cancel:gone");
   });
@@ -80,13 +106,13 @@ describe("cancelSupersededTree", () => {
   it("fails when the D1 cancel fails, so the step retries the whole sequence", async () => {
     const { ports } = fixture([row("old-gate")]);
     const failing: SupersedePorts = { ...ports, store: { ...ports.store, cancel: () => Effect.fail(new Error("D1 down")) } };
-    expect(Exit.isFailure(await Effect.runPromiseExit(cancelSupersededTree("old-gate", "new-gate", failing)))).toBe(true);
+    expect(Exit.isFailure(await Effect.runPromiseExit(cancelSupersededTree("old-gate", "new-gate", "g", failing)))).toBe(true);
   });
 
   it("leaves rows and check-runs untouched when termination fails", async () => {
     const { ports, events, updates } = fixture([row("old-gate"), row("part-a")]);
     const failing: SupersedePorts = { ...ports, terminate: async () => { throw new Error("unavailable"); } };
-    expect(Exit.isFailure(await Effect.runPromiseExit(cancelSupersededTree("old-gate", "new-gate", failing)))).toBe(true);
+    expect(Exit.isFailure(await Effect.runPromiseExit(cancelSupersededTree("old-gate", "new-gate", "g", failing)))).toBe(true);
     expect(events).not.toContain("cancel:old-gate,part-a");
     expect(updates).toEqual([]);
   });
@@ -94,18 +120,18 @@ describe("cancelSupersededTree", () => {
   it("does not cancel descendants of a root that already finished", async () => {
     const { ports, events } = fixture([row("old-gate", { status: "success" }), row("part-a")]);
     const finished: SupersedePorts = { ...ports, store: { ...ports.store, status: () => Effect.succeed("success") } };
-    expect(await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", finished))).toEqual([]);
+    expect(await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", "g", finished))).toEqual([]);
     expect(events).toEqual(["mark:old-gate"]);
   });
 
   it("keeps the opener alive until its check id is persisted, then cancels it on retry", async () => {
     const tree = [row("old-gate", { checkRunId: null })];
     const { ports, events, updates } = fixture(tree);
-    expect(Exit.isFailure(await Effect.runPromiseExit(cancelSupersededTree("old-gate", "new-gate", ports)))).toBe(true);
+    expect(Exit.isFailure(await Effect.runPromiseExit(cancelSupersededTree("old-gate", "new-gate", "g", ports)))).toBe(true);
     expect(events).not.toContain("terminate:old-gate");
     expect(updates).toEqual([]);
     tree[0] = row("old-gate", { status: "cancelled" });
-    await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", ports));
+    await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", "g", ports));
     expect(updates[0]?.conclusion).toBe("cancelled");
   });
 
@@ -116,7 +142,7 @@ describe("cancelSupersededTree", () => {
       events.push(`terminate:${id}`);
       if (id === "part-a") tree.push(row("grandchild"));
     } };
-    expect(await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", spawning))).toEqual(["old-gate", "part-a", "grandchild"]);
+    expect(await Effect.runPromise(cancelSupersededTree("old-gate", "new-gate", "g", spawning))).toEqual(["old-gate", "part-a", "grandchild"]);
     expect(events.indexOf("mark:grandchild")).toBeLessThan(events.indexOf("terminate:grandchild"));
     expect(events).toContain("cancel:old-gate,part-a,grandchild");
   });
@@ -146,7 +172,7 @@ const prelude = (opts: {
       }),
     store: {
       status: (id) => Effect.sync(() => (id === "parent" ? opts.parentStatus : undefined)),
-      cancel: (ids) => Effect.sync(() => { events.push(`cancel:${ids.join(",")}`); }),
+      cancel: (ids) => Effect.sync(() => { events.push(`cancel:${ids.join(",")}`); return { admittedSlots: 0 }; }),
       register: (id, group, o) =>
         Effect.sync(() => {
           registered.push({ id, group, ...o });
diff --git a/apps/dispatcher/src/supersede.ts b/apps/dispatcher/src/supersede.ts
index a92a67b5..48435933 100644
--- a/apps/dispatcher/src/supersede.ts
+++ b/apps/dispatcher/src/supersede.ts
@@ -14,7 +14,9 @@
 //   4. terminate each child's instance and tear down each container;
 //   5. end those rows 'cancelled' and delete their admission, serial-queue
 //      and supersession rows — the freed slots admit the next waiter at once;
-//   6. conclude every still-open check-run of the tree `cancelled`.
+//   6. conclude every still-open check-run of the tree `cancelled`;
+//   7. log one `supersede.cancelled` line naming the group, the root and the
+//      counts of children, admitted slots and check-runs it ended.
 //
 // D1 writes and instance termination fail the step so it retries the
 // idempotent sequence. Container and check-run calls are best-effort.
@@ -65,13 +67,28 @@ const requireCheckRunId = (row: SupersededRow | undefined): Effect.Effect<void,
     ? Effect.void
     : Effect.fail(new Error("supersede: waiting for check-run id persistence"));
 
+/** The structured `supersede.cancelled` line: one per superseded tree it ended. */
+export type SupersedeCancelledLine = {
+  readonly event: "supersede.cancelled";
+  readonly group: string;
+  readonly root: string;
+  readonly supersededBy: string;
+  readonly children: number;
+  readonly admittedSlots: number;
+  readonly checkRuns: number;
+};
+
+const logCancelled = (line: SupersedeCancelledLine): Effect.Effect<void> =>
+  Effect.sync(() => console.log(JSON.stringify(line)));
+
 /**
- * Cancel `rootId` and its children on behalf of `supersededBy`. Resolves to the
- * ids whose rows it ended.
+ * Cancel `rootId` and its children on behalf of `supersededBy`, a member of
+ * `group`. Resolves to the ids whose rows it ended.
  */
 export const cancelSupersededTree = (
   rootId: string,
   supersededBy: string,
+  group: string,
   ports: SupersedePorts,
 ): Effect.Effect<readonly string[], Error> =>
   Effect.gen(function* () {
@@ -108,28 +125,40 @@ export const cancelSupersededTree = (
       { concurrency: 4, discard: true },
     );
     const ids = tree.map((row) => row.id);
-    yield* ports.store.cancel(ids);
-    yield* Effect.forEach(
+    const { admittedSlots } = yield* ports.store.cancel(ids);
+    const concluded = yield* Effect.forEach(
       tree,
       (row) =>
         Effect.gen(function* () {
           const checkRunId = row.checkRunId;
-          if (checkRunId === null || checkRunId === NOOP_CHECK_RUN_ID) return;
+          if (checkRunId === null || checkRunId === NOOP_CHECK_RUN_ID) return false;
           const state = yield* ports.checks.status({ repo: row.repo, checkRunId });
-          if (state !== "open") return;
+          if (state !== "open") return false;
           yield* ports.checks.update({
             repo: row.repo,
             checkRunId,
             conclusion: "cancelled",
             output: { title: supersededTitle(supersededBy), summary: supersededSummary(supersededBy) },
           });
+          return true;
         }).pipe(
           Effect.catchAllCause((cause) =>
-            Effect.logWarning(`supersede: check-run of ${row.id} not concluded — ${cause}`),
+            Effect.logWarning(`supersede: check-run of ${row.id} not concluded — ${cause}`).pipe(
+              Effect.as(false),
+            ),
           ),
         ),
-      { concurrency: 4, discard: true },
+      { concurrency: 4 },
     );
+    yield* logCancelled({
+      event: "supersede.cancelled",
+      group,
+      root: rootId,
+      supersededBy,
+      children: tree.filter((row) => row.id !== rootId).length,
+      admittedSlots,
+      checkRuns: concluded.filter(Boolean).length,
+    });
     return ids;
   });
 
@@ -144,8 +173,8 @@ export type SupersessionPorts = {
   /** A durable checkpoint (RunWorkflow's `step.do`). */
   readonly stepDo: <T>(name: string, body: () => Promise<T>) => Effect.Effect<T>;
   readonly store: Pick<RunSupersedeStore, "status" | "cancel" | "register">;
-  /** Cancel one superseded tree (`cancelSupersededTree` bound to live ports). */
-  readonly cancelTree: (olderId: string) => Effect.Effect<unknown, Error>;
+  /** Cancel one superseded tree of `group` (`cancelSupersededTree` bound to live ports). */
+  readonly cancelTree: (olderId: string, group: string) => Effect.Effect<unknown, Error>;
   /** Conclude this execution's own check-run `cancelled` with `summary`. */
   readonly concludeCancelled: (summary: string) => Effect.Effect<void>;
 };
@@ -197,7 +226,7 @@ export const enterSupersession = (
     if (registration.supersededBy !== null) return yield* standDown(registration.supersededBy);
     for (const [index, olderId] of registration.superseded.entries()) {
       yield* ports.stepDo(`supersede-cancel-${index}`, () =>
-        Effect.runPromise(ports.cancelTree(olderId)).then(() => true),
+        Effect.runPromise(ports.cancelTree(olderId, spec.group)).then(() => true),
       );
     }
     return "proceed" as const;
diff --git a/apps/dispatcher/src/workflow.ts b/apps/dispatcher/src/workflow.ts
index f4fd7c81..b69f0c49 100644
--- a/apps/dispatcher/src/workflow.ts
+++ b/apps/dispatcher/src/workflow.ts
@@ -365,7 +365,7 @@ export class RunWorkflow extends WorkflowEntrypoint<Env> {
             stepDo,
             store,
             cancelTree: (rootId, markerId) =>
-              cancelSupersededTree(rootId, markerId, liveSupersedePorts(env, store, checks)),
+              cancelSupersededTree(rootId, markerId, close.group, liveSupersedePorts(env, store, checks)),
           });
           yield* Effect.logInfo(
             `pull request closed: ${close.group} — cancelled ${cancelled.length} execution(s)${cancelled.length > 0 ? `: ${cancelled.join(", ")}` : ""}`,
@@ -815,8 +815,8 @@ export class RunWorkflow extends WorkflowEntrypoint<Env> {
         {
           stepDo,
           store: supersessions,
-          cancelTree: (olderId) =>
-            cancelSupersededTree(olderId, payload.executionId, liveSupersedePorts(env, supersessions, checks)),
+          cancelTree: (olderId, group) =>
+            cancelSupersededTree(olderId, payload.executionId, group, liveSupersedePorts(env, supersessions, checks)),
           concludeCancelled: (summary) =>
             checks.update({
               repo: payload.github.repo,
diff --git a/infra/migrations/0010_run_supersessions.sql b/infra/migrations/0010_run_supersessions.sql
index 88fcc541..9421afd0 100644
--- a/infra/migrations/0010_run_supersessions.sql
+++ b/infra/migrations/0010_run_supersessions.sql
@@ -4,13 +4,15 @@
 -- one group per pull request). A higher-ranked execution of a group marks every
 -- lower-ranked 'live' row 'superseded', naming itself in `superseded_by`, then
 -- cancels each of those executions with its children; a lower-ranked arrival
--- marks itself. A row is deleted when its execution finishes or is cancelled. See @fractalboxdev/flare-dispatch-runtime-cf
+-- marks itself. A live row is deleted when its execution finishes; a cancelled
+-- execution's row turns 'cancelled' and keeps `superseded_by` until the GC age.
+-- See @fractalboxdev/flare-dispatch-runtime-cf
 -- run-supersede-d1.ts.
 
 CREATE TABLE IF NOT EXISTS run_supersessions (
   execution_id TEXT PRIMARY KEY,
   group_key TEXT NOT NULL,          -- SupersedeSpec.group
-  state TEXT NOT NULL,              -- 'live' | 'superseded'
+  state TEXT NOT NULL,              -- 'live' | 'superseded' | 'cancelled'
   superseded_by TEXT,               -- execution id of the higher-ranked member that superseded this one
   revision_rank INTEGER NOT NULL,   -- SupersedeSpec.order, else registered_at; revision order within a group
   registered_at INTEGER NOT NULL    -- ms epoch; breaks a rank tie
diff --git a/packages/runtime-cf/src/index.ts b/packages/runtime-cf/src/index.ts
index a2f91b29..82460ab8 100644
--- a/packages/runtime-cf/src/index.ts
+++ b/packages/runtime-cf/src/index.ts
@@ -87,6 +87,7 @@ export {
 export {
   makeRunSupersedeD1,
   TERMINAL_EXECUTION_STATUSES,
+  type CancelOutcome,
   type RunSupersedeStore,
   type SupersededRow,
 } from "./run-supersede-d1";
diff --git a/packages/runtime-cf/src/run-supersede-d1.ts b/packages/runtime-cf/src/run-supersede-d1.ts
index ae865bfd..18ecb5b3 100644
--- a/packages/runtime-cf/src/run-supersede-d1.ts
+++ b/packages/runtime-cf/src/run-supersede-d1.ts
@@ -14,7 +14,9 @@
 // touches a running execution. Supersession is the other policy: the older
 // member is cancelled wherever it stands — queued in admission, running, or
 // joined on children. `cancel` is the D1 half of that: it ends the rows, frees
-// their admission and serial slots, and drops their supersession rows. The
+// their admission and serial slots, and marks their supersession rows
+// 'cancelled', which keeps `superseded_by` readable for the dashboard until the
+// GC age and takes them out of every later registration. The
 // Workflow instances, containers and check-runs are the dispatcher's half
 // (apps/dispatcher/src/supersede.ts).
 //
@@ -55,6 +57,12 @@ export type SupersedeRegistration = {
   readonly supersededBy: string | undefined;
 };
 
+/** What one `cancel` freed. */
+export type CancelOutcome = {
+  /** `run_admissions` rows in state 'admitted' it deleted. */
+  readonly admittedSlots: number;
+};
+
 export interface RunSupersedeStore {
   /**
    * Join `group` at `rank` (default: now). With `supersedeOlder`, mark every
@@ -77,9 +85,11 @@ export interface RunSupersedeStore {
   readonly row: (executionId: string) => Effect.Effect<{ readonly status: string; readonly run: string } | undefined, Error>;
   /**
    * End every row in `ids` as 'cancelled' (rows already ended keep their
-   * status), and delete their admission, serial-queue and supersession rows.
+   * status), delete their admission and serial-queue rows, and mark their
+   * supersession rows 'cancelled'. Resolves to the number of admitted slots
+   * it freed.
    */
-  readonly cancel: (ids: readonly string[]) => Effect.Effect<void, Error>;
+  readonly cancel: (ids: readonly string[]) => Effect.Effect<CancelOutcome, Error>;
   /** Leave the group (DELETE own row) and collect rows past the GC age. */
   readonly release: (executionId: string) => Effect.Effect<void, Error>;
 }
@@ -146,7 +156,7 @@ export const makeRunSupersedeD1 = (
         db
           .prepare(
             `SELECT superseded_by AS supersededBy FROM run_supersessions
-              WHERE execution_id = ? AND state = 'superseded'`,
+              WHERE execution_id = ? AND state IN ('superseded', 'cancelled')`,
           )
           .bind(executionId)
           .first<{ supersededBy: string | null }>(),
@@ -203,12 +213,18 @@ export const makeRunSupersedeD1 = (
         .first<{ status: string; run: string }>(),
     ).pipe(Effect.map((found) => (found === null ? undefined : { status: found.status, run: found.run })));
 
-  const cancel = (ids: readonly string[]): Effect.Effect<void, Error> => {
-    if (ids.length === 0) return Effect.void;
+  const cancel = (ids: readonly string[]): Effect.Effect<CancelOutcome, Error> => {
+    if (ids.length === 0) return Effect.succeed({ admittedSlots: 0 });
     const marks = ids.map(() => "?").join(", ");
     const ts = now();
     return d1(() =>
-      db.batch([
+      db.batch<{ n?: number }>([
+        db
+          .prepare(
+            `SELECT COUNT(*) AS n FROM run_admissions
+              WHERE execution_id IN (${marks}) AND state = 'admitted'`,
+          )
+          .bind(...ids),
         db
           .prepare(
             `UPDATE executions SET status = 'cancelled', completed_at = ?
@@ -217,9 +233,11 @@ export const makeRunSupersedeD1 = (
           .bind(ts, ...ids),
         db.prepare(`DELETE FROM run_admissions WHERE execution_id IN (${marks})`).bind(...ids),
         db.prepare(`DELETE FROM serial_queue WHERE execution_id IN (${marks})`).bind(...ids),
-        db.prepare(`DELETE FROM run_supersessions WHERE execution_id IN (${marks})`).bind(...ids),
+        db
+          .prepare(`UPDATE run_supersessions SET state = 'cancelled' WHERE execution_id IN (${marks})`)
+          .bind(...ids),
       ]),
-    ).pipe(Effect.asVoid);
+    ).pipe(Effect.map(([counted]) => ({ admittedSlots: counted?.results[0]?.n ?? 0 })));
   };
 
   const release = (executionId: string): Effect.Effect<void, Error> =>
diff --git a/packages/runtime-cf/src/run-supersede-d1.workers.test.ts b/packages/runtime-cf/src/run-supersede-d1.workers.test.ts
index ccb57637..c4c06880 100644
--- a/packages/runtime-cf/src/run-supersede-d1.workers.test.ts
+++ b/packages/runtime-cf/src/run-supersede-d1.workers.test.ts
@@ -67,6 +67,24 @@ describe("makeRunSupersedeD1: supersession against real D1", () => {
     expect(await executionStatus("exec-c")).toBe("running");
   });
 
+  it("keeps a cancelled member's superseded_by and leaves it out of later registrations", async () => {
+    await insertExecution("exec-a", "running");
+    await superseded("exec-a", G, { supersedeOlder: true });
+    clock += 1;
+    expect(await superseded("exec-b", G, { supersedeOlder: true })).toEqual(["exec-a"]);
+    await run(store.cancel(["exec-a"]));
+    const kept = await bindings.db
+      .prepare(`SELECT state, superseded_by AS by FROM run_supersessions WHERE execution_id = 'exec-a'`)
+      .first<{ state: string; by: string }>();
+    expect(kept).toEqual({ state: "cancelled", by: "exec-b" });
+    clock += 1;
+    expect(await superseded("exec-c", G, { supersedeOlder: true })).toEqual(["exec-b"]);
+    expect(await run(store.register("exec-a", G, { supersedeOlder: true }))).toEqual({
+      superseded: [],
+      supersededBy: "exec-b",
+    });
+  });
+
   it("returns the same superseded set when the registration re-runs", async () => {
     await superseded("exec-a", G, { supersedeOlder: true });
     clock += 1;
@@ -167,7 +185,8 @@ describe("makeRunSupersedeD1: supersession against real D1", () => {
     await insertExecution("child-done", "success", "parent", 13);
     await insertExecution("grandchild-running", "running", "child-running", 14);
     const admissions = makeRunAdmissionD1(bindings.db, () => clock);
-    await run(admissions.enqueue("child-running", "lean", "parent"));
+    const { enqueuedAt } = await run(admissions.enqueue("child-running", "lean", "parent"));
+    await run(admissions.attempt("child-running", "lean", enqueuedAt));
     await run(admissions.enqueue("grandchild-running", "lean", "child-running"));
 
     await run(store.markCancelled("parent"));
@@ -180,7 +199,8 @@ describe("makeRunSupersedeD1: supersession against real D1", () => {
       ["parent", "11"],
     ]);
 
-    await run(store.cancel(tree.map((row) => row.id)));
+    // One admitted slot (child-running); grandchild-running is still queued.
+    expect(await run(store.cancel(tree.map((row) => row.id)))).toEqual({ admittedSlots: 1 });
     expect(await executionStatus("child-running")).toBe("cancelled");
     expect(await executionStatus("grandchild-running")).toBe("cancelled");
     expect(await executionStatus("child-done")).toBe("success");

From 77a66a971c15ca7508e7bf986b9639182d9c218e Mon Sep 17 00:00:00 2001
From: debuggingfuture <hi@debuggingfuture.com>
Date: Thu, 22 Oct 2026 17:17:30 +0800
Subject: [PATCH 4/5] feat(contextful-gate): split light and heavy parts across
 pull requests and default-branch pushes

gate.lightLabels:<repo> names the light parts. A pull-request gate runs
only those; a push to the default branch runs the heavy parts once per
head, serialized per repo, and is dispatched only for a repo that lists
light labels. Unset, a pull-request gate runs every part and a push
dispatches nothing.
---
 runs/contextful-gate.test.ts | 125 +++++++++++++++++++++++++++++++++++
 runs/contextful-gate.ts      | 125 +++++++++++++++++++++++++++++++++--
 2 files changed, 243 insertions(+), 7 deletions(-)

diff --git a/runs/contextful-gate.test.ts b/runs/contextful-gate.test.ts
index a2ff3801..7f0b9ae7 100644
--- a/runs/contextful-gate.test.ts
+++ b/runs/contextful-gate.test.ts
@@ -14,14 +14,17 @@ import {
 import { check } from "./check";
 import {
   contextfulGate,
+  lightLabelsKey,
   mergeStages,
   NOT_AFFECTED_SUMMARY,
   parseAffected,
+  parseLightLabels,
   parseStages,
   parseWindow,
   planStages,
   prLiveness,
   stageCommand,
+  tierParts,
   unrunSummary,
   WINDOW_DEFAULT,
   WINDOW_MAX,
@@ -267,6 +270,7 @@ describe("contextful-gate", () => {
         ),
       );
       expect(handles.executions.steps.map((entry) => entry.name).filter((name) => !name.startsWith("checkout") && !name.startsWith("discover") && name !== "release-discovery-container")).toEqual([
+        "resolve-tiers",
         "prebuild-ci-binary",
         "resolve-window",
         "spawn-parts-0",
@@ -944,4 +948,125 @@ describe("contextful-gate", () => {
       }).pipe(Effect.provide(layer));
     });
   });
+
+  describe("two-tier gate", () => {
+    const LIGHT_KEY = "gate.lightLabels:fractalboxdev/contextful";
+    const parts = ["pins", "workspace.compile", "formal"];
+    const program = {
+      [DISCOVER_HEAD]: { stdout: `${parts.join("\n")}\n`, exitCode: 0 },
+      [DISCOVER]: { stdout: `${parts.join("\n")}\n`, exitCode: 0 },
+    };
+    const heavyInput = { ...input, tier: "heavy", branch: "main" } as const;
+    const spawnedLabels = (handles: { childRuns: { spawned: readonly { input: unknown }[] } }) =>
+      handles.childRuns.spawned.map((spawn) => (spawn.input as { checkLabel: string }).checkLabel);
+
+    it("parses a comma or JSON list, and reads unset, blank, empty or malformed as no light labels", () => {
+      expect(lightLabelsKey("o/r")).toBe("gate.lightLabels:o/r");
+      expect(parseLightLabels(undefined)).toBeUndefined();
+      expect(parseLightLabels("  ")).toBeUndefined();
+      expect(parseLightLabels(",, ,")).toBeUndefined();
+      expect(parseLightLabels("[]")).toBeUndefined();
+      expect(parseLightLabels("[pins")).toBeUndefined();
+      expect(parseLightLabels('["pins", 3]')).toBeUndefined();
+      expect(parseLightLabels('{"pins": true}')).toBeUndefined();
+      expect(parseLightLabels(" pins , formal,pins ")).toEqual(["pins", "formal"]);
+      expect(parseLightLabels('["pins", " formal "]')).toEqual(["pins", "formal"]);
+    });
+
+    it("splits the plan into light parts for pull requests and heavy parts for the default branch", () => {
+      expect(tierParts(parts, ["formal", "pins"], "pull-request")).toEqual(["pins", "formal"]);
+      expect(tierParts(parts, ["formal", "pins"], "heavy")).toEqual(["workspace.compile"]);
+      expect(tierParts(parts, ["absent"], "pull-request")).toEqual([]);
+      expect(tierParts(parts, ["absent"], "heavy")).toEqual(parts);
+    });
+
+    it("unset: a pull-request gate runs every part and the heavy tier none", () => {
+      expect(tierParts(parts, undefined, "pull-request")).toBe(parts);
+      expect(tierParts(parts, undefined, "heavy")).toEqual([]);
+    });
+
+    it.effect("unset: a pull-request gate spawns every part", () => {
+      const { layer, handles } = makeCFRuntimeTest({
+        sandboxProgram: program,
+        childRuns: { pollFn: (ids) => ids.map((executionId) => ({ executionId, status: "success" })) },
+      });
+      return Effect.gen(function* () {
+        expect(yield* contextfulGate.run(input)).toEqual({ stages: 3, failed: [], notAffected: [] });
+        expect(spawnedLabels(handles)).toEqual(parts);
+      }).pipe(Effect.provide(layer));
+    });
+
+    it.effect("a pull-request gate spawns only the light parts and posts no check for the heavy ones", () => {
+      const { layer, handles } = makeCFRuntimeTest({
+        sandboxProgram: program,
+        config: { [LIGHT_KEY]: "pins,formal" },
+        childRuns: { pollFn: (ids) => ids.map((executionId) => ({ executionId, status: "success" })) },
+      });
+      return Effect.gen(function* () {
+        expect(yield* contextfulGate.run(input)).toEqual({ stages: 3, failed: [], notAffected: [] });
+        expect(spawnedLabels(handles)).toEqual(["pins", "formal"]);
+        expect(handles.checks.creates).toEqual([]);
+      }).pipe(Effect.provide(layer));
+    });
+
+    it.effect("a default-branch push spawns only the heavy parts without reading pull-request liveness", () => {
+      const { layer, handles } = makeCFRuntimeTest({
+        sandboxProgram: program,
+        config: { [LIGHT_KEY]: '["pins"]' },
+        childRuns: { pollFn: (ids) => ids.map((executionId) => ({ executionId, status: "success" })) },
+      });
+      return Effect.gen(function* () {
+        expect(yield* contextfulGate.run(heavyInput)).toEqual({ stages: 3, failed: [], notAffected: [] });
+        expect(spawnedLabels(handles)).toEqual(["workspace.compile", "formal"]);
+        expect(handles.github.commitPullRequestsCalls).toHaveLength(0);
+        expect(handles.github.pullRequestCalls).toHaveLength(0);
+      }).pipe(Effect.provide(layer));
+    });
+
+    it.effect("unset: a default-branch push skips before it checks anything out", () => {
+      const { layer, handles } = makeCFRuntimeTest({ sandboxProgram: program });
+      return Effect.gen(function* () {
+        const exit = yield* Effect.exit(contextfulGate.run(heavyInput));
+        expect(Exit.isFailure(exit)).toBe(true);
+        if (Exit.isFailure(exit)) expect(Cause.pretty(exit.cause)).toContain("two-tier gate not configured");
+        expect(handles.sandbox.clones).toEqual([]);
+        expect(handles.childRuns.spawned).toHaveLength(0);
+      }).pipe(Effect.provide(layer));
+    });
+
+    it("triggers once per default-branch head, opted in by the light-label key", () => {
+      const push = contextfulGate.triggers?.[1];
+      expect(push?.event).toBe("push");
+      const payload = {
+        ref: "refs/heads/main",
+        before: BASE_SHA,
+        after: SHA,
+        repository: { full_name: input.repo, default_branch: "main" },
+      };
+      expect(push?.gate?.({ payload } as never)).toBe(true);
+      expect(push?.idempotencyKey?.({ payload } as never)).toBe(`contextful-gate:push:${SHA}`);
+      expect(push?.inputs({ payload } as never)).toEqual(heavyInput);
+      for (const other of [
+        { ...payload, ref: "refs/heads/feature" },
+        { ...payload, ref: "refs/tags/v1.0.0" },
+        { ...payload, after: "0".repeat(40) },
+        { ...payload, before: "0".repeat(40) },
+        { ...payload, repository: { full_name: "other/repo", default_branch: "main" } },
+      ]) {
+        expect(push?.gate?.({ payload: other } as never)).toBe(false);
+      }
+      expect(contextfulGate.optIn?.({ input: heavyInput })).toEqual([LIGHT_KEY]);
+      expect(contextfulGate.optIn?.({ input: { ...input, pr: 42 } })).toEqual([]);
+    });
+
+    it("serializes heavy-tier gates per repo and leaves pull-request gates unserialized", () => {
+      expect(contextfulGate.serialize?.({ ...input, pr: 42 })).toBeUndefined();
+      expect(contextfulGate.serialize?.(heavyInput)).toEqual({
+        group: "contextful-gate:heavy:fractalboxdev/contextful",
+        revision: SHA,
+        current: expect.anything(),
+      });
+      expect(contextfulGate.supersede?.(heavyInput)).toBeUndefined();
+    });
+  });
 });
diff --git a/runs/contextful-gate.ts b/runs/contextful-gate.ts
index 3284dc57..d8a0ef08 100644
--- a/runs/contextful-gate.ts
+++ b/runs/contextful-gate.ts
@@ -27,6 +27,8 @@ import {
 import { check } from "./check";
 
 const REPO = "fractalboxdev/contextful";
+const SHA40 = /^[a-f0-9]{40}$/i;
+const ZERO_SHA = "0".repeat(40);
 const CI_PACKAGE = "contextful-ci";
 const CARGO_RUN_CI = `cargo run --locked -q -p ${CI_PACKAGE} --`;
 const DISCOVER = `${CARGO_RUN_CI} stages --parts`;
@@ -84,6 +86,57 @@ export const parseWindow = (raw: string | undefined): number => {
 export const partCheckName = (stage: string): string => `flare-dispatch/check:${stage}`;
 export const NOT_AFFECTED_SUMMARY = "not affected by this change";
 
+/**
+ * The two-tier gate (specs/adr/0009-fast-trustworthy-verdicts.md § Two-tier
+ * gate). `gate.lightLabels:<repo>` lists the light parts; every other part is
+ * heavy. A pull-request gate runs the light parts, and a push to the default
+ * branch runs the heavy parts once per head. Unset, every part is heavy and a
+ * pull-request gate runs all of them, as it does without the key.
+ */
+export const lightLabelsKey = (repo: string): string => `gate.lightLabels:${repo}`;
+
+/**
+ * The configured light labels: a JSON list of strings or a comma-separated
+ * list. Absent, blank, empty or malformed → `undefined`: every part is heavy.
+ */
+export const parseLightLabels = (raw: string | undefined): readonly string[] | undefined => {
+  const text = raw?.trim() ?? "";
+  if (text === "") return undefined;
+  let labels: readonly string[];
+  if (text.startsWith("[") || text.startsWith("{")) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return undefined;
+    }
+    if (!Array.isArray(parsed) || parsed.some((label) => typeof label !== "string")) return undefined;
+    labels = parsed as string[];
+  } else {
+    labels = text.split(",");
+  }
+  const trimmed = [...new Set(labels.map((label) => label.trim()).filter((label) => label !== ""))];
+  return trimmed.length === 0 ? undefined : trimmed;
+};
+
+/** Which half of a two-tier gate one execution runs. */
+export type GateTier = "pull-request" | "heavy";
+
+/**
+ * The parts one tier dispatches, in plan order. With no light labels a
+ * pull-request gate dispatches every part and the heavy tier none: the split
+ * is off.
+ */
+export const tierParts = (
+  dispatch: readonly string[],
+  lightLabels: readonly string[] | undefined,
+  tier: GateTier,
+): readonly string[] => {
+  if (lightLabels === undefined) return tier === "pull-request" ? dispatch : [];
+  const light = new Set(lightLabels);
+  return dispatch.filter((stage) => light.has(stage) === (tier === "pull-request"));
+};
+
 /** Why a gate stops spawning before every part has run. */
 export type StopReason = "head superseded" | "pull request closed" | "admission backlog";
 
@@ -150,6 +203,10 @@ const Input = Schema.Struct({
    * gate registers first. A reopen adds {@link REOPEN_RANK_OFFSET_MS}.
    */
   revisedAt: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.nonNegative())),
+  /** `heavy`: a push to the default branch, which runs the heavy parts. Absent: a pull-request gate. */
+  tier: Schema.optional(Schema.Literal("heavy")),
+  /** The default branch a heavy-tier push landed on; its head is the serial group's current revision. */
+  branch: Schema.optional(Schema.String),
 });
 
 type InputType = Schema.Schema.Type<typeof Input>;
@@ -265,8 +322,10 @@ export const planStages = (
 
 export const contextfulGate = defineRun({
   name: "contextful-gate",
+  // 1.3.0 — two-tier gate: `gate.lightLabels:<repo>` splits light parts (pull
+  // requests) from heavy parts (pushes to the default branch).
   // 1.2.2 — a reopen ranks above the close marker of its own second.
-  version: "1.2.2",
+  version: "1.3.0",
   inputs: Input,
   outputs: Output,
   triggers: [
@@ -297,7 +356,46 @@ export const contextfulGate = defineRun({
         };
       },
     },
+    {
+      // The heavy tier: one gate per new default-branch head. The receiver
+      // dispatches it only when `gate.lightLabels:<repo>` exists (`optIn`).
+      event: "push",
+      idempotencyKey: ({ payload }) => `contextful-gate:push:${String(payload.after ?? "")}`,
+      gate: ({ payload }) =>
+        payload.repository?.full_name === REPO &&
+        typeof payload.repository?.default_branch === "string" &&
+        payload.ref === `refs/heads/${payload.repository.default_branch}` &&
+        typeof payload.after === "string" && SHA40.test(payload.after) && payload.after !== ZERO_SHA &&
+        typeof payload.before === "string" && SHA40.test(payload.before) && payload.before !== ZERO_SHA,
+      inputs: ({ payload }): InputType => ({
+        repo: REPO,
+        sha: String(payload.after),
+        baseSha: String(payload.before),
+        tier: "heavy",
+        branch: String(payload.repository?.default_branch),
+      }),
+    },
   ],
+  // A pull-request gate reads its light labels in the body and needs no
+  // opt-in; a heavy-tier push exists only for a repo that lists them.
+  optIn: ({ input }) => (input.tier === "heavy" ? [lightLabelsKey(input.repo)] : []),
+  // Heavy-tier gates of one repo never overlap: a newer default-branch head
+  // replaces a waiting older one, and a head that is no longer current skips.
+  serialize: (input) =>
+    input.tier === "heavy"
+      ? {
+          group: `contextful-gate:heavy:${input.repo}`,
+          revision: input.sha,
+          ...(input.branch !== undefined && input.branch !== ""
+            ? {
+                current: github.branchHead({ repo: input.repo, branch: input.branch }).pipe(
+                  Effect.map((sha): string | undefined => sha),
+                  Effect.orElseSucceed(() => undefined),
+                ),
+              }
+            : {}),
+        }
+      : undefined,
   // One gate run per pull request is live: a newer revision cancels the older
   // run, its children and their checks (apps/dispatcher/src/supersede.ts), and
   // the pull request's close cancels the live one (apps/dispatcher/src/pr-close.ts).
@@ -314,6 +412,16 @@ export const contextfulGate = defineRun({
   limits: { maxDurationSec: 30 * 3600, admissionMaxQueueAgeSec: 90 * 60 },
   run: (input) =>
     Effect.gen(function* () {
+      const tier: GateTier = input.tier === "heavy" ? "heavy" : "pull-request";
+      const lightLabels = yield* step("resolve-tiers", () =>
+        config.get(lightLabelsKey(input.repo)).pipe(Effect.map((raw) => parseLightLabels(raw) ?? null)),
+      );
+      // The heavy tier runs only beside a configured light tier.
+      if (tier === "heavy" && lightLabels === null) {
+        return yield* Effect.fail(
+          new RunSkipped({ reason: `two-tier gate not configured — ${lightLabelsKey(input.repo)} is unset` }),
+        );
+      }
       // Discovery runs in the execution's one container, the one its admission
       // slot pays for: head first, then the base in the same checkout, so the
       // base build reuses the head's `target/` and compiles only what differs.
@@ -427,6 +535,8 @@ export const contextfulGate = defineRun({
           }),
         );
       }
+      // This tier's parts. The other tier's parts post no check here.
+      const dispatch = tierParts(plan.dispatch, lightLabels ?? undefined, tier);
 
       // Branch protection requires every part's check: a part the diff cannot
       // reach is posted green under the same name instead of running. Creating
@@ -467,7 +577,7 @@ export const contextfulGate = defineRun({
       // them all before the first fresh read. A part that times out in the
       // admission queue also stops it: the pool is saturated, and further
       // windows would only queue behind the backlog.
-      const queue = [...plan.dispatch];
+      const queue = [...dispatch];
       const running: { readonly stage: string; readonly id: string; readonly expiresAt: number }[] = [];
       const failed = new Set<string>();
       const timedOut: string[] = [];
@@ -489,7 +599,8 @@ export const contextfulGate = defineRun({
           const batch = queue.slice(0, free);
           const spawn = yield* step(`spawn-parts-${spawned}`, () =>
             Effect.gen(function* () {
-              const liveness = yield* readLiveness(input);
+              // A default-branch head has no open pull request to outlive.
+              const liveness = tier === "heavy" ? LIVE : yield* readLiveness(input);
               if (!liveness.live) return { stopped: liveness.reason };
               const handles = yield* fanOut({
                 run: "check",
@@ -561,7 +672,7 @@ export const contextfulGate = defineRun({
         // gate has ended.
         const reason = stopped;
         const unrun = [...queue];
-        const timedOutInOrder = plan.dispatch.filter((stage) => timedOut.includes(stage));
+        const timedOutInOrder = dispatch.filter((stage) => timedOut.includes(stage));
         yield* Effect.forEach(
           unrun,
           (stage) =>
@@ -579,10 +690,10 @@ export const contextfulGate = defineRun({
         );
         if (reason !== "admission backlog") {
           return yield* Effect.fail(
-            new RunSkipped({ reason: `${reason} — ${unrun.length} of ${plan.dispatch.length} parts not run` }),
+            new RunSkipped({ reason: `${reason} — ${unrun.length} of ${dispatch.length} parts not run` }),
           );
         }
-        const failedParts = plan.dispatch.filter((stage) => failed.has(stage));
+        const failedParts = dispatch.filter((stage) => failed.has(stage));
         return yield* Effect.fail(
           new AcceptanceFailed({
             exitCode: 1,
@@ -594,7 +705,7 @@ export const contextfulGate = defineRun({
           }),
         );
       }
-      const failedInOrder = plan.dispatch.filter((stage) => failed.has(stage));
+      const failedInOrder = dispatch.filter((stage) => failed.has(stage));
       if (failedInOrder.length > 0) {
         return yield* Effect.fail(
           new AcceptanceFailed({

From e0a571b8acdef2d5d58cbd76bcfda476942bdd01 Mon Sep 17 00:00:00 2001
From: debuggingfuture <hi@debuggingfuture.com>
Date: Thu, 22 Oct 2026 17:38:43 +0800
Subject: [PATCH 5/5] fix(contextful-gate): name the parts a tier leaves to the
 other one

A two-tier gate's output reported every required part under `stages` while it
ran only one tier's share, so a green pull-request gate read as a full verdict.
The output now lists the affected parts the other tier runs under `deferred`;
with the split off the field is absent and the output is unchanged.
---
 runs/contextful-gate.test.ts | 14 ++++++++++++--
 runs/contextful-gate.ts      | 14 +++++++++++++-
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/runs/contextful-gate.test.ts b/runs/contextful-gate.test.ts
index 7f0b9ae7..d0903429 100644
--- a/runs/contextful-gate.test.ts
+++ b/runs/contextful-gate.test.ts
@@ -1003,7 +1003,12 @@ describe("contextful-gate", () => {
         childRuns: { pollFn: (ids) => ids.map((executionId) => ({ executionId, status: "success" })) },
       });
       return Effect.gen(function* () {
-        expect(yield* contextfulGate.run(input)).toEqual({ stages: 3, failed: [], notAffected: [] });
+        expect(yield* contextfulGate.run(input)).toEqual({
+          stages: 3,
+          failed: [],
+          notAffected: [],
+          deferred: ["workspace.compile"],
+        });
         expect(spawnedLabels(handles)).toEqual(["pins", "formal"]);
         expect(handles.checks.creates).toEqual([]);
       }).pipe(Effect.provide(layer));
@@ -1016,7 +1021,12 @@ describe("contextful-gate", () => {
         childRuns: { pollFn: (ids) => ids.map((executionId) => ({ executionId, status: "success" })) },
       });
       return Effect.gen(function* () {
-        expect(yield* contextfulGate.run(heavyInput)).toEqual({ stages: 3, failed: [], notAffected: [] });
+        expect(yield* contextfulGate.run(heavyInput)).toEqual({
+          stages: 3,
+          failed: [],
+          notAffected: [],
+          deferred: ["pins"],
+        });
         expect(spawnedLabels(handles)).toEqual(["workspace.compile", "formal"]);
         expect(handles.github.commitPullRequestsCalls).toHaveLength(0);
         expect(handles.github.pullRequestCalls).toHaveLength(0);
diff --git a/runs/contextful-gate.ts b/runs/contextful-gate.ts
index d8a0ef08..f68e333e 100644
--- a/runs/contextful-gate.ts
+++ b/runs/contextful-gate.ts
@@ -225,6 +225,12 @@ const Output = Schema.Struct({
   stages: Schema.Number,
   failed: Schema.Array(Schema.String),
   notAffected: Schema.Array(Schema.String),
+  /**
+   * The affected parts this tier left to the other one (two-tier gate only):
+   * the heavy parts on a pull request, the light parts on a default-branch
+   * push. Absent when the split is off.
+   */
+  deferred: Schema.optional(Schema.Array(Schema.String)),
 });
 
 /** A malformed or empty discovery cannot quietly remove required checks. */
@@ -714,6 +720,12 @@ export const contextfulGate = defineRun({
           }),
         );
       }
-      return { stages: plan.required.length, failed: failedInOrder, notAffected: plan.notAffected };
+      const deferred = plan.dispatch.filter((stage) => !dispatch.includes(stage));
+      return {
+        stages: plan.required.length,
+        failed: failedInOrder,
+        notAffected: plan.notAffected,
+        ...(lightLabels === null ? {} : { deferred }),
+      };
     }),
 });